說明
使用 chrome.declarativeContent
API 依據網頁內容執行動作,不必取得網頁內容的讀取權限。
權限
declarativeContent
概念和用法
有了宣告式 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
條件允許比對使用者個人資料中目前網址的書籤狀態。如要使用此條件,必須在擴充功能資訊清單中宣告「書籤」權限。
類型
ImageDataType
請參閱 https://developer.mozilla.org/en-US/docs/Web/API/ImageData。
類型
ImageData
PageStateMatcher
根據各種條件比對網頁狀態。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: PageStateMatcher) => {...}
-
arg
-
returns
-
-
css
string[] 選填
如果陣列中的所有 CSS 選取器都與頁框中所顯示的元素相符,且兩者的原點與網頁的主要頁框相同,則視為相符。這個陣列中的所有選取器都必須是複合選取器,才能加快比對速度。注意:如果只列出數百個 CSS 選取器,或每條網頁列出符合數百次的 CSS 選取器,可能會導致網站速度變慢。
-
isBookmarked
布林值 (選用)
Chrome 45 以上版本比對網頁的書籤狀態是否等於指定值。重新授予書籤權限。
-
pageUrl
UrlFilter 選用
比對是否滿足網頁的頂層網址
UrlFilter
條件。
RequestContentScript
插入內容指令碼的宣告式事件動作。
警告:這項動作仍在實驗階段,不適用於 Chrome 穩定版。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: RequestContentScript) => {...}
-
returns
-
-
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) => {...}
-
arg
-
returns
-
-
imageData
ImageData | 物件 選用
ImageData
物件或字典 {size -> ImageData},代表要設定圖示。如果圖示指定為字典,系統會根據螢幕的像素密度選擇要使用的圖片。如果適合單一螢幕空間單元的圖片像素數量等於scale
,系統就會選取大小為scale * n
的圖片,其中 n 是使用者介面中圖示的大小。至少須指定一張圖片。請注意,details.imageData = foo
等同於details.imageData = {'16': foo}
。
ShowAction
宣告事件動作會在符合相應條件時,將擴充功能的工具列動作設為啟用狀態。這個動作無需主機權限即可使用。如果擴充功能具備 activeTab 權限,點選頁面動作即可授予使用中分頁的存取權。
如果條件不符合擴充功能的工具列動作,系統會以灰階顯示。這樣一來,點按該圖示就會開啟內容選單,而不會觸發動作。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: ShowAction) => {...}
-
arg
-
returns
-
ShowPageAction
請使用 declarativeContent.ShowAction
。
宣告事件動作會在符合相應條件時,將擴充功能的頁面動作設為啟用狀態。這個動作無需主機權限即可使用,但擴充功能必須要有網頁動作。如果擴充功能具備 activeTab 權限,點選頁面動作即可授予使用中分頁的存取權。
如果條件不符合擴充功能的工具列動作,系統會以灰階顯示。這樣一來,點按該圖示就會開啟內容選單,而不會觸發動作。
屬性
-
建構函式
void
constructor
函式如下所示:(arg: ShowPageAction) => {...}
-
arg
-
returns
-
活動
onPageChanged
提供由 addRules
、removeRules
和 getRules
組成的宣告式事件 API。