"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 共用執行環境。詳情請參閱「在隔離環境中工作」。 ,瞭解如何調查及移除這項存取權。
範例
請參閱「在每個網頁上執行」教學課程,瞭解如何建構在資訊清單中插入內容指令碼的擴充功能。