清单 - 内容脚本

"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" - 数组，
可选。一个 JavaScript 文件路径数组，在注入 CSS 文件后，按照它们在此数组中出现的顺序注入。数组中的每个字符串都必须是相对于扩展程序根目录中资源的相对路径。前导斜杠 ('/') 会自动剪裁。

匹配网址

只有 "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。 脚本是否应注入到父级网址与 "matches" 中声明的某个格式匹配的 about:blank 框架中。
"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 共享执行环境。如需了解详情，请参阅在隔离的世界中工作。

示例

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