chrome.userScripts

說明

使用 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 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" 原因。

範例

這個範例來自範例存放區中的 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[]

  ScriptSource 物件清單，用於定義要插入相符網頁的指令碼來源。

• 相符項目

  string[] 選填

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

• runAt

  RunAt 選用

  指定將 JavaScript 檔案插入網頁的時機。建議使用，預設值為 document_idle。

• 國際

  ExecutionWorld 選用

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

ScriptSource

屬性

• 代碼

  字串 選用

  包含要插入之 JavaScript 程式碼的字串。必須明確指定為 file 或 code 其中之一。

• 檔案

  字串 選用

  相對於擴充功能根目錄的插入 JavaScript 檔案路徑。必須明確指定為 file 或 code 其中之一。

UserScriptFilter

屬性

• ids

  string[] 選填

  getScripts 只會傳回具有這份清單指定 ID 的指令碼。

WorldProperties

屬性

• CSP

  字串 選用

  指定世界 CSp。預設值為 `ISOLATED` 世界 CSp。

• 訊息

  布林值 (選用)

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

方法

configureWorld()

Promise

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

設定 `USER_SCRIPT` 執行環境。

參數

• 資源

  WorldProperties

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getScripts()

Promise

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

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

參數

• 過濾器

  UserScriptFilter 選用

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

• 回呼

  函式選用

  callback 參數如下所示：

  (scripts: RegisteredUserScript[])=>void

  • 指令碼

    RegisteredUserScript[]

傳回

• Promise<RegisteredUserScript[]>

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

register()

Promise

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

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

參數

• 指令碼

  RegisteredUserScript[]

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

unregister()

Promise

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

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

參數

• 過濾器

  UserScriptFilter 選用

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

update()

Promise

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

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

參數

• 指令碼

  RegisteredUserScript[]

  包含要更新的使用者指令碼清單。只有現有指令碼中的屬性在此物件中指定屬性時，系統才會更新其屬性。如果剖析/檔案驗證期間發生錯誤，或是指定的 ID 與完整註冊的指令碼不符，系統就不會更新指令碼。

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。