chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

說明

使用 chrome.declarativeContent API 根據網頁內容採取行動，不必取得讀取網頁內容的權限。

權限

declarativeContent

用量

透過 Declarative Content API，您可以根據網頁的網址，或 CSS 選取器是否與網頁上的元素相符，啟用擴充功能的動作，無須新增主機權限或插入內容指令碼。

使用者點選擴充功能的動作後，您可以使用 activeTab 權限與網頁互動。

規則

規則由條件和動作組成，只要符合任一條件，系統就會執行所有動作。動作為 setIcon 和 showAction。

只有在符合所有列出的條件時，PageStateMatcher 才會比對網頁。它可以比對網頁網址、CSS 複合選取器或網頁的書籤狀態。下列規則會在 Google 頁面出現密碼欄位時，啟用擴充功能的動作：

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

如要為含有影片的 Google 網站啟用擴充功能的動作，可以新增第二個條件，因為每個條件都足以觸發所有指定的動作：

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

onPageChanged 事件會測試是否有任何規則至少符合一個條件，並執行動作。規則會在瀏覽工作階段中保留，因此在擴充功能安裝期間，您應先使用 removeRules 清除先前安裝的規則，然後使用 addRules 註冊新規則。

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

有了 activeTab 權限，擴充功能就不會顯示任何權限警告，且使用者點選擴充功能動作時，只會在相關網頁上執行。

網頁網址比對

如果符合網址條件，系統就會比對 PageStateMatcher.pageurl。最常見的條件是主機、路徑或網址的串連，後面接著「包含」、「等於」、「前置字串」或「後置字串」。下表列出幾個範例：

條件 配對組合
{ hostSuffix: 'google.com' } 所有 Google 網址
{ pathPrefix: '/docs/extensions' } 擴充功能文件網址
{ urlContains: 'developer.chrome.com' } 所有 Chrome 開發人員說明文件網址

所有條件都區分大小寫。如需完整條件清單，請參閱 UrlFilter。

CSS 比對

PageStateMatcher.css 條件必須是複合選取器，也就是說，選取器中不得包含空白字元或「>」等組合器。這有助於 Chrome 更有效率地比對選取器。

複合選取器 (OK) 複雜選取器 (不適用)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

CSS 條件只會比對顯示的元素：如果符合選取器的元素是 display:none，或其中一個父項元素是 display:none，就不會導致條件相符。以 visibility:hidden 樣式設定的元素、位於畫面外的元素，或遭其他元素隱藏的元素，仍可讓條件相符。

已加入書籤狀態比對

PageStateMatcher.isBookmarked 條件可比對使用者個人資料中目前網址的書籤狀態。如要使用這項條件，必須在擴充功能資訊清單中聲明「書籤」權限。

類型

類型

ImageData

PageStateMatcher

根據各種條件比對網頁狀態。

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

    (arg: PageStateMatcher) => {...}

  • CSS

    字串陣列 選用

    如果陣列中的所有 CSS 選取器，都與頁面主要框架來源相同的框架中顯示的元素相符，就會相符。這個陣列中的所有選取器都必須是複合選取器，才能加快比對速度。注意：列出數百個 CSS 選取器，或列出每個網頁可比對數百次的 CSS 選取器，可能會導致網站速度變慢。

  • isBookmarked

    布林值 選填

    Chrome 45 以上版本

    如果網頁的書籤狀態等於指定值，就會相符。需要書籤權限。

  • pageUrl

    UrlFilter 選填

    如果網頁的頂層網址符合 UrlFilter 的條件，就會相符。

RequestContentScript

可插入內容指令碼的宣告式事件動作。

警告：這項動作仍處於實驗階段，Chrome 穩定版不支援這項功能。

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

    (arg: RequestContentScript) => {...}

  • allFrames

    布林值 選填

    內容指令碼是在相符網頁的所有框架中執行，還是只在頂端框架中執行。預設值為 false。

  • CSS

    字串陣列 選用

    要插入為內容指令碼一部分的 CSS 檔案名稱。

  • js

    字串陣列 選用

    要插入為內容指令碼一部分的 JavaScript 檔案名稱。

  • matchAboutBlank

    布林值 選填

    是否要在 about:blank 和 about:srcdoc 插入內容指令碼。預設值為 false。

SetIcon

宣告式事件動作，可在符合對應條件時，為擴充功能的網頁動作或瀏覽器動作設定 n-dip 方形圖示。這項動作不需主機權限即可使用，但擴充功能必須有網頁或瀏覽器動作。

必須明確指定 imageData 或 path 其中之一。兩者都是將像素數量對應至圖片表示法的字典。imageData 中的圖片表示法是 ImageData 物件 (例如來自 canvas 元素)，而 path 中的圖片表示法則是相對於擴充功能資訊清單的圖片檔案路徑。如果 scale 螢幕像素符合裝置獨立像素，系統會使用 scale * n 圖示。如果缺少該比例，系統會將其他圖片調整為所需大小。

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | 物件 選用

    ImageData 物件或字典 {size -> ImageData}，代表要設定的圖示。如果圖示指定為字典，系統會根據螢幕的像素密度選擇使用的圖片。如果可放入一個螢幕空間單位的圖片像素數量等於 scale，則會選取大小為 scale * n 的圖片，其中 n 是 UI 中圖示的大小。至少須指定一張圖片。請注意，details.imageData = foo 等於 details.imageData = {'16': foo}。

ShowAction

Chrome 97 以上版本

宣告式事件動作，可在符合相應條件時，將擴充功能的工具列動作設為啟用狀態。這項動作不需主機權限即可使用。如果擴充功能具有 activeTab 權限，按一下頁面動作即可授予現用分頁的存取權。

如果網頁不符合條件，擴充功能的工具列動作會顯示為灰階，點選後會開啟內容選單，而不是觸發動作。

屬性

ShowPageAction

自 Chrome 97 起已淘汰

請使用 declarativeContent.ShowAction。

宣告式事件動作，可在符合對應條件時，將擴充功能的網頁動作設為啟用狀態。這項動作不需主機權限即可使用，但擴充功能必須有頁面動作。如果擴充功能具有 activeTab 權限，按一下頁面動作即可授予現用分頁的存取權。

如果網頁不符合條件，擴充功能的工具列動作會顯示為灰階，點選後會開啟內容選單，而不是觸發動作。

屬性

事件

onPageChanged

提供 Declarative Event API，包含 addRules、removeRules 和 getRules。

條件

PageStateMatcher

動作

RequestContentScript

SetIcon

ShowPageAction

ShowAction