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&lt;InjectionResult[]&gt;

  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&lt;RegisteredContentScript[]&gt;

  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 使用传递给回调的类型进行解析。