本頁面由 Cloud Translation API 翻譯而成。

chrome.scripting

說明

使用 chrome.scripting API 在不同環境中執行指令碼。

權限

scripting

可用性

Chrome 88 以上版本 MV3 以上版本

資訊清單

如要使用 chrome.scripting API，請在資訊清單中宣告 "scripting" 權限，以及要注入指令碼的網頁主機權限。使用 "host_permissions" 鍵或 "activeTab" 權限，即可授予臨時主機權限。以下範例使用 activeTab 權限。

{   "name": "Scripting Extension",   "manifest_version": 3,   "permissions": ["scripting", "activeTab"],   ... }

概念與用途

您可以使用 chrome.scripting API 將 JavaScript 和 CSS 注入網站。這與內容指令碼的功能類似。但只要使用 chrome.scripting 命名空間，擴充功能就能在執行階段做出決策。

注入目標

您可以使用 target 參數指定要將 JavaScript 或 CSS 插入的目標。

唯一的必填欄位是 tabId。根據預設，注入作業會在指定分頁的主要框架中執行。

function getTabId() { ... }  chrome.scripting     .executeScript({       target : {tabId : getTabId()},       files : [ "script.js" ],     })     .then(() => console.log("script injected"));

如要在指定分頁的所有框架中執行，您可以將 allFrames 布林值設為 true。

function getTabId() { ... }  chrome.scripting     .executeScript({       target : {tabId : getTabId(), allFrames : true},       files : [ "script.js" ],     })     .then(() => console.log("script injected in all frames"));

您也可以指定個別框架 ID，將程式碼插入分頁的特定框架。如要進一步瞭解影格 ID，請參閱 chrome.webNavigationAPI。

function getTabId() { ... }  chrome.scripting     .executeScript({       target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},       files : [ "script.js" ],     })     .then(() => console.log("script injected on target frames"));

注意：您無法同時指定 "frameIds" 和 "allFrames" 屬性。

注入的程式碼

擴充功能可以透過外部檔案或執行階段變數，指定要插入的程式碼。

檔案

檔案會指定為字串，也就是擴充功能根目錄的相對路徑。下列程式碼會將 script.js 檔案插入分頁的 main frame。

function getTabId() { ... }  chrome.scripting     .executeScript({       target : {tabId : getTabId()},       files : [ "script.js" ],     })     .then(() => console.log("injected script file"));

執行階段函式

使用 scripting.executeScript() 插入 JavaScript 時，您可以指定要執行的函式，而非檔案。此函式應為函式變數，可供目前的擴充功能環境使用。

function getTabId() { ... } function getTitle() { return document.title; }  chrome.scripting     .executeScript({       target : {tabId : getTabId()},       func : getTitle,     })     .then(() => console.log("injected a function"));

function getTabId() { ... } function getUserColor() { ... }  function changeBackgroundColor() {   document.body.style.backgroundColor = getUserColor(); }  chrome.scripting     .executeScript({       target : {tabId : getTabId()},       func : changeBackgroundColor,     })     .then(() => console.log("injected a function"));

如要解決這個問題，請使用 args 屬性：

function getTabId() { ... } function getUserColor() { ... } function changeBackgroundColor(backgroundColor) {   document.body.style.backgroundColor = backgroundColor; }  chrome.scripting     .executeScript({       target : {tabId : getTabId()},       func : changeBackgroundColor,       args : [ getUserColor() ],     })     .then(() => console.log("injected a function"));

執行階段字串

如果在網頁中插入 CSS，您也可以指定要在 css 屬性中使用的字串。這個選項僅適用於 scripting.insertCSS()，您無法使用 scripting.executeScript() 執行字串。

function getTabId() { ... } const css = "body { background-color: red; }";  chrome.scripting     .insertCSS({       target : {tabId : getTabId()},       css : css,     })     .then(() => console.log("CSS injected"));

處理結果

執行 JavaScript 的結果會傳遞至擴充功能。每個影格會包含單一結果。保證主要影格是結果陣列中的第一個索引；所有其他影格的順序不確定。

function getTabId() { ... } function getTitle() { return document.title; }  chrome.scripting     .executeScript({       target : {tabId : getTabId(), allFrames : true},       func : getTitle,     })     .then(injectionResults => {       for (const {frameId, result} of injectionResults) {         console.log(`Frame ${frameId} result:`, result);       }     });

scripting.insertCSS() 未傳回任何結果。

Promise

如果執行指令碼後的值是 Promise，Chrome 會等待 Promise 結算，並傳回結果值。

