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"));

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

插入的程式碼

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

檔案

檔案會指定為字串，做為擴充功能根目錄的相對路徑 目錄。下列程式碼會在主程式中插入 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(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 以上版本

屬性

• ids

  string[] 選填

  如有指定，getRegisteredContentScripts 只會傳回具有這份清單所指定 ID 的指令碼。

CSSInjection

屬性

• CSS

  string optional

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

• 檔案

  string[] 選填

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

• 起源

  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

  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 以上版本

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

• 目標

  InjectionTarget

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

• 世界

  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 屬性，即使頁面尚未載入完畢，指令碼也不會等待。如果指令碼評估結果為 承諾，瀏覽器會等待計算結果，然後傳回結果值。

參數

• 注射避孕針

  ScriptInjection

  插入的指令碼詳細資訊。

• 回呼

  函式 選用

  callback 參數如下所示：

  (results: InjectionResult[]) => void

  • 結果

    InjectionResult[]

傳回

• Promise<InjectionResult[]>

  Chrome 90 以上版本

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

getRegisteredContentScripts()

Promise Chrome 96 以上版本

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

參數

• 篩選器

  ContentScriptFilter 選用

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (scripts: RegisteredContentScript[]) => void

  • 指令碼

    RegisteredContentScript[]

傳回

• 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,
)

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

參數

• 指令碼

  RegisteredContentScript[]

  包含要註冊的指令碼清單。如果指令碼剖析/檔案驗證期間發生錯誤，或是指定的 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,
)

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

參數

• 指令碼

  RegisteredContentScript[]

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

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