資訊清單 - 內容指令碼

"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

Frames

"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 共用執行環境。詳情請參閱「在隔離環境中工作」。
,瞭解如何調查及移除這項存取權。

範例

請參閱「在每個網頁上執行」教學課程,瞭解如何建構在資訊清單中插入內容指令碼的擴充功能。