function getTabId() { ... } async function addIframe() {   const iframe = document.createElement("iframe");   const loadComplete =       new Promise(resolve => iframe.addEventListener("load", resolve));   iframe.src = "https://example.com";   document.body.appendChild(iframe);   await loadComplete;   return iframe.contentWindow.document.title; }  chrome.scripting     .executeScript({       target : {tabId : getTabId(), allFrames : true},       func : addIframe,     })     .then(injectionResults => {       for (const frameResult of injectionResults) {         const {frameId, result} = frameResult;         console.log(`Frame ${frameId} result:`, result);       }     });

範例

取消註冊所有動態內容指令碼

下列程式碼片段包含一個函式，可取消註冊擴充功能先前註冊的所有動態內容指令碼。

async function unregisterAllDynamicContentScripts() {   try {     const scripts = await chrome.scripting.getRegisteredContentScripts();     const scriptIds = scripts.map(script => script.id);     return chrome.scripting.unregisterContentScripts({ ids: scriptIds });   } catch (error) {     const message = [       "An unexpected error occurred while",       "unregistering dynamic content scripts.",     ].join(" ");     throw new Error(message, {cause : error});   } }

如要試用 chrome.scripting API，請從 Chrome 擴充功能範例存放區安裝指令碼範例。

類型

ContentScriptFilter

Chrome 96 以上版本

屬性

ids

字串陣列選用

如果指定，getRegisteredContentScripts 只會傳回這個清單中指定 ID 的指令碼。

CSSInjection

屬性

CSS

字串選填

包含要插入的 CSS 的字串。必須指定 files 和 css 其中之一。
檔案

字串陣列選用

要插入的 CSS 檔案路徑，相對於擴充功能的根目錄。必須指定 files 和 css 其中之一。
origin

StyleOrigin 選用

注入的樣式來源。預設值為 'AUTHOR'。
目標

InjectionTarget

詳細資料：指定要插入 CSS 的目標。

ExecutionWorld

Chrome 95 以上版本

指令碼要在其中執行的 JavaScript 世界。

列舉

「ISOLATED」
：指定獨立世界，也就是這個擴充功能專屬的執行環境。

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

InjectionResult

屬性

documentId

字串

Chrome 106 以上版本

與插入內容相關聯的文件。
frameId

數字

Chrome 90 以上版本

與插入內容相關聯的影格。
結果

不限選填

指令碼執行結果。

InjectionTarget

屬性

allFrames

布林值選填

指令碼是否應注入分頁中的所有影格。預設值為 false。如果指定了 frameIds，這個值就不得為 true。
documentIds

字串陣列選用

Chrome 106 以上版本

要注入的特定 documentId 的 ID。如果已設定 frameIds，則不得設定這項屬性。
frameIds

number[] 選填

要注入的特定框架 ID。
tabId

數字

要注入的索引標籤 ID。

RegisteredContentScript

Chrome 96 以上版本

屬性

allFrames

布林值選填

如果指定為 true，即使影格不是分頁中最上層的影格，也會注入所有影格。系統會針對網址需求獨立檢查每個影格，如果不符合網址需求，系統就不會將影格插入子影格。預設值為 false，表示只會比對頂端影格。
CSS

字串陣列選用

要插入相符網頁的 CSS 檔案清單。系統會按照這個陣列中的順序插入這些項目，然後才會建構或顯示網頁的任何 DOM。
excludeMatches

字串陣列選用

排除這個內容指令碼原本會注入的網頁。如要進一步瞭解這些字串的語法，請參閱「比對模式」。
id

字串

API 呼叫中指定的內容指令碼 ID。開頭不得為「_」，因為這是為產生的指令碼 ID 保留的前置字元。
js

字串陣列選用

要插入相符網頁的 JavaScript 檔案清單。系統會按照這個陣列中的順序插入這些項目。
matchOriginAsFallback

布林值選填

Chrome 119 以上版本

指出是否可將指令碼插入網址含有不支援配置的影格，具體來說，就是 about:、data:、blob: 或 filesystem:。在這些情況下，系統會檢查網址的來源，判斷是否應插入指令碼。如果來源是 null (例如資料網址)，則使用的來源是建立目前影格的影格，或是啟動導覽至這個影格的影格。請注意，這可能不是父影格。
完全相符

字串陣列選用

指定要將這個內容指令碼插入哪些網頁。如要進一步瞭解這些字串的語法，請參閱「比對模式」。必須為 registerContentScripts 指定。
persistAcrossSessions

布林值選填

指定這個內容指令碼是否會保留到日後的工作階段。預設值為 true。
runAt

RunAt 選填

