此页面由 Cloud Translation API 翻译。

chrome.scripting

说明

使用 chrome.scripting API 在不同上下文中执行脚本。

权限

scripting

可用性

Chrome 88 及更高版本 MV3+

清单

如需使用 chrome.scripting API，请在清单中声明 "scripting" 权限，以及要将脚本注入的网页的主机权限。使用 "host_permissions" 密钥或 "activeTab" 权限（用于授予临时主机权限）。以下示例使用 activeTab 权限。

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

概念和用法

您可以使用 chrome.scripting API 将 JavaScript 和 CSS 注入。这与您可以对内容执行的操作类似脚本。但通过使用 chrome.scripting 命名空间，扩展可以在运行时做出决策。

注入目标

您可以使用 target 参数指定要注入 JavaScript 的目标，或 CSS 导入。

唯一的必填字段是 tabId。默认情况下，注入会在指定标签页的主框架

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

如需在指定标签页的所有帧中运行，您可以设置 allFrames 布尔值至 true。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

您还可以通过指定单个帧，注入到某个标签页的特定帧中。如需详细了解帧 ID，请参阅 chrome.webNavigation API。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

注意：您不能同时指定 "frameIds" 和 "allFrames" 属性。

注入的代码

扩展程序可以指定要通过外部文件或运行时变量。

文件

文件指定为字符串，且路径是相对于扩展程序根目录的路径目录。以下代码会将文件 script.js 注入主标签页的框架中。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

运行时函数

使用 scripting.executeScript() 注入 JavaScript 时，您可以指定函数（而不是文件）。此函数应为函数变量。

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

您可以使用 args 属性解决此问题：

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

运行时字符串

如果在网页中注入 CSS，您还可以指定要在 css 属性。此选项仅适用于 scripting.insertCSS()；您无法使用 scripting.executeScript() 执行字符串。

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

处理结果

JavaScript 的执行结果会传递给扩展程序。单个结果包含的图片数量主框架一定会是结果数组；所有其他帧的顺序则不确定。

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() 不会返回任何结果。

promise

如果脚本执行的结果值为 promise，则 Chrome 会等待来让 promise 得到解决并返回结果值。

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

示例

取消注册所有动态内容脚本

以下代码段包含一个用于取消注册所有动态内容的函数脚本。

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts(scriptIds);
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

如需试用 chrome.scripting API，请执行以下操作：安装 Chrome 扩展程序示例中的脚本示例存储库

类型

ContentScriptFilter

Chrome 96 及更高版本

属性

ids

string[] 选填

如果指定，getRegisteredContentScripts 将仅返回具有此列表中指定的 ID 的脚本。

CSSInjection

属性

css

字符串（可选）

包含要注入的 CSS 的字符串。必须指定 files 和 css 中的一个。
文件

string[] 选填

要注入的 CSS 文件的路径（相对于扩展程序的根目录）。必须指定 files 和 css 中的一个。
源

StyleOrigin 可选

注入的样式来源。默认为 'AUTHOR'。
目标

InjectionTarget

用于指定要插入 CSS 的目标的详情。

ExecutionWorld

Chrome 95 及更高版本

用于执行脚本的 JavaScript 环境。

枚举

"ISOLATED"
指定隔离世界，即此扩展程序所独有的执行环境。

"MAIN"
指定 DOM 的主域，也就是与托管页面的 JavaScript 共享的执行环境。

InjectionResult

属性

documentId

字符串

Chrome 106 及更高版本

与注射相关的文档。
frameId

number

Chrome 90 及更高版本

与注入关联的帧。
结果

任何选填字段

脚本执行的结果。

InjectionTarget

属性

allFrames

布尔值（可选）

是否应将脚本注入标签页内的所有帧。默认值为 false。如果指定了 frameIds，则此字段不得为 true。
documentIds

string[] 选填

Chrome 106 及更高版本

要注入到的特定 documentId 的 ID。如果设置了 frameIds，则不得设置此字段。
frameIds

number[]（选填）

要注入到的特定帧的 ID。
tabId

number

要注入的标签页的 ID。

RegisteredContentScript

Chrome 96 及更高版本

属性

allFrames

布尔值（可选）

如果指定 true，该帧会注入所有帧，即使该帧不是标签页中最顶部的帧也不例外。系统会分别检查每一帧，以确定其是否符合网址要求；如果不符合网址要求，则不会注入到子框架中。默认设置为 false，表示仅匹配顶部的帧。
css

string[] 选填

要注入到匹配页面的 CSS 文件列表。在为网页构建或显示任何 DOM 之前，这些变量会按照它们在此数组中出现的顺序进行注入。
excludeMatches

string[] 选填

不包括这些内容脚本本来会被注入的网页。如需详细了解这些字符串的语法，请参阅匹配模式。
id

字符串

在 API 调用中指定的内容脚本的 ID。不得以“_”开头因为它已预留为生成的脚本 ID 的前缀。
js

string[] 选填

