1. Mozilla
  2. 附加组件
  3. 浏览器扩展
  4. manifest.json
  5. content_scripts

content_scripts

类型 Array
必填 否
Manifest 版本 2 或更高
示例
json
"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["borderify.js"]
  }
]

指示浏览器将 内容脚本 加载到 URL 与指定模式匹配的网页中。

此键是一个数组。每个项目都是一个对象，该对象

  • 必须 包含一个名为 matches 的属性，该属性指定要加载脚本的 URL 模式；
  • 可以 包含名为 js 和 css 的属性，这些属性列出了要加载到匹配页面中的脚本和样式表；并且
  • 可以 包含一些其他属性，用于控制内容脚本的加载方式和时机。

此表详细介绍了您可以包含的所有属性。

名称 类型 描述
all_frames Boolean
true

将 js 和 css 中指定的脚本注入到所有符合指定 URL 要求的框架中，即使该框架不是标签页中的最顶层框架。这不会注入到仅其父级匹配 URL 要求而子级不匹配 URL 要求的子框架中。URL 要求会独立检查每个框架。

注意：这也适用于任何使用 iframe 的跟踪器或广告，这意味着启用此选项可能会导致某些页面的内容脚本被调用数十次。

false
仅将脚本注入到符合 URL 要求的、标签页中最顶层的框架中。

默认为 false。
css Array

一个相对于 manifest.json 的路径数组，引用要注入到匹配页面中的 CSS 文件。有关文件注入顺序的信息，请参阅 加载顺序。

注意： Firefox 会相对于 CSS 文件本身解析注入的 CSS 文件中的 URL，而不是相对于其注入到的页面。
css_origin
可选 		String

CSS 注入的样式来源

  • "user"，作为用户样式表添加。
  • "author"，作为作者样式表添加。
默认为 "author"。

此属性在 Firefox 和 Safari 中对大小写不敏感。
exclude_globs Array 一个包含通配符的字符串数组。请参阅下面的 匹配 URL 模式。
exclude_matches Array 一个 匹配模式 数组。请参阅下面的 匹配 URL 模式。
include_globs Array 一个包含通配符的字符串数组。请参阅下面的 匹配 URL 模式。
js Array

一个相对于 manifest.json 的路径数组，引用要注入到匹配页面中的 JavaScript 文件。有关文件注入顺序的信息，请参阅 加载顺序。
match_about_blank Boolean

将内容脚本插入到 URL 为 "about:blank" 或 "about:srcdoc" 的页面中，前提是打开或创建此页面的页面的 URL 匹配 content_scripts 键中其余部分指定的模式。

这对于在 URL 为 "about:blank" 的空 iframe 中运行脚本特别有用。要做到这一点，您还应该设置 all_frames 键。

例如，假设您有如下 content_scripts 键：

json
  "content_scripts": [
    {
      "js": ["my-script.js"],
      "matches": ["https://example.org/"],
      "match_about_blank": true,
      "all_frames": true
    }
  ]

如果用户加载 https://example.org/，并且该页面嵌入了一个空 iframe，那么 "my-script.js" 将被加载到该 iframe 中。

注意： 从 Firefox 52 版本开始支持 match_about_blank。

请注意，在 Firefox 中，即使您在 run_at 中指定了该值，内容脚本也不会在 "document_start" 时注入到空 iframe 中。
match_origin_as_fallback Boolean 如果为 true，则在 about:、data: 和 blob: 页面的来源与 matches 中的模式匹配时，即使文档来源不透明（由于使用了 CSP 或 iframe 沙箱），代码也会被注入。matches 中的匹配模式必须指定一个通配符路径 glob。默认为 false。
matches Array

一个 匹配模式 数组。请参阅下面的 匹配 URL 模式。

这是唯一必需的键。
run_at String

此选项确定 css 和 js 中指定的文件注入时间。您可以提供以下三个字符串之一，每个字符串都标识了文档加载过程中的一个状态。这些状态直接对应于 Document.readyState

"document_start"
对应于 loading。DOM 仍在加载中。
"document_end"
对应于 interactive。DOM 加载已完成，但脚本和图像等资源可能仍在加载中。
"document_idle"
对应于 complete。文档及其所有资源已加载完成。

默认值为 "document_idle"。

在所有情况下，js 中的文件都在 css 中的文件之后注入。
world String

脚本执行的 JavaScript 世界。

