說明
使用 userScripts
API,在 User Script 環境中執行使用者指令碼。
權限
userScripts
如要使用 chrome.userScripts
API,請針對要執行指令碼的網站,在 manifest.json 和 "host_permissions"
中新增 "userScripts"
權限。
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
適用國家/地區
概念和用法
使用者指令碼是插入網頁的一小段程式碼,可以修改其外觀或行為。指令碼必須由使用者建立,或從指令碼存放區或使用者指令碼擴充功能下載。
擴充功能使用者的開發人員模式
擴充功能開發人員已在安裝 Chrome 時啟用開發人員模式。如果是使用者指令碼擴充功能,使用者也必須啟用開發人員模式。您可以按照下列指示複製及貼上自己的說明文件。
- 在新分頁中輸入
chrome://extensions
,前往「擴充功能」頁面。(在設計上,chrome://
網址不可連結)。 按一下「開發人員模式」旁邊的切換鈕,啟用開發人員模式。
您可以檢查 chrome.userScripts
是否會擲回錯誤,藉此判斷開發人員模式是否已啟用。例如:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
在隔離環境中工作
使用者和內容指令碼都能在隔離環境中執行,或在主要世界中執行。隔離環境是指代管網頁或其他擴充功能無法存取的執行環境。如此一來,使用者指令碼就可以變更 JavaScript 環境,而不會影響代管網頁或其他擴充功能的使用者及內容指令碼。相反地,代管網頁 (以及其他擴充功能的使用者指令碼) 和內容指令碼都無法看到使用者指令碼 (和內容指令碼)。在主要世界中執行的指令碼,可供代管網頁和其他擴充功能存取,而且可由代管網頁和其他擴充功能檢視。如要選取全世界,請在呼叫 userScripts.register()
時傳遞 "USER_SCRIPT"
或 "MAIN"
。
如要設定 USER_SCRIPT
的內容安全政策,請呼叫 userScripts.configureWorld()
:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
訊息
如同內容指令碼和畫面外文件,使用者指令碼會使用訊息功能與擴充功能的其他部分進行通訊,也就是說,這類指令碼可以呼叫 runtime.sendMessage()
和 runtime.connect()
,就像擴充功能的任何其他部分一樣。但是,透過專用的事件處理常式 (也就是不使用 onMessage
或 onConnect
) 接收這類處理常式。這些處理常式稱為 runtime.onUserScriptMessage
和 runtime.onUserScriptConnect
。專屬處理常式可讓您更輕鬆地識別來自使用者指令碼的訊息,這是較不信任的結構定義。
傳送訊息前,您必須先呼叫 configureWorld()
,並將 messaging
引數設為 true
。請注意,csp
和 messaging
引數可以同時傳遞。
chrome.userScripts.configureWorld({
messaging: true
});
擴充功能更新
使用者指令碼會在擴充功能更新時清除。如要加回這些對話方塊,請在擴充功能服務 Worker 的 runtime.onInstalled
事件處理常式中執行程式碼。只回應傳遞至事件回呼的 "update"
原因。
範例
這個範例來自範例存放區中的 userScript 範例。
註冊指令碼
以下範例顯示對 register()
的基本呼叫。第一個引數是物件的陣列,用於定義要註冊的指令碼。這裡列出的選項比這裡列出的還多。
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
類型
ExecutionWorld
供使用者指令碼執行的 JavaScript 世界。
列舉
"MAIN"
指定 DOM 的執行環境,這是與代管網頁 JavaScript 共用的執行環境。
"USER_Script"
指定使用者指令碼專用的執行環境,而且不需依賴網頁的 CSP。
RegisteredUserScript
屬性
-
allFrames
布林值 (選用)
設為 true 時,即使頁框並非分頁最頂層的框架,系統也會將其插入所有頁框。每個頁框都會根據網址規定分別檢查;如果不符合網址規定,則不會插入子頁框。預設值為 False,表示只比對頂層頁框。
-
excludeGlobs
string[] 選填
指定「不」插入這個使用者指令碼的網頁萬用字元模式。
-
excludeMatches
string[] 選填
排除可插入這個使用者指令碼的網頁。如要進一步瞭解這些字串的語法,請參閱比對模式。
-
id
字串
API 呼叫中指定的使用者指令碼 ID。這個屬性不得以「_」為開頭,因為已保留為產生的指令碼 ID 前置字元。
-
includeGlobs
string[] 選填
為將插入這個使用者指令碼的網頁指定萬用字元模式。
-
js
ScriptSource 物件清單,用於定義要插入相符網頁的指令碼來源。
-
相符項目
string[] 選填
指定要將這個使用者指令碼插入哪些網頁。如要進一步瞭解這些字串的語法,請參閱比對模式。必須為 ${ref:register} 指定這個屬性。
-
runAt
RunAt 選用
指定將 JavaScript 檔案插入網頁的時機。建議使用,預設值為
document_idle
。 -
國際
要執行指令碼的 JavaScript 執行環境。預設為
`USER_SCRIPT`
。
ScriptSource
屬性
-
代碼
字串 選用
包含要插入之 JavaScript 程式碼的字串。必須明確指定為
file
或code
其中之一。 -
檔案
字串 選用
相對於擴充功能根目錄的插入 JavaScript 檔案路徑。必須明確指定為
file
或code
其中之一。
UserScriptFilter
屬性
-
ids
string[] 選填
getScripts
只會傳回具有這份清單指定 ID 的指令碼。
WorldProperties
屬性
-
CSP
字串 選用
指定世界 CSp。預設值為
`ISOLATED`
世界 CSp。 -
訊息
布林值 (選用)
指定是否要公開訊息 API。預設為
false
。
方法
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
設定 `USER_SCRIPT`
執行環境。
參數
-
包含使用者指令碼世界設定。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
傳回這個擴充功能的所有動態註冊使用者指令碼。
參數
-
過濾器
如果指定的話,這個方法只會傳回相符的使用者指令碼。
-
回呼
函式選用
callback
參數如下所示:(scripts: RegisteredUserScript[]) => void
-
指令碼
-
傳回
-
Promise<RegisteredUserScript[]>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
為這項擴充功能註冊一或多個使用者指令碼。
參數
-
指令碼
包含要註冊的使用者指令碼清單。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
取消註冊這項擴充功能的所有動態註冊使用者指令碼。
參數
-
過濾器
如果已指定,這個方法只會取消註冊相符的使用者指令碼,
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
更新這項擴充功能的一或多個使用者指令碼。
參數
-
指令碼
包含要更新的使用者指令碼清單。只有現有指令碼中的屬性在此物件中指定屬性時,系統才會更新其屬性。如果剖析/檔案驗證期間發生錯誤,或是指定的 ID 與完整註冊的指令碼不符,系統就不會更新指令碼。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。