"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 共用執行環境。詳情請參閱「在隔離環境中工作」。
範例
請參閱「在每個網頁中執行」教學課程,建構可在資訊清單中插入內容指令碼的擴充功能。