chrome.userScripts

說明

使用 userScripts API 在「User Scripts」情境中執行使用者指令碼。

權限

userScripts

如要使用 chrome.userScripts API，請在 manifest.json 中加入 "userScripts" 權限，並為要執行指令碼的網站新增 "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
});

擴充功能更新

擴充功能更新時，系統會清除使用者腳本。您可以透過在擴充功能服務 worker 的 runtime.onInstalled 事件處理常式中執行程式碼，將這些項目重新加入。只回應傳遞至事件回呼的 "update" reason。

範例

這個範例取自範例存放區中的 userScript 範例。

註冊指令碼

以下範例顯示對 register() 的基本呼叫。第一個引數是物件陣列，定義要註冊的腳本。這裡顯示的選項並非全部。

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

類型

ExecutionWorld

使用者指令碼執行的 JavaScript 環境。

列舉

「MAIN」
指定 DOM 的執行環境，也就是與主機網頁 JavaScript 共用的執行環境。

"USER_SCRIPT"
指定專屬於使用者指令碼的執行環境，且不受網頁的 CSP 限制。

RegisteredUserScript

屬性

• allFrames

  boolean 選填

  如果為 true，即使該頁框不是分頁中頂端的頁框，也會插入所有頁框。系統會個別檢查每個影格是否符合網址規定；如果不符合網址規定，就不會將影格插入子影格。預設值為 false，表示只會比對頂層影格。

• excludeGlobs

  string[] 選填

  指定此使用者指令碼不會插入的網頁萬用字元模式。

• excludeMatches

  string[] 選填

  排除這個使用者指令碼會插入的網頁。如要進一步瞭解這些字串的語法，請參閱「比對模式」。

• id

  字串

  API 呼叫中指定的使用者指令碼 ID。此屬性不得以「_」開頭，因為系統會將「_」保留做為產生的指令碼 ID 前置字元。

• includeGlobs

  string[] 選填

  指定要插入此使用者指令碼的網頁萬用字元模式。

• js

  ScriptSource[] 選填

  ScriptSource 物件清單，定義要插入相符網頁的指令碼來源。此屬性必須指定給 ${ref:register}，且指定時必須為非空陣列。

• 完全相符

  string[] 選填

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

• runAt

  RunAt 選填

  指定 JavaScript 檔案何時會插入網頁。建議值和預設值為 document_idle。

• 世界

  ExecutionWorld 選填

  要執行指令碼的 JavaScript 執行環境。預設為 `USER_SCRIPT`。

• worldId

  string 選填

  待處理

  如果指定，則會指定要執行的特定使用者指令碼世界 ID。只有在省略 world 或為 USER_SCRIPT 時才有效。如果省略此參數，系統會在預設使用者指令碼環境中執行指令碼。以底線 (_) 開頭的值為保留值。

ScriptSource

屬性

• 程式碼

  string 選填

  字串，其中包含要插入的 JavaScript 程式碼。必須指定 file 或 code 其中一個。

• 檔案

  string 選填

  相對於擴充功能根目錄的 JavaScript 檔案路徑。必須指定 file 或 code 其中一個。

UserScriptFilter

屬性

• ids

  string[] 選填

  getScripts 只會傳回清單中指定 ID 的劇本。

WorldProperties

屬性

• csp

  string 選填

  指定世界 csp。預設為 `ISOLATED` 世界 csp。

• 訊息

  boolean 選填

  指定是否要公開訊息 API。預設為 false。

• worldId

  string 選填

  待處理

  指定要更新的特定使用者指令碼世界 ID。如未提供，則會更新預設使用者指令碼 world 的屬性。以底線 (_) 開頭的值為保留值。

方法

configureWorld()

Promise

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

設定 `USER_SCRIPT` 執行環境。

參數

• 資源

  WorldProperties

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

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getScripts()

Promise

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

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

參數

• 篩選器

  UserScriptFilter 選填

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

• 回呼

  函式 選填

  callback 參數如下所示：

  (scripts: RegisteredUserScript[]) => void

  • 指令碼

    RegisteredUserScript[]

傳回

• Promise<RegisteredUserScript[]>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getWorldConfigurations()

Promise 待處理

chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

擷取所有已註冊的世界設定。

參數

• 回呼

  函式 選填

  callback 參數如下所示：

  (worlds: WorldProperties[]) => void

  • 世界

    WorldProperties[]

傳回

• Promise<WorldProperties[]>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

register()

Promise

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

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

參數

• 指令碼

  RegisteredUserScript[]

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

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

resetWorldConfiguration()

Promise 待處理

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

重設使用者指令碼世界設定。任何以指定 ID 注入到世界中的指令碼，都會使用預設的世界設定。

參數

• worldId

  string 選填

  要重設的使用者指令碼世界 ID。如果省略，則會重設預設世界的設定。

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

unregister()

Promise

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

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

參數

• 篩選器

  UserScriptFilter 選填

  如果指定了這個方法，則只會註銷與該方法相符的使用者指令碼。

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

update()

Promise

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

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

參數

• 指令碼

  RegisteredUserScript[]

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

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。