本頁面由 Cloud Translation API 翻譯而成。

chrome.declarativeContent

說明

使用 chrome.declarativeContent API 可根據網頁內容採取行動，且無須取得讀取網頁內容的權限。

權限

declarativeContent

概念和用法

宣告式內容 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 條件可讓您比對使用者個人資料中目前網址的書籤狀態。如要使用這項條件，請務必在擴充功能manifest中宣告「書籤」權限。

類型

ImageDataType

請參閱 https://developer.mozilla.org/en-US/docs/Web/API/ImageData。

類型

ImageData

PageStateMatcher

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

屬性

建構函式

void

constructor 函式如下所示：
```
(arg: PageStateMatcher) => {...}
```
- arg
  
  PageStateMatcher
- returns
  PageStateMatcher
CSS

string[] 選填

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

boolean 選填

Chrome 45 以上版本

如果網頁的書籤狀態等於指定值，則會進行比對。需要書籤權限。
pageUrl

UrlFilter 選填

如果網頁的頂層網址符合 UrlFilter 的條件，則會比對成功。

RequestContentScript

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

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

屬性

建構函式

void

constructor 函式如下所示：
```
(arg: RequestContentScript) => {...}
```
- arg
  
  RequestContentScript
- returns
  RequestContentScript
allFrames

boolean 選填

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

string[] 選填

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

string[] 選填

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

boolean 選填

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

SetIcon

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

必須指定 imageData 或 path 其中一個。兩者都是字典，可將像素數量對應至圖像表示法。imageData 中的圖片表示法是 ImageData 物件，例如來自 canvas 元素；path 中的圖片表示法則是相對於擴充功能資訊清單的圖片檔案路徑。如果 scale 螢幕像素可放入裝置獨立像素，系統會使用 scale * n 圖示。如果沒有該比例，系統會將其他圖片調整為必要大小。

屬性

建構函式

void

constructor 函式如下所示：
```
(arg: SetIcon) => {...}
```
- arg
  
  SetIcon
- returns
  SetIcon
imageData

ImageData | 物件選用

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