chrome.scripting

說明

使用 chrome.scripting API 在不同的情況下執行指令碼。

權限

scripting

可用性

Chrome 88 以上版本 MV3 以上

資訊清單

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

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

概念和用法

您可以使用 chrome.scripting API 將 JavaScript 和 CSS 插入 網站。做法類似您可以撰寫的內容 指令碼但透過使用 chrome.scripting 命名空間 並在執行階段做出決策

插入目標

您可以使用 target 參數指定要插入 JavaScript 的目標，或是 翻譯成

唯一的必填欄位是 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.webNavigation API 讀取和更新資料。

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

插入的程式碼

擴充功能可以透過外部檔案或 執行階段變數。

檔案

檔案會指定為字串，做為擴充功能根目錄的相對路徑 目錄。下列程式碼會在主程式中插入 script.js 檔案 視窗的頁框

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

如果執行指令碼的結果值是承諾，Chrome 會等待 並傳回結果值

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 擴充功能範例中的指令碼範例 Cloud Storage 也提供目錄同步處理功能

類型

ContentScriptFilter

Chrome 96 以上版本

屬性

CSSInjection

屬性

  • CSS

    string optional

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

  • 檔案

    string[] 選填

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

  • 起源

    StyleOrigin 選用

    插入內容的樣式來源。預設值為 'AUTHOR'。

  • 詳細說明要插入 CSS 的目標。

ExecutionWorld

Chrome 95 以上版本

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

列舉

"ISOLATED"
指定獨立世界，這是這項擴充功能專屬的執行環境。

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

InjectionResult

屬性

  • documentId

    字串

    Chrome 106 以上版本

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

  • frameId

    數字

    Chrome 90 以上版本

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

  • 結果

    任何選用

    指令碼執行的結果。

InjectionTarget

屬性

  • allFrames

    布林值 選填

    設定指令碼是否應插入分頁內的所有頁框中。預設值為 false。如果已指定 frameIds，則不得為 true。

  • documentIds

    string[] 選填

    Chrome 106 以上版本

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

  • frameIds

    number[] 選填

    要插入的特定影格的 ID。

  • tabId

    數字

    插入的分頁 ID。

RegisteredContentScript

Chrome 96 以上版本

屬性

  • allFrames

    布林值 選填

    如果指定 True，即使該影格並非分頁中最頂端的影格，仍會插入所有頁框。系統會分別檢查每個頁框是否符合網址規定。就不會在不符合網址規定的情況下插入子頁框。預設值為 false，表示只有頂層影格相符。

  • CSS

    string[] 選填

    要插入相符頁面的 CSS 檔案清單。系統會在為網頁建構或顯示任何 DOM 之前，按照這些陣列中出現的順序插入這些變數。

  • excludeMatches

    string[] 選填

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

  • id

    字串

    在 API 呼叫中指定的內容指令碼 ID。開頭不得為「_」這個 ID 可當做前置字串，用於產生的指令碼 ID。

  • js

    string[] 選填

    指定要插入到相符網頁的 JavaScript 檔案清單。系統會按照此陣列中的顯示順序插入這些元素。

  • matchOriginAsFallback

    布林值 選填

    Chrome 119 以上版本

    指出指令碼是否可以插入網址包含不支援的配置；特別是關於:、data:、blob: 或檔案系統:。在這種情況下，系統會檢查網址的來源，判斷是否應插入指令碼。如果來源是 null (如同「data: URL」的情況)，就表示使用的原點是建立目前頁框的頁框，或是啟動瀏覽這個頁框的頁框。請注意，這不是父項頁框。

  • 完全相符

    string[] 選填

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

  • persistAcrossSessions

    布林值 選填

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

  • runAt

    RunAt 非必要

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

  • 世界

    ExecutionWorld 選用

    Chrome 102 以上版本

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

ScriptInjection

屬性

  • args

    Any[] 選填

    Chrome 92 以上版本

    要傳遞至所提供函式的引數。只有在指定 func 參數的情況下，這才算有效。這些引數必須可進行 JSON 序列化。

  • 檔案

    string[] 選填

    所插入 JS 或 CSS 檔案的路徑 (相對於擴充功能根目錄)。必須明確指定 files 或 func 其中之一。

  • injectImmediately

    布林值 選填

    Chrome 102 以上版本

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

  • 詳細說明插入指令碼的目標。

  • 世界

    ExecutionWorld 選用

    Chrome 95 以上版本

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

  • func

    void optional

    Chrome 92 以上版本

    要插入的 JavaScript 函式。此函式會序列化，然後反序列化為插入。這表示任何繫結參數和執行環境都會遺失。必須明確指定 files 或 func 其中之一。

    func 函式如下所示： 

    () => {...}

StyleOrigin

樣式變更的起點。詳情請參閱「樣式來源」一文。

列舉

「AUTHOR」

「USER」

方法

executeScript()

Promise 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

將指令碼插入目標結構定義。根據預設，指令碼會在 document_idle 執行；如果頁面已載入，則會立即執行。如果設定了 injectImmediately 屬性，即使頁面尚未載入完畢，指令碼也不會等待。如果指令碼評估結果為 承諾，瀏覽器會等待計算結果，然後傳回結果值。

參數

傳回

  • Promise<InjectionResult[]>

    Chrome 90 以上版本

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

getRegisteredContentScripts()

Promise Chrome 96 以上版本 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

參數

傳回

  • Promise<RegisteredContentScript[]>

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

insertCSS()

Promise 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

參數

  • 注射避孕針

    CSSInjection

    要插入的樣式詳細資料。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 90 以上版本

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

registerContentScripts()

Promise Chrome 96 以上版本 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

參數

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

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

removeCSS()

Promise Chrome 90 以上版本 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

移除這個擴充功能先前從目標內容插入的 CSS 樣式表。

參數

  • 注射避孕針

    CSSInjection

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

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

unregisterContentScripts()

Promise Chrome 96 以上版本 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

參數

  • 篩選器

    ContentScriptFilter 選用

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

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

updateContentScripts()

Promise Chrome 96 以上版本 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

參數

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

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