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.club.tw/*"],
      "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.