指定將 JavaScript 檔案插入網頁的時間。建議值和預設值為 document_idle。
世界

ExecutionWorld 選用

Chrome 102 以上版本

執行指令碼的 JavaScript「世界」。預設值為 ISOLATED。

ScriptInjection

屬性

args

any[] 選填

Chrome 92 以上版本

要傳遞至所提供函式的引數。只有在指定 func 參數時，這項設定才會生效。這些引數必須可透過 JSON 序列化。
檔案

字串陣列選用

要插入的 JS 或 CSS 檔案路徑，相對於擴充功能的根目錄。必須指定 files 或 func 其中之一。
injectImmediately

布林值選填

Chrome 102 以上版本

是否應盡快在目標中觸發插入作業。請注意，這無法保證系統會在網頁載入前注入指令碼，因為指令碼到達目標時，網頁可能已載入完畢。
目標

InjectionTarget

詳細資料：指定要將指令碼注入的目標。
世界

ExecutionWorld 選用

Chrome 95 以上版本

執行指令碼的 JavaScript「世界」。預設值為 ISOLATED。
func

void optional

Chrome 92 以上版本

要插入的 JavaScript 函式。這個函式會序列化，然後還原序列化以進行注入。也就是說，所有繫結的參數和執行環境都會遺失。必須指定 files 或 func 其中之一。

func 函式如下所示：
```
() => {...}
```

StyleOrigin

樣式變更的來源。詳情請參閱「樣式來源」。

列舉

「AUTHOR」

「USER」

方法

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

將指令碼插入目標環境。根據預設，指令碼會在 document_idle 執行，如果網頁已載入，則會立即執行。如果設定 injectImmediately 屬性，即使網頁尚未載入完成，指令碼也會立即注入。如果指令碼評估結果為 Promise，瀏覽器會等待 Promise 結算，並傳回結果值。

參數

注射

ScriptInjection

要插入的指令碼詳細資料。

傳回

Promise<InjectionResult[]>

Chrome 90 以上版本

getRegisteredContentScripts()

Chrome 96 以上版本

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

傳回這個擴充功能所有動態註冊的內容指令碼，這些指令碼符合指定的篩選條件。

參數

篩選

ContentScriptFilter optional

用於篩選擴充功能動態註冊指令碼的物件。

傳回

Promise<RegisteredContentScript[]>

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

將 CSS 樣式表插入目標環境。如果指定多個影格，系統會忽略失敗的插入作業。

參數

注射

CSSInjection

要插入的樣式詳細資料。

傳回

Promise<void>

Chrome 90 以上版本

registerContentScripts()

Chrome 96 以上版本

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

為這個擴充功能註冊一或多個內容指令碼。

參數

指令碼

RegisteredContentScript[]

包含要註冊的指令碼清單。如果在剖析指令碼/驗證檔案時發生錯誤，或指定的 ID 已存在，系統就不會註冊任何指令碼。

傳回

Promise<void>

removeCSS()

Chrome 90 以上版本

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

從目標環境中移除先前由這個擴充功能插入的 CSS 樣式表。

參數

注射

CSSInjection

要移除的樣式詳細資料。請注意，css、files 和 origin 屬性必須與透過 insertCSS 插入的樣式表完全相符。嘗試移除不存在的樣式表是無作業。

傳回

Promise<void>

unregisterContentScripts()

Chrome 96 以上版本

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

取消註冊這個擴充功能的內容指令碼。

參數

篩選

ContentScriptFilter optional

如果指定，則只會取消註冊符合篩選條件的動態內容指令碼。否則，擴充功能的所有動態內容指令碼都會取消註冊。

傳回

Promise<void>

updateContentScripts()

Chrome 96 以上版本

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

更新這個擴充功能的一或多個內容指令碼。

參數

指令碼

RegisteredContentScript[]

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

傳回

Promise<void>

chrome.scripting 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

說明

權限

可用性

資訊清單

概念與用途

注入目標

注入的程式碼

檔案

執行階段函式

執行階段字串

處理結果

Promise

範例

取消註冊所有動態內容指令碼

類型

ContentScriptFilter

屬性

CSSInjection

屬性

ExecutionWorld

列舉

InjectionResult

屬性

InjectionTarget

屬性

RegisteredContentScript

屬性

ScriptInjection

屬性

StyleOrigin

列舉

方法

executeScript()

參數

傳回

getRegisteredContentScripts()

參數

傳回

insertCSS()

參數

傳回

registerContentScripts()

參數

傳回

removeCSS()

參數

傳回

unregisterContentScripts()

參數

傳回

updateContentScripts()

參數

傳回

chrome.scripting