说明
使用 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 中启用了开发者模式。对于用户脚本扩展程序,您的用户还需要启用开发者模式。以下说明您可以复制并粘贴到您自己的文档中。
- 在新标签页中输入
chrome://extensions
,前往“扩展程序”页面。(根据设计,chrome://
网址是不可链接的。) 点击开发者模式旁边的切换开关,以启用开发者模式。
您可以通过检查 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[] 可选
用于指定要将此用户脚本注入到的页面中的通配符格式。
-
js
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()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
配置 `USER_SCRIPT`
执行环境。
参数
-
媒体资源
包含用户脚本环境配置。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
返回此扩展程序的所有动态注册的用户脚本。
参数
-
filter
如果指定,则此方法仅返回与其匹配的用户脚本。
-
callback
函数(可选)
callback
参数如下所示:(scripts: RegisteredUserScript[]) => void
-
脚本
-
返回
-
Promise<RegisteredUserScript[]>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
为此扩展程序注册一个或多个用户脚本。
参数
-
脚本
包含要注册的用户脚本列表。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
取消注册此扩展程序的所有动态注册的用户脚本。
参数
-
filter
如果指定,则此方法仅取消注册与其匹配的用户脚本。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
更新此扩展程序的一个或多个用户脚本。
参数
-
脚本
包含要更新的用户脚本列表。仅当在此对象中指定了现有脚本的属性时,系统才会更新该属性。如果脚本解析/文件验证过程中出错,或者指定的 ID 与完全注册的脚本不对应,则系统不会更新任何脚本。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。