"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",
}
],
...
}
Files
每個檔案都必須包含擴充功能根目錄中資源的相對路徑。系統會自動移除開頭的斜線 (/)。"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"模式。
Globs 和網址比對範例
"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 共用執行環境。詳情請參閱「在隔離環境中工作」。
範例
請參閱「在每個網頁中執行」教學課程，建構可在資訊清單中插入內容指令碼的擴充功能。