要注入到匹配页面的 JavaScript 文件的列表。这些变量按其在此数组中显示的顺序注入。
matchOriginAsFallback

布尔值（可选）

Chrome 119 及更高版本

指明脚本是否可以注入到网址包含不受支持的架构的框架中；例如 about:、data:、blob: 或 filesystem:。在这些情况下，系统会检查网址的来源，以确定是否应注入脚本。如果源为 null（如 data: 网址s 所示），则使用的来源要么是创建当前帧的帧，要么是启动到此帧的导航操作。请注意，这可能不是父框架。
匹配

string[] 选填

指定要将此内容脚本注入哪些页面。如需详细了解这些字符串的语法，请参阅匹配模式。必须为 registerContentScripts 指定。
persistAcrossSessions

布尔值（可选）

指定此内容脚本是否会持续到将来的会话中。默认值为 true。
runAt

RunAt 可选

指定何时将 JavaScript 文件注入网页。首选默认值为 document_idle。
全球

ExecutionWorld 可选

Chrome 浏览器 102 或更高版本

JavaScript“世界”来运行该脚本默认为 ISOLATED。

ScriptInjection

属性

args

any[] 选填

Chrome 92 或更高版本

要传递给所提供函数的参数。这仅在指定了 func 参数时有效。这些参数必须可进行 JSON 序列化。
文件

string[] 选填

要注入的 JS 或 CSS 文件的路径（相对于扩展程序的根目录）。必须且只能指定 files 和 func 中的一个。
injectImmediately

布尔值（可选）

Chrome 浏览器 102 或更高版本

是否应尽快在目标中触发注入。请注意，这并不保证注入会在网页加载之前发生，因为网页可能在脚本到达目标时就已经加载了。
目标

InjectionTarget

用于指定脚本注入目标的详细信息。
全球

ExecutionWorld 可选

Chrome 95 及更高版本

JavaScript“世界”来运行该脚本默认为 ISOLATED。
func

void 选填

Chrome 92 或更高版本

要注入的 JavaScript 函数。此函数会先序列化，然后反序列化以进行注入。这意味着所有绑定参数和执行上下文都将丢失。必须且只能指定 files 和 func 中的一个。

func 函数如下所示：
```
() => {...}
```

StyleOrigin

样式更改的原点。如需了解详情，请参阅样式来源。

枚举

“AUTHOR”

“USER”

方法

executeScript()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

将脚本注入目标上下文。默认情况下，脚本将在 document_idle 运行，如果页面已加载，则立即运行。如果设置了 injectImmediately 属性，即使页面尚未加载完毕，脚本也会在不等待的情况下注入。如果脚本的计算结果为 promise，则浏览器将等待 promise 产生结果，并返回结果值。

参数

注入

ScriptInjection

要注入的脚本的详细信息。
callback

函数（可选）

callback 参数如下所示：
```
(results: InjectionResult[]) => void
```
- 结果
  
  InjectionResult[]

Promise<InjectionResult[]>

Chrome 90 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getRegisteredContentScripts()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 96 及更高版本

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

返回此扩展程序与指定过滤条件匹配的所有动态注册的内容脚本。

参数

filter

ContentScriptFilter 可选

用于过滤扩展程序动态注册脚本的对象。
callback

函数（可选）

callback 参数如下所示：
```
(scripts: RegisteredContentScript[]) => void
```
- 脚本
  
  RegisteredContentScript[]

Promise<RegisteredContentScript[]>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

insertCSS()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

将 CSS 样式表插入目标上下文。如果指定了多个帧，失败的注入会被忽略。

参数

注入

CSSInjection

要插入的样式的详情。
callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Chrome 90 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

registerContentScripts()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 96 及更高版本

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

为此扩展程序注册一个或多个内容脚本。

参数

脚本

RegisteredContentScript[]

包含要注册的脚本列表。如果脚本解析/文件验证期间出错，或者指定的 ID 已存在，则不会注册任何脚本。
callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

removeCSS()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 90 及更高版本

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

从目标上下文中移除此扩展程序之前插入的 CSS 样式表。

参数

注入

CSSInjection

要移除的样式的详情。请注意，css、files 和 origin 属性必须与通过 insertCSS 插入的样式表完全匹配。尝试移除不存在的样式表属于空操作。
callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

unregisterContentScripts()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 96 及更高版本

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

取消注册此扩展程序的内容脚本。

参数

filter

ContentScriptFilter 可选

如果已指定，则仅取消注册与过滤条件匹配的动态内容脚本。否则，该扩展程序的所有动态内容脚本都会被取消注册。
callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

updateContentScripts()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 96 及更高版本

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

更新此扩展程序的一个或多个内容脚本。

参数

脚本

RegisteredContentScript[]

包含要更新的脚本列表。只有在此对象中指定了某个属性时，系统才会为现有脚本更新该属性。如果脚本解析/文件验证期间出现错误，或者指定的 ID 与完全注册的脚本不一致，那么系统不会更新任何脚本。
callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。