"content_scripts"
键会指定一个静态加载的 JavaScript 或 CSS 文件,以供每次用户打开符合特定网址格式的网页时使用。扩展程序还可以以编程方式注入内容脚本,请参阅注入脚本了解详情。
清单
这些是 "content_scripts"
支持的键。只有 "matches"
键以及 "js"
或 "css"
是必需的。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"],
"exclude_matches": ["*://*/*foo*"],
"include_globs": ["*example.com/???s/*"],
"exclude_globs": ["*bar*"],
"all_frames": false,
"match_origin_as_fallback": false,
"match_about_blank": false,
"run_at": "document_idle",
"world": "ISOLATED",
}
],
...
}
文件
每个文件都必须包含扩展程序根目录中某项资源的相对路径。系统会自动剪除前导斜杠 (/
)。"run_at"
键指定何时注入每个文件。
"css"
- 数组- 可选。CSS 文件路径数组,按此数组的顺序注入,并会在任何 DOM 构建或页面呈现发生之前进行。
"js"
- 数组,- 可选。注入 CSS 文件后,会按在此数组中出现的顺序注入的 JavaScript 文件路径数组。数组中的每个字符串都必须是扩展程序根目录中某项资源的相对路径。系统会自动剪掉前导斜杠(“/”)。
匹配网址
只有 "matches"
属性是必需的。然后,您可以使用 "exclude_matches"
、"include_globs"
和 "exclude_globs"
自定义要向哪些网址注入代码。"matches"
键将触发警告。
"matches"
- 数组- 必需。指定要将内容脚本注入到哪些网址格式。有关语法,请参阅匹配模式。
"exclude_matches"
- 数组- 可选。不包括要将内容脚本注入到的网址格式。有关语法,请参阅匹配模式。
"include_globs"
- 数组- 可选。在匹配项之后应用,以仅包含也与此 glob 匹配的网址。用于模拟 @include Greasemonkey 关键字。
"exclude_globs"
- 数组- 可选。在匹配项之后应用,以排除与此 glob 匹配的网址。用于模拟 @Exclude Greasemonkey 关键字。
glob 网址是指包含“通配符”* 和问号的网址。通配符 * 可匹配任意长度(包括空字符串)的任何字符串,而问号 ?匹配任意单个字符。
在以下情况下,内容脚本会注入到网页中:
- 该网址与任意
"matches"
和"include_globs"
格式匹配。 - 并且网址不符合
"exclude_matches"
或"exclude_globs"
格式。
glob 和网址匹配示例
"include_globs"
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"include_globs": ["https://???.example.com/foo/*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/foo/bar https://the.example.com/foo/
https://my.example.com/foo/bar https://example.com/foo/* https://www.example.com/foo
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"include_globs": ["*example.com/???s/*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/arts/index.html https://www.example.com/jobs/index.html
https://www.example.com/sports/index.html https://www.example.com/music/index.html
"exclude_globs"
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"exclude_globs": ["*science*"],
"js": ["content-script.js"]
}
],
...
}
https://history.example.com https://.example.com/music
https://science.example.com https://www.example.com/science
高级自定义示例
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"exclude_matches": ["*://*/*business*"],
"include_globs": ["*example.com/???s/*"],
"exclude_globs": ["*science*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/arts/index.html https://.example.com/jobs/index.html
https://science.example.com https://www.example.com/jobs/business https://www.example.com/science
帧
"all_frames"
键用于指定是否应将内容脚本注入符合指定网址要求的所有帧。如果设置为 false
,它将仅注入到最顶层的帧。它可以与 "match_about_blank"
搭配使用,注入到 about:blank
帧中。
如需注入到 data:
、blob:
和 filesystem:
等其他帧中,请将 "match_origin_as_fallback"
设置为 true
。如需了解详情,请参阅注入相关帧
"all_frames"
布尔值- 可选。默认值为
false
,表示仅匹配上层帧。如果设为 true,该帧会注入到所有帧中,即使相应帧不是标签页中最顶层的帧也是如此。系统会分别检查每个帧是否符合网址要求,如果不符合网址要求,帧将不会注入到子框架中。 "match_about_blank"
- 布尔值- 可选。默认值为
false
。脚本是否应注入到about:blank
框架中,其中父网址与"matches"
中声明的某个格式匹配。 "match_origin_as_fallback"
- 布尔值- 可选。默认值为
false
。脚本是否应注入由匹配的来源创建的帧,但其网址或来源可能与模式不直接匹配。其中包括具有不同架构的帧,例如about:
、data:
、blob:
和filesystem:
。
运行时和执行环境
默认情况下,内容脚本会在文档和所有资源加载完毕后进行注入,并且会位于网页或其他扩展程序无法访问的专用隔离执行环境中。您可以通过以下键更改这些默认值:
"run_at"
-document_start
|document_end
|document_idle
- 可选。指定何时应将脚本注入到网页中。它与 Document.readyState 的加载状态相对应:
"document_start"
:DOM 仍在加载。"document_end"
:网页的资源仍在加载"document_idle"
:DOM 和资源已加载完毕。这是默认值。
"world"
-ISOLATED
|MAIN
- 可选。用于执行脚本的 JavaScript 环境。默认为
"ISOLATED"
,这是内容脚本独有的执行环境。如果选择"MAIN"
环境,脚本将与托管网页的 JavaScript 共享执行环境。如需了解详情,请参阅在隔离的世界中工作。
示例
要构建一个可在清单中注入内容脚本的扩展程序,请参阅在每个网页上运行教程。