清单 - 内容脚本

"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 匹配的网址。旨在模拟 @excluded 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。脚本是否应注入到父网址与 "matches" 中声明的某个格式匹配的 about:blank 帧中。
"match_origin_as_fallback" - 布尔值
可选。默认值为 false。脚本是否应注入由匹配源创建但其网址或源可能与格式不直接匹配的帧。这包括采用不同架构的帧，例如 about:、data:、blob: 和 filesystem:。

运行时和执行环境

默认情况下，系统会在文档及所有资源加载完毕后注入内容脚本，并将其置于网页或其他扩展程序无法访问的专用隔离执行环境中。您可以通过以下键更改这些默认值：

"run_at" - document_start |document_end |document_idle
可选。指定应在何时将脚本注入网页。它对应于 Document.readyState 的加载状态： <ph type="x-smartling-placeholder">
    </ph>
  • "document_start"：DOM 仍在加载。
  • "document_end"：网页的资源仍在加载
  • "document_idle"：DOM 和资源已加载完毕。这是默认值。
"world" - ISOLATED |MAIN
可选。用于执行脚本的 JavaScript 环境。默认值为 "ISOLATED"，这是内容脚本独有的执行环境。选择 "MAIN" 域意味着脚本将与托管页面的 JavaScript 共享执行环境。如需了解详情，请参阅在隔离的世界中工作。
。

示例

如需构建可在清单中注入内容脚本的扩展程序，请参阅在每个网页上运行教程。