說明
chrome.events
命名空間包含 API 分派事件經常使用的類型,會在發生有趣事件時通知您。
Event
物件可讓您在發生有趣的事件時收到通知。以下範例說明如何在鬧鐘過後使用 chrome.alarms.onAlarm
事件接收通知:
chrome.alarms.onAlarm.addListener(function(alarm) {
appendToLog('alarms.onAlarm --'
+ ' name: ' + alarm.name
+ ' scheduledTime: ' + alarm.scheduledTime);
});
如範例所示,您必須使用 addListener()
註冊通知。addListener()
的引數一律是您定義用來處理事件的函式,但函式的參數則視您處理的事件而定。您可以查看 alarms.onAlarm
的說明文件,瞭解該函式只有單一參數:alarms.Alarm
物件,其中包含了經過的鬧鐘詳細資料。
使用事件的 API 範例:鬧鐘、i18n、identity、runtime。大多數 Chrome API 都會執行這項操作。
宣告式事件處理常式
宣告式事件處理常式可讓您定義由宣告條件和動作組成的規則。系統會直接在瀏覽器中評估條件,而不是透過 JavaScript 引擎評估,這可減少往返延遲時間,進而提高效率。
宣告式事件處理常式和宣告式 Content API 會使用宣告式事件處理常式。本頁說明所有宣告式事件處理常式的基本概念。
規則
最簡單的可能規則包含一或多個條件和一或多個動作:
var rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
只要符合任一條件,系統就會執行所有動作。
除了條件和動作之外,您可以為每項規則提供 ID,以簡化先前註冊的規則,並定義規則之間的優先順序。只有在規則彼此衝突或需要以特定順序執行時,才會考慮優先順序。系統會根據規則的優先順序,遞減執行動作。
var rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
事件物件
事件物件可能支援規則。事件發生時,這些事件物件不會呼叫回呼函式,但請測試任何註冊的規則是否至少具備一項已達成的條件,並執行與這項規則相關聯的動作。支援宣告式 API 的事件物件有三種相關方法:events.Event.addRules
、events.Event.removeRules
和 events.Event.getRules
。
新增規則
如要新增規則,請呼叫事件物件的 addRules()
函式。它將規則例項的陣列做為第一個參數,以及在完成時呼叫的回呼函式。
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
如果成功插入規則,details
參數會包含插入規則的陣列,順序與傳遞的 rule_list
中相同,其中選用參數 id
和 priority
已填入系統產生的值。如果任何規則無效,例如因為包含無效的條件或動作,則不會新增任何規則,且系統會在呼叫回呼函式時設定 runtime.lastError 變數。rule_list
中的每個規則都必須包含目前沒有其他規則使用的專屬 ID,或是空白的 ID。
移除規則
如要移除規則,請呼叫 removeRules()
函式。它接受選用的規則 ID 陣列做為第一個參數,以及回呼函式做為第二個參數。
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
如果 rule_ids
是 ID 陣列,系統會移除陣列中列出 ID 的所有規則。如果 rule_ids
列出不明的 ID,系統會自動忽略這個 ID。如果 rule_ids
為 undefined
,系統會移除這項擴充功能的所有已註冊規則。系統會在移除規則時呼叫 callback()
函式。
擷取規則
如要擷取目前註冊的規則清單,請呼叫 getRules()
函式。它接受選用的規則 ID 陣列,其語意與 removeRules
及回呼函式相同。
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});
傳遞至 callback()
函式的 details
參數是規則陣列,包含已填入的選用參數。
效能
為達到最佳成效,請謹記以下原則。
大量註冊及取消註冊規則。每次註冊或取消註冊後,Chrome 都需要更新內部資料結構。這項更新需要耗費大量資源,
而不是這樣
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
偏好:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
建議先比對子字串,而不是 events.UrlFilter 中的規則運算式。 以子字串為基礎的比對速度極快。
而不是這樣
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" } });
偏好:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {hostSuffix: "example.com", pathContains: "foo"} });
如有多項規則共用相同的動作,請將這些規則合併成一項。 規則會在滿足單一條件時立即觸發動作。這會加快比對速度,並減少重複動作集的記憶體消耗。
而不是這樣
var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } });
var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' } });
var rule1 = { conditions: [condition1],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
var rule2 = { conditions: [condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
偏好:
var rule = { conditions: [condition1, condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule]);
篩選事件
篩選事件是一種機制,可讓事件監聽器指定他們感興趣的部分事件。如果事件未通過篩選器,系統就不會叫用使用篩選器的事件監聽器,這可讓監聽程式碼更具宣告式與效率。Service Worker 不須喚醒即可處理不重要的事件。
篩除事件的用途是從手動篩選程式碼進行轉換,如下所示:
chrome.webNavigation.onCommitted.addListener(function(e) {
if (hasHostSuffix(e.url, 'google.com') ||
hasHostSuffix(e.url, 'google.com.au')) {
// ...
}
});
轉換為:
chrome.webNavigation.onCommitted.addListener(function(e) {
// ...
}, {url: [{hostSuffix: 'google.com'},
{hostSuffix: 'google.com.au'}]});
事件支援特定篩選器,方便該事件觸發。事件支援的篩選器清單會列在該事件的說明文件中 (位於「篩選器」部分)。
比對網址時 (如上例所示),事件篩選器支援與使用 events.UrlFilter
表達相同的網址比對功能,但配置和通訊埠比對除外。
類型
Event
此物件允許新增及移除 Chrome 事件的事件監聽器。
屬性
-
addListener
void
註冊事件事件監聽器的回呼。
addListener
函式如下所示:(callback: H) => {...}
-
回呼
H
在事件發生時呼叫。這個函式的參數取決於事件類型。
-
-
addRules
void
註冊處理事件的規則。
addRules
函式如下所示:(rules: Rule<anyany>[], callback?: function) => {...}
-
getRules
void
傳回目前註冊的規則。
getRules
函式如下所示:(ruleIdentifiers?: string[], callback: function) => {...}
-
hasListener
void
hasListener
函式如下所示:(callback: H) => {...}
-
回呼
H
應測試註冊狀態的事件監聽器。
-
returns
boolean
如果事件已註冊回呼,則為 True。
-
-
hasListeners
void
hasListeners
函式如下所示:() => {...}
-
returns
boolean
如果事件已登錄到事件,則為 true。
-
-
removeListener
void
從事件中取消註冊事件監聽器回呼。
removeListener
函式如下所示:(callback: H) => {...}
-
回呼
H
應取消註冊的監聽器。
-
-
removeRules
void
取消註冊目前註冊的規則。
removeRules
函式如下所示:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] 選填
如果傳遞陣列,只有包含此陣列內含 ID 的規則才會取消註冊。
-
回呼
函式選用
callback
參數如下所示:() => void
-
Rule
說明用於處理事件的宣告式規則。
屬性
-
作業
任何 []
當滿足其中一項條件時,就會觸發動作清單。
-
conditions
任何 []
這些條件清單,說明可觸發動作的條件。
-
id
字串 選用
可參照這項規則的選用 ID。
-
優先順序
數字 選填
這項規則的選擇性優先順序。預設值為 100。
-
標記
string[] 選填
標記可用來為規則加上註解,以及對一組規則執行作業。
UrlFilter
針對各種條件篩選網址。請參閱事件篩選。所有條件均須區分大小寫。
屬性
-
cidrBlocks
string[] 選填
Chrome 123 以上版本如果網址的主機部分是 IP 位址,且包含在陣列中指定的任何 CIDR 區塊中,就會進行比對。
-
hostContains
字串 選用
比對網址主機名稱是否包含指定字串。如要測試主機名稱元件是否含有前置字串「foo」,請使用 hostContains: '.foo'。它與「www.foobar.com」和「foo.com」相符,因為在主機名稱開頭加上隱含的點。同樣地,hostContains 可以與元件後置字串 (「foo.」) 進行比對,以及與元件 (「.foo.」) 進行比對。由於未在主機名稱結尾加上任何隱含點,因此您需要使用 hostSuffix 個別完成後置字串的後置字串以及完全比對。
-
hostEquals
字串 選用
比對網址的主機名稱是否等於指定字串。
-
hostPrefix
字串 選用
比對網址主機名稱的開頭是否為指定字串。
-
hostSuffix
字串 選用
比對網址主機名稱結尾是否為指定字串。
-
originAndPathMatches
字串 選用
比對不含查詢片段和片段 ID 的網址是否符合指定的規則運算式。如果通訊埠編號與預設通訊埠號碼相符,系統會刪除網址中的通訊埠編號。規則運算式使用 RE2 語法。
-
pathContains
字串 選用
比對網址路徑部分是否包含指定字串。
-
pathEquals
字串 選用
比對網址路徑部分是否等於指定字串。
-
pathPrefix
字串 選用
比對網址路徑部分是否以指定字串開頭。
-
pathSuffix
字串 選用
比對網址路徑部分結尾是否為指定字串。
-
ports
(number | number[])[] 選填
比對網址的通訊埠是否列在任何指定的通訊埠清單中。舉例來說,
[80, 443, [1000, 1200]]
會比對通訊埠 80、443 且範圍介於 1000-1200 中的所有要求。 -
queryContains
字串 選用
比對網址查詢區段是否包含指定字串。
-
queryEquals
字串 選用
比對網址查詢部分是否等於指定字串。
-
queryPrefix
字串 選用
比對網址查詢區段開頭是否為指定字串。
-
querySuffix
字串 選用
比對網址查詢區段結尾是否為指定字串。
-
schemes
string[] 選填
比對網址配置與陣列中指定的任何配置時相符。
-
urlContains
字串 選用
比對網址 (不含片段 ID) 是否包含指定字串。如果通訊埠編號與預設通訊埠號碼相符,系統會刪除網址中的通訊埠編號。
-
urlEquals
字串 選用
比對網址 (不含片段 ID) 是否等於指定字串。如果通訊埠編號與預設通訊埠號碼相符,系統會刪除網址中的通訊埠編號。
-
urlMatches
字串 選用
比對網址 (不含片段 ID) 是否符合指定的規則運算式。如果通訊埠編號與預設通訊埠號碼相符,系統會刪除網址中的通訊埠編號。規則運算式使用 RE2 語法。
-
urlPrefix
字串 選用
比對網址 (不含片段 ID) 的開頭是否為指定字串。如果通訊埠編號與預設通訊埠號碼相符,系統會刪除網址中的通訊埠編號。
-
urlSuffix
字串 選用
比對網址 (不含片段 ID) 的結尾是否為指定字串。如果通訊埠編號與預設通訊埠號碼相符,系統會刪除網址中的通訊埠編號。