chrome.userScripts

说明

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

权限

userScripts

如需使用 chrome.userScripts API，请向 manifest.json 添加 "userScripts" 权限，并为您要运行脚本的网站添加 "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
});

扩展程序更新

扩展程序更新时，用户脚本会被清除。您可以通过在扩展程序服务工作器的 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

  字符串

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

• includeGlobs

  string[] 可选

  为要注入此用户脚本的网页指定通配符模式。

• js

  ScriptSource[] 可选

  定义要注入到匹配网页中的脚本来源的 ScriptSource 对象列表。必须为 ${ref:register} 指定此属性，并且在指定时，该属性必须为非空数组。

• 匹配

  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` 世界 csp。

• 消息传递

  布尔值（可选）

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

方法

configureWorld()

prometido

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

配置 `USER_SCRIPT` 执行环境。

参数

• 媒体资源

  WorldProperties

  包含用户脚本世界配置。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getScripts()

prometido

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

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

参数

• filter

  UserScriptFilter（可选）

  如果指定了此参数，此方法将仅返回与其匹配的用户脚本。

• callback

  函数（可选）

  callback 参数如下所示：

  (scripts: RegisteredUserScript[]) => void

  • 脚本

    RegisteredUserScript[]

返回

• Promise<RegisteredUserScript[]>RegisteredUserScript

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

register()

prometido

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

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

参数

• 脚本

  RegisteredUserScript[]

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

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

unregister()

prometido

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

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

参数

• filter

  UserScriptFilter（可选）

  如果指定了此参数，此方法只会取消注册与其匹配的用户脚本。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

update()

prometido

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

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

参数

• 脚本

  RegisteredUserScript[]

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

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。