browser.declarativeContent

說明

使用 chrome.declarativeContent API 根據網頁內容採取行動，而不要求讀取網頁內容。

權限

declarativeContent

概念和用法

Declarative Content API 可讓您根據 或是 CSS 選取器與網頁上的元素相符 新增主機權限或插入內容指令碼。

使用 activeTab 權限，在使用者點選 擴充功能的動作。

規則

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

只有在所有列出的清單都符合時，PageStateMatcher 才會比對網頁 條件是否相符可與網頁網址和 css 複合選取器相符 或是網頁的書籤狀態。以下規則會啟用 含有密碼欄位時，擴充功能在 Google 網頁上的動作：

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

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

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

onPageChanged 事件會測試任何規則是否至少達成一項 並執行工作規則會在各個瀏覽工作階段保留。因此 擴充功能安裝時間 (建議使用 removeRules) 先前安裝的規則，然後使用 addRules 註冊新的規則。

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

如果有 activeTab 權限，擴充功能就不會顯示任何權限 警告，而使用者點擊額外資訊動作時，廣告只會在相關網頁上放送。

網頁網址比對

滿足網址條件時，PageStateMatcher.pageurl 會達成比對。 最常見的條件為主機、路徑或網址，後面依序接有「包含」、「等於」、「前置字元」或 後稱謂。下表包含幾個範例：

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

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

CSS 比對

PageStateMatcher.css 條件必須是複合選取器， 因此不能包含空白字元或「>」等合併符號在您的 選取器程式碼這有助於 Chrome 更有效率地比對選取器。

複合選取器 (確定) 複雜選取器 (未通過)
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

    string[] 選填

    在與網頁主頁框相同的頁框中，比對陣列中所有 CSS 選取器是否皆與頁框中的顯示元素相符。此陣列中的所有選取器都必須是複合選取器，才能加快比對速度。注意：如果單頁列出數百個 CSS 選取器，或是列出單頁比對結果數百次的 CSS 選取器，可能會導致網站運作速度變慢。

  • isBookmarked

    布林值 選填

    Chrome 45 以上版本

    比對網頁的書籤狀態是否等於指定值。授予書籤權限。

  • pageUrl

    UrlFilter 選用

    比對網頁的頂層網址是否符合 UrlFilter 的條件。

RequestContentScript

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

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

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

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

  • allFrames

    布林值 選填

    內容指令碼會在相符網頁的所有頁框中執行，或僅在頂端頁框執行。預設值為 false。

  • CSS

    string[] 選填

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

  • js

    string[] 選填

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

  • matchAboutBlank

    布林值 選填

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

SetIcon

在符合相應條件的情況下，用於設定擴充功能的網頁動作或瀏覽器動作的 n-dip 正方形圖示。這項操作可在沒有主機權限的情況下使用，但這項擴充功能必須含有網頁或瀏覽器動作。

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

屬性

  • 建構函式

    void

    constructor 函式如下所示： 

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

  • 圖片資料

    ImageData |物件 optional

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

ShowAction

Chrome 97 以上版本

宣告式事件動作，可在符合相應條件時，將擴充功能的工具列動作設為已啟用狀態。這項操作可以在沒有主機權限的情況下使用。如果擴充功能擁有 activeTab 權限，點選網頁動作即可授權存取使用中分頁。

如果在網頁不符合條件時，使用者動作不符合擴充功能的工具列動作，就會顯示灰階，點選該按鈕即可開啟內容選單，而不會觸發動作。

屬性

ShowPageAction

自 Chrome 97 版起已淘汰

請使用 declarativeContent.ShowAction。

宣告式事件動作，可在符合相應條件時，將擴充功能的網頁動作設為已啟用狀態。你可在沒有主機權限的情況下執行這項操作，但擴充功能必須設有網頁動作。如果擴充功能擁有 activeTab 權限，點選網頁動作即可授權存取使用中分頁。

如果在網頁不符合條件時，使用者動作不符合擴充功能的工具列動作，就會顯示灰階，點選該按鈕即可開啟內容選單，而不會觸發動作。

屬性

活動

onPageChanged

提供由 addRules、removeRules 和 getRules 組成的宣告式事件 API。

條件

PageStateMatcher

動作

RequestContentScript

SetIcon

ShowPageAction

ShowAction