說明
chrome.events 命名空間包含 API 分派事件經常使用的類型，會在發生有趣事件時通知您。
概念和用法
Event 是一種物件，可讓您在發生有趣的事件時收到通知。以下範例說明如何在鬧鐘過後使用 chrome.alarms.onAlarm 事件接收通知：
chrome.alarms.onAlarm.addListener((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 會使用宣告式事件處理常式。本頁說明所有宣告式事件處理常式的基本概念。
規則
最簡單的可能規則包含一或多個條件和一或多個動作：
const rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
只要符合任一條件，系統就會執行所有動作。
除了條件和動作之外，您可以為每項規則提供 ID，以簡化先前註冊的規則，並定義規則之間的優先順序。只有在規則彼此衝突或需要以特定順序執行時，才會考慮優先順序。系統會根據規則的優先順序，遞減執行動作。
const 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() 函式。它將規則例項的陣列做為第一個參數，以及在完成時呼叫的回呼函式。
const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});
如果成功插入規則，details 參數會包含插入規則的陣列，順序與傳遞的 rule_list 中相同，其中選用參數 id 和 priority 已填入系統產生的值。如果任何規則無效，例如包含無效的條件或動作，則不會新增任何規則，且會在呼叫回呼函式時設定 runtime.lastError 變數。rule_list 中的每個規則都必須包含已有其他規則使用的專屬 ID，或是空白的 ID。
移除規則
如要移除規則，請呼叫 removeRules() 函式。它接受選用的規則 ID 陣列做為第一個參數，以及回呼函式做為第二個參數。
const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});
如果 rule_ids 是 ID 陣列，系統會移除陣列中列出 ID 的所有規則。如果 rule_ids 列出不明的 ID，系統會自動忽略這個 ID。如果 rule_ids 為 undefined，系統會移除這項擴充功能的所有已註冊規則。系統會在移除規則時呼叫 callback() 函式。
擷取規則
如要擷取已註冊規則的清單，請呼叫 getRules() 函式。它接受選用的規則 ID 陣列，其語意與 removeRules() 及回呼函式相同。
const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});
傳遞至 callback() 函式的 details 參數是規則陣列，包含已填入的選用參數。
效能
為達到最佳成效，請謹記以下原則。
大量註冊及取消註冊規則。每次註冊或取消註冊後，Chrome 都需要更新內部資料結構。這項更新需要耗費大量資源，
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
建議先比對子字串，而不是 events.UrlFilter 中的規則運算式。 以子字串為基礎的比對速度極快。
const match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" }
});
const match = new chrome.declarativeWebRequest.RequestMatcher({
url: {hostSuffix: "example.com", pathContains: "foo"}
});
如有許多規則都共用相同的動作，請將規則合併成單一規則。 規則會在滿足單一條件時立即觸發動作。這會加快比對速度，並減少重複動作集的記憶體消耗。
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' }
});
const condition2 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
actions: [new chrome.declarativeWebRequest.CancelRequest()]
};
const rule2 = { conditions: [condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' }
});
const condition2 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]
};
chrome.declarativeWebRequest.onRequest.addRules([rule]);
篩選事件
篩選事件是一種機制，可讓事件監聽器指定他們感興趣的部分事件。如果事件未通過篩選器，系統就不會叫用使用篩選器的事件監聽器，這可讓監聽程式碼更具宣告式與效率。Service Worker 不須喚醒即可處理不重要的事件。
篩除事件的用途是從手動篩選程式碼轉換。
chrome.webNavigation.onCommitted.addListener((event) => {
if (hasHostSuffix(event.url, 'google.com') ||
hasHostSuffix(event.url, 'google.com.au')) {
// ...
}
});
chrome.webNavigation.onCommitted.addListener((event) => {
// ...
}, {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) 的結尾是否為指定字串。如果通訊埠編號與預設通訊埠號碼相符，系統會刪除網址中的通訊埠編號。