chrome.userScripts

說明

使用 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 120 以上版本 MV3 以上

概念和用法

使用者指令碼是插入網頁中的一小段程式碼，用來修改網頁的外觀或行為。指令碼可以由使用者建立，也可以從指令碼存放區或使用者指令碼擴充功能下載。

擴充功能使用者的開發人員模式

擴充功能開發人員在安裝 Chrome 時，已啟用開發人員模式。如果是使用者指令碼擴充功能，使用者也必須啟用開發人員模式。您可以複製下列指示並貼到自己的文件中。

1. 在新分頁中開啟 chrome://extensions，前往「擴充功能」頁面。(根據設計，chrome:// 網址無法連結)。

2. 按一下「開發人員模式」旁的切換鈕，即可啟用開發人員模式。

   

   擴充功能頁面 (chrome://extensions)

如要判斷開發人員模式是否已啟用，請檢查 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[]

  ScriptSource 物件清單，用於定義要在比對頁面中插入的指令碼來源。

• 完全相符

  string[] 選填

  指定要插入這個使用者指令碼的網頁。如要進一步瞭解這些字串的語法，請參閱比對模式。必須為 ${ref:register} 指定這項屬性。

• runAt

  RunAt 非必要

  指定在網頁中插入 JavaScript 檔案的時機。偏好及預設值為 document_idle。

• 世界

  ExecutionWorld 選用

  要執行指令碼的 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()

Promise

chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

設定 `USER_SCRIPT` 執行環境。

參數

• 資源

  WorldProperties

  含有使用者指令碼世界設定。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getScripts()

Promise

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

傳回這個擴充功能的所有動態註冊使用者指令碼。

參數

• 篩選器

  UserScriptFilter (選用)

  如果指定，這個方法只會傳回相符的使用者指令碼。

• 回呼

  函式 選用

  callback 參數如下所示：

  (scripts: RegisteredUserScript[]) => void

  • 指令碼

    RegisteredUserScript[]

傳回

• Promise&lt;RegisteredUserScript[]&gt;

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

register()

Promise

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

為這個擴充功能註冊一或多個使用者指令碼。

參數

• 指令碼

  RegisteredUserScript[]

  包含要註冊的使用者指令碼清單。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

unregister()

Promise

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

取消註冊這個擴充功能的所有動態註冊使用者指令碼。

參數

• 篩選器

  UserScriptFilter (選用)

  如果有指定，這個方法只會取消註冊相符的使用者指令碼。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

update()

Promise

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

更新這個擴充功能的一或多個使用者指令碼。

參數

• 指令碼

  RegisteredUserScript[]

  包含要更新的使用者指令碼清單。只有這個物件中已指定指令碼的屬性，才會更新現有指令碼的屬性。如果在剖析指令碼/檔案驗證期間發生錯誤，或是指定的 ID 未對應到完整註冊的指令碼，系統就不會更新任何指令碼。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。