"ISOLATED"
默认的 内容脚本 执行环境。此环境与页面的上下文隔离：尽管它们共享相同的文档，但全局作用域和可用的 API 不同。
"MAIN"
网页的执行环境。此环境与网页共享，没有隔离。此环境中的脚本无法访问仅内容脚本可用的 API。

警告：由于缺乏隔离，网页可以检测并干扰正在执行的代码。除非网页可以读取、访问或修改通过已执行代码流逻辑或数据，否则请勿使用 MAIN 世界。

默认值为 "ISOLATED"。

加载顺序

content_scripts 中的已注册对象会在 run_at 指定的时间（先 document_start，然后 document_end，最后 document_idle）注入到匹配的网页中。

  • 按照 content_scripts 数组中指定的顺序，对于具有匹配的 run_at 值的每个对象，然后：
    • CSS 按其 css 数组中指定的顺序应用。默认情况下，"author" 来源的 CSS 具有优先权，除非 css_origin 设置为 "user"。
    • JavaScript 代码按其 js 数组中指定的顺序执行。

例如，在此键规范中：

json
"content_scripts": [
    {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["jquery.js", "my-content-script.js"],
    "run_at": "document_idle"
  },
  {
    "matches": ["*://*.mozilla.org/*"],
    "css": ["my-css.css"],
    "js": ["another-content-script.js", "yet-another-content-script.js"],
    "run_at": "document_idle"
  },
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["run-first.js"],
    "run_at": "document_start"
  }
]

当打开 mozilla.org 域时，文件按以下方式加载：

  • "run-first.js" - 因为它被请求在 "document_start" 运行。
  • "jquery.js" - 因为它在第一个请求在 "document_idle" 运行的数组中。
  • "my-content-script.js" - 因为它是第一个请求在 "document_idle" 运行的数组中的第二个项目。
  • "my-css.css" - 因为对象的 CSS 在其 JavaScript 之前加载。
  • "another-content-script.js" - 因为它是 js 属性中的第一个项目。
  • "yet-another-content-script.js"

匹配 URL 模式

"content_scripts" 键根据 URL 匹配将内容脚本附加到文档：如果文档的 URL 与键中的规范匹配，则将附加该脚本。"content_scripts" 中有四个属性可用于此规范：

matches

一个 匹配模式 数组

exclude_matches

一个 匹配模式 数组

include_globs

一个 glob 数组

exclude_globs

一个 glob 数组

要匹配这些属性之一，URL 必须至少匹配其数组中的一个项目。例如，给定一个属性：

json
"matches": ["*://*.example.org/*", "*://*.example.com/*"]

http://example.org/ 和 http://example.com/ 都将匹配。

由于 matches 是唯一必需的键，因此其他三个键用于进一步限制匹配的 URL。要使整个键匹配，URL 必须：

  • 匹配 matches 属性
  • 并且匹配 include_globs 属性（如果存在）
  • 并且不匹配 exclude_matches 属性（如果存在）
  • 并且不匹配 exclude_globs 属性（如果存在）

globs

Glob 只是一个可能包含通配符的字符串。

有两种通配符，您可以在同一个 glob 中组合它们：

  1. * 匹配零个或多个字符
  2. ? 匹配正好一个字符。

例如："*na?i" 将匹配 "illuminati" 和 "annunaki"，但不匹配 "sagnarelli"。

示例

json
"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["borderify.js"]
  }
]

这会将单个内容脚本 borderify.js 注入到 mozilla.org 或其任何子域下的所有页面中，无论它们是通过 HTTP 还是 HTTPS 提供。

json
  "content_scripts": [
    {
      "exclude_matches": ["*://mdn.org.cn/*"],
      "matches": ["*://*.mozilla.org/*"],
      "js": ["jquery.js", "borderify.js"]
    }
  ]

这会将两个内容脚本注入到 mozilla.org 或其任何子域下的所有页面中，但 developer.mozilla.org 除外，无论它们是通过 HTTP 还是 HTTPS 提供。

内容脚本看到 DOM 的视图相同，并且按照它们在数组中出现的顺序注入，因此 borderify.js 可以看到由 jquery.js 添加的全局变量。

浏览器兼容性

帮助改进 MDN

了解如何贡献

此页面最后修改于 ，由 MDN 贡献者 修改。

在 GitHub 上查看此页面 • 报告此内容的问题
© . Content available under a Creative Commons license.