說明
使用 userScripts
API,在 User Script 環境中執行使用者指令碼。
權限
userScripts
如要使用 chrome.userScripts
API,請針對要執行指令碼的網站,將 "userScripts"
權限新增至 manifest.json 和 "host_permissions"
。
{
"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
});
擴充功能更新
更新擴充功能時,系統會清除使用者指令碼。如要加回這些屬性,請在擴充功能 Service 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 可當做前置字串,用於產生的指令碼 ID。
-
includeGlobs
string[] 選填
為要插入這個使用者指令碼的網頁指定萬用字元模式。
-
js
ScriptSource 物件清單,用於定義要在比對頁面中插入的指令碼來源。
-
完全相符
string[] 選填
指定要插入這個使用者指令碼的網頁。如要進一步瞭解這些字串的語法,請參閱比對模式。必須為 ${ref:register} 指定這項屬性。
-
runAt
RunAt 非必要
指定在網頁中插入 JavaScript 檔案的時機。偏好及預設值為
document_idle
。 -
世界
要執行指令碼的 JavaScript 執行環境。預設為
`USER_SCRIPT`
。
ScriptSource
屬性
-
程式碼
string optional
包含要插入 JavaScript 程式碼的字串。必須明確指定
file
或code
其中之一。 -
檔案
string optional
所插入 JavaScript 檔案的路徑 (相對於擴充功能根目錄)。必須明確指定
file
或code
其中之一。
UserScriptFilter
屬性
-
ids
string[] 選填
getScripts
只會傳回具有這份清單所指定 ID 的指令碼。
WorldProperties
屬性
-
CSP
string optional
指定全球 CSS。預設值為
`ISOLATED`
世界 HTTPS。 -
簡訊
布林值 選填
指定是否公開訊息 API。預設為
false
。
方法
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
設定 `USER_SCRIPT`
執行環境。
參數
-
含有使用者指令碼世界設定。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
傳回這個擴充功能的所有動態註冊使用者指令碼。
參數
-
篩選器
UserScriptFilter (選用)
如果指定,這個方法只會傳回相符的使用者指令碼。
-
回呼
函式 選用
callback
參數如下所示:(scripts: RegisteredUserScript[]) => void
-
指令碼
-
傳回
-
Promise<RegisteredUserScript[]>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
為這個擴充功能註冊一或多個使用者指令碼。
參數
-
指令碼
包含要註冊的使用者指令碼清單。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
取消註冊這個擴充功能的所有動態註冊使用者指令碼。
參數
-
篩選器
UserScriptFilter (選用)
如果有指定,這個方法只會取消註冊相符的使用者指令碼。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
更新這個擴充功能的一或多個使用者指令碼。
參數
-
指令碼
包含要更新的使用者指令碼清單。只有這個物件中已指定指令碼的屬性,才會更新現有指令碼的屬性。如果在剖析指令碼/檔案驗證期間發生錯誤,或是指定的 ID 未對應到完整註冊的指令碼,系統就不會更新任何指令碼。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。