chrome.userScripts

说明

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

权限

userScripts

若要使用 chrome.userScripts API，请向您的 manifest.json 和 "host_permissions" 添加 "userScripts" 权限，以便运行脚本的网站。

{
  "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. 点击开发者模式旁边的切换开关以启用开发者模式。

   

   <ph type="x-smartling-placeholder">

   </ph> “扩展程序”页面 (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

  字符串

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

• includeGlobs

  string[] 选填

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

• js

  ScriptSource[]

  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。默认值为 `ISOLATED` 世界 csp。

• 消息

  布尔值（可选）

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

方法

configureWorld()

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

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

配置 `USER_SCRIPT` 执行环境。

参数

• 媒体资源

  WorldProperties

  包含用户脚本世界配置。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

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

getScripts()

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

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

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

参数

• filter

  UserScriptFilter 可选

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

• callback

  函数（可选）

  callback 参数如下所示：

  (scripts: RegisteredUserScript[]) => void

  • 脚本

    RegisteredUserScript[]

返回

• Promise&lt;RegisteredUserScript[]&gt;

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

register()

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

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

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

参数

• 脚本

  RegisteredUserScript[]

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

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

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

unregister()

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

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

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

参数

• filter

  UserScriptFilter 可选

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

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

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

update()

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

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

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

参数

• 脚本

  RegisteredUserScript[]

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

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

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