title | slug | l10n | ||
---|---|---|---|---|
tabs.executeScript() |
Mozilla/Add-ons/WebExtensions/API/tabs/executeScript |
|
{{AddonSidebar}}
向页面注入 JavaScript 代码。
Note
当使用 Manifest V3 或更高版本时,请使用 {{WebExtAPIRef("scripting.executeScript()")}} 来执行脚本。
你可以将代码注入到其 URL 可以用匹配模式表示的页面中。为此,其协议必须是以下之一:http
、https
或 file
。
你必须拥有页面 URL 的权限。无论是明确的主机权限,还是通过 activeTab 权限。请注意,一些特殊页面不允许此权限,包括阅读器视图、view-source 以及 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, // 可选整数
details // 对象
)
-
tabId
{{optional_inline}}-
:
integer
。要运行脚本的标签页的 ID。默认为当前窗口的活动标签页。
-
-
details
-
: 描述要运行的脚本的对象。
它包含以下属性:
-
allFrames
{{optional_inline}}-
:
boolean
。如果为true
,代码将注入到当前页面的所有框架中。如果为
true
并且设置了frameId
,则会引发错误。(frameId
和allFrames
是互斥的。)如果为
false
,代码仅注入到顶层框架中。默认为
false
。
-
-
code
{{optional_inline}}-
:
string
。要注入的代码,作为文本字符串。[!WARNING] 不要使用此属性将不受信任的数据插入 JavaScript,因为这可能会导致安全问题。
-
-
file
{{optional_inline}}-
:
string
。包含要注入代码的文件的路径。- 在 Firefox 中,不从扩展根目录开始的相对 URL 相对于当前页面 URL 解析。
- 在 Chrome 中,这些 URL 相对于扩展的根 URL 解析。
为了跨浏览器工作,可以指定从扩展根目录开始的相对 URL,如:
"/path/to/script.js"
。
-
-
frameId
{{optional_inline}}-
:
integer
。应注入代码的框架。默认为
0
(顶层框架)。
-
-
matchAboutBlank
{{optional_inline}}-
:
boolean
。如果为true
,且你的扩展具有访问其父文档的权限,代码将注入到内嵌的about:blank
和about:srcdoc
框架中。代码不能注入到顶层about:
框架中。默认为
false
。
-
-
runAt
{{optional_inline}}-
: {{WebExtAPIRef('extensionTypes.RunAt')}}。代码将在标签页中注入的最早时间。
默认为
"document_idle"
。
-
-
-
一个 Promise
,其会兑现一个对象数组。数组的值表示脚本在每个注入框架中的结果。
脚本的结果是最后评估的语句,这类似于如果在 Web 控制台中执行脚本时输出的结果(不是任何 console.log()
的输出)。例如,考虑这样的脚本:
let foo = "my result";
foo;
在这里,结果数组将包含字符串 "my result"
作为元素。
Note
最后一个语句也可能是一个 Promise
,但 webextension-polyfill 库不支持此功能。
如果发生任何错误,则该 promise 将被拒绝并带有错误消息。
此示例在当前活动标签页中执行一行代码片段:
function onExecuted(result) {
console.log(`我们把它变绿了`);
}
function onError(error) {
console.log(`发生错误:${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(`我们在所有子框架中执行了`);
}
function onError(error) {
console.log(`发生错误:${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(`我们在标签页 2 中执行了`);
}
function onError(error) {
console.log(`发生错误:${error}`);
}
const executing = browser.tabs.executeScript(2, {
file: "/content-script.js",
});
executing.then(onExecuted, onError);
{{WebExtExamples}}
{{Compat}}
Note
此 API 基于 Chromium 的 chrome.tabs
API。此文档源自 Chromium 代码中的 tabs.json
。