chrome.declarativeContent

說明

使用 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 更有效率地比對選取器。

複合選取器 (確定) 複雜選取器 (未通過)
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:blankabout:srcdoc 上插入內容指令碼。預設值為 false

SetIcon

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

必須明確指定 imageDatapath 其中之一。兩者都是字典,將數字對應到圖片形式。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

提供由 addRulesremoveRulesgetRules 組成的宣告式事件 API