tabs.executeScript()

将 JavaScript 代码注入页面。

注意：使用清单 V3 或更高版本时，使用 scripting.executeScript() 来执行脚本。

你可以将代码注入到可以使用匹配模式表达其 URL 的页面中。为此，其方案必须是以下之一：http、https 或 file。

你必须拥有页面的 URL 的权限——要么是明确的权限，如主机权限——要么是通过 activeTab 权限。请注意，某些特殊页面不允许此权限，包括阅读器视图、视图来源和 PDF 查看器页面。

你还可以将代码注入到与你的扩展一起打包的页面中

browser.tabs.create({ url: "/my-page.html" }).then(() => {
  browser.tabs.executeScript({
    code: `console.log('location:', window.location.href);`,
  });
});

执行此操作不需要任何特殊权限。

你不能将代码注入到任何浏览器的内置页面中，例如：about:debugging、about:addons 或当你打开一个新的空标签页时打开的页面。

你注入的脚本称为内容脚本。

这是一个异步函数，它返回一个 Promise。

语法

let executing = browser.tabs.executeScript(
  tabId,                 // optional integer
  details                // object
)

参数

tabId 可选

integer。要运行脚本的标签的 ID。

默认为当前窗口的活动标签。

details

一个描述要运行的脚本的对象。

它包含以下属性

allFrames 可选

boolean。如果为 true，则代码将被注入到当前页面的所有帧中。

如果为 true 且 frameId 已设置，则会引发错误。（frameId 和 allFrames 互斥。）

如果为 false，则代码仅被注入到顶层帧中。

默认为 false。

code 可选

string。要注入的代码，作为文本字符串。

警告：不要使用此属性将不受信任的数据插入 JavaScript 中，因为这会导致安全问题。

file 可选

string。包含要注入的代码的文件的路径。

在 Firefox 中，未从扩展根目录开始的相对 URL 会相对于当前页面 URL 解析。
在 Chrome 中，这些 URL 会相对于扩展的基 URL 解析。

为了跨浏览器工作，你可以将路径指定为一个从扩展根目录开始的相对 URL，例如："/path/to/script.js"。

frameId 可选

integer。要注入代码的帧。

默认为 0（顶层帧）。

matchAboutBlank 可选

boolean。如果为 true，如果你的扩展有权访问其父文档，则代码将被注入到嵌入的 about:blank 和 about:srcdoc 帧中。代码不能插入到顶层的 about: 帧中。

默认为 false。

runAt 可选

extensionTypes.RunAt。代码最早被注入到标签中的时间。

默认为 "document_idle"。

返回值

一个将解析为对象数组的 Promise。数组的值代表在每个注入帧中脚本的结果。

脚本的结果是最后执行的语句，这类似于你在网页控制台中执行脚本时会输出的内容（结果，而不是任何 console.log() 输出）。例如，考虑如下脚本

let foo = "my result";
foo;

这里结果数组将包含字符串 "my result" 作为元素。

结果值必须是结构化可克隆的（请参阅数据克隆算法）。

注意：最后一个语句也可能是一个 Promise，但此功能不受 webextension-polyfill 库支持。

如果发生任何错误，则 promise 将被拒绝，并显示错误消息。

示例

此示例在当前活动标签中执行一个单行代码段

function onExecuted(result) {
  console.log(`We made it green`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const makeItGreen = 'document.body.style.border = "5px solid green"';

const executing = browser.tabs.executeScript({
  code: makeItGreen,
});
executing.then(onExecuted, onError);

此示例执行一个名为 "content-script.js" 的文件（与扩展打包在一起）中的脚本。该脚本在当前活动标签中执行。该脚本在子帧以及主文档中执行

function onExecuted(result) {
  console.log(`We executed in all subframes`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const executing = browser.tabs.executeScript({
  file: "/content-script.js",
  allFrames: true,
});
executing.then(onExecuted, onError);

此示例执行一个名为 "content-script.js" 的文件（与扩展打包在一起）中的脚本。该脚本在 ID 为 2 的标签中执行

function onExecuted(result) {
  console.log(`We executed in tab 2`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const executing = browser.tabs.executeScript(2, {
  file: "/content-script.js",
});
executing.then(onExecuted, onError);

扩展示例

浏览器兼容性

BCD 表仅在启用了 JavaScript 的浏览器中加载。

注意：此 API 基于 Chromium 的 chrome.tabs API。此文档源自 Chromium 代码中的 tabs.json。