chrome.userScripts

说明

使用 userScripts API 在用户脚本上下文中执行用户脚本。

权限

userScripts

若要使用 chrome.userScripts API，请将 "userScripts" 权限添加到 manifest.json 和要用于运行脚本的网站的 "host_permissions" 中。

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

可用性

Chrome 120 及更高版本 MV3+

概念和用法

用户脚本是注入网页以修改其外观或行为的一小段代码。脚本可以由用户创建，也可以从脚本库或用户脚本扩展程序下载。

扩展程序用户的开发者模式

作为扩展程序开发者，您已在安装的 Chrome 中启用了开发者模式。对于用户脚本扩展程序，您的用户还需要启用开发者模式。以下说明您可以复制并粘贴到您自己的文档中。

  1. 在新标签页中输入 chrome://extensions，前往“扩展程序”页面。（根据设计，chrome:// 网址是不可链接的。）

  2. 点击开发者模式旁边的切换开关，以启用开发者模式。

    “附加信息”页面

    “扩展程序”页面 (chrome://extensions)

您可以通过检查 chrome.userScripts 是否会抛出错误来确定是否已启用开发者模式。例如：

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

在偏僻的世界中工作

用户和内容脚本均可在隔离环境或主环境中运行。隔离环境是一种主机网页或其他扩展程序无法访问的执行环境。这可让用户脚本更改其 JavaScript 环境，而不会影响托管网页或其他扩展程序的用户和内容脚本。反之，用户脚本（和内容脚本）对托管网页或其他扩展程序的用户和内容脚本不可见。在主环境中运行的脚本可供托管网页和其他扩展程序访问，对托管网页和其他扩展程序可见。如需选择世界，请在调用 userScripts.register() 时传递 "USER_SCRIPT" 或 "MAIN"。

如需为 USER_SCRIPT 环境配置内容安全政策，请调用 userScripts.configureWorld()：

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

消息功能

与内容脚本和屏幕外文档一样，用户脚本使用消息功能与扩展程序的其他部分进行通信（也就是说，它们可以像扩展程序的任何其他部分一样调用 runtime.sendMessage() 和 runtime.connect()）。不过，函数是使用专用的事件处理脚本接收的（也就是说，它们不使用 onMessage 或 onConnect）。这些处理程序分别称为 runtime.onUserScriptMessage 和 runtime.onUserScriptConnect。专用处理程序可让用户更轻松地从用户脚本（不太可信的上下文）中识别消息。

在发送消息之前，您必须调用 configureWorld() 并将 messaging 参数设置为 true。请注意，csp 和 messaging 实参可以同时传递。

chrome.userScripts.configureWorld({
  messaging: true
});

扩展程序更新

当扩展程序更新时，系统会清除用户脚本。您可以通过运行扩展程序 Service Worker 的 runtime.onInstalled 事件处理脚本中的代码来重新添加这些容器。仅响应传递给事件回调的 "update" 原因。

示例

此示例来自我们示例代码库中的 userScript 示例。

注册脚本

以下示例展示了对 register() 的基本调用。第一个参数是对象数组，用于定义要注册的脚本。除了此处所示的选项之外，还有更多选项。

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

类型

ExecutionWorld

供用户脚本执行的 JavaScript 环境。

枚举

"MAIN"
指定 DOM 的执行环境，即与托管网页的 JavaScript 共享的执行环境。

"USER_SCRIPT"
会指定用户脚本特有的执行环境，不受网页 CSP 的约束。

RegisteredUserScript

属性

  • allFrames

    布尔值 选填

    如果为 true，该框架将注入所有框架，即使该框架不是标签页中最顶层的框架，也是如此。系统会分别检查每个帧是否符合网址要求；如果不符合网址要求，帧将不会注入到子框架中。默认值为 false，表示仅匹配上层帧。

  • excludeGlobs

    string[] 可选

    指定此用户脚本不会注入到的页面中的通配符格式。

  • excludeMatches

    string[] 可选

    不包括此用户脚本本应被注入的网页。要详细了解这些字符串的语法，请参阅匹配模式。

  • id

    string

    在 API 调用中指定的用户脚本的 ID。此属性不得以“_”开头，因为它已预留为生成的脚本 ID 的前缀。

  • includeGlobs

    string[] 可选

    用于指定要将此用户脚本注入到的页面中的通配符格式。

  • ScriptSource 对象列表，这些对象用于定义要注入到匹配页面的脚本来源。

  • 匹配

    string[] 可选

    指定此用户脚本将注入到哪些页面。要详细了解这些字符串的语法，请参阅匹配模式。必须为 ${ref:register} 指定此属性。

  • runAt

    RunAt 可选

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

  • 全球

    ExecutionWorld（可选）

    用于运行脚本的 JavaScript 执行环境。默认值为 `USER_SCRIPT`。

ScriptSource

属性

  • 验证码

    字符串（可选）

    包含要注入的 JavaScript 代码的字符串。必须指定 file 和 code 中的一个。

  • 文件

    字符串（可选）

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

UserScriptFilter

属性

  • ids

    string[] 可选

    getScripts 仅返回具有此列表中指定的 ID 的脚本。

WorldProperties

属性

  • CSP

    字符串（可选）

    指定全球 CSP。默认是 `ISOLATED` 世界 CSS。

  • 消息功能

    布尔值 选填

    指定是否公开消息传递 API。默认值为 false。

方法

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

配置 `USER_SCRIPT` 执行环境。

参数

  • 媒体资源

    WorldProperties

    包含用户脚本环境配置。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

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

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

返回此扩展程序的所有动态注册的用户脚本。

参数

返回

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

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

为此扩展程序注册一个或多个用户脚本。

参数

  • 包含要注册的用户脚本列表。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

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

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

取消注册此扩展程序的所有动态注册的用户脚本。

参数

  • filter

    UserScriptFilter 可选

    如果指定，则此方法仅取消注册与其匹配的用户脚本。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

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

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

更新此扩展程序的一个或多个用户脚本。

参数

  • 包含要更新的用户脚本列表。仅当在此对象中指定了现有脚本的属性时，系统才会更新该属性。如果脚本解析/文件验证过程中出错，或者指定的 ID 与完全注册的脚本不对应，则系统不会更新任何脚本。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

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