chrome.events

refresh date: 2026-09-25 robots: noindex

說明

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 物件，其中包含有關經過時間的鬧鐘詳細資料。

使用 Events 的 API 範例：alarms、i18n、identity、runtime。大多數 Chrome API 都是如此。

宣告式事件處理常式

宣告式事件處理常式提供定義規則的方法，規則包含宣告式條件和動作。條件是在瀏覽器中而非 JavaScript 引擎中評估，因此可減少往返延遲，並達到極高的效率。

舉例來說，Declarative Web Request API 和 Declarative 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 相同，也不得為空白 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

    向事件註冊事件監聽器 callback。

    addListener 函式如下所示： 

    (callback: H) =& gt;{...}

    • callback

      H

      事件發生時呼叫。這項函式的參數取決於事件類型。

  • addRules

    void

    註冊規則來處理事件。

    addRules 函式如下所示： 

    (rules: Rule<anyany>[], callback?: function) =& gt;{...}

    • 規則

      規則<anyany>[]

      要註冊的規則。這些規則不會取代先前註冊的規則。

    • callback

      函式 選填

      callback 參數如下： 

      (rules: Rule<anyany>[]) =& gt;void

      • 規則

        規則<anyany>[]

        已註冊的規則，選用參數會填入值。

  • getRules

    void

    傳回目前已註冊的規則。

    getRules 函式如下所示： 

    (ruleIdentifiers?: string[], callback: function) =& gt;{...}

    • ruleIdentifiers

      字串陣列 選用

      如果傳遞陣列，系統只會傳回含有此陣列中 ID 的規則。

    • callback

      函式

      callback 參數如下： 

      (rules: Rule<anyany>[]) =& gt;void

      • 規則

        規則<anyany>[]

        已註冊的規則，選用參數會填入值。

  • hasListener

    void

    hasListener 函式如下所示： 

    (callback: H) =& gt;{...}

    • callback

      H

      要測試註冊狀態的接聽者。

    • returns

      布林值

      如果 callback 已註冊至事件，則為 True。

  • hasListeners

    void

    hasListeners 函式如下所示： 

    () =& gt;{...}

    • returns

      布林值

      如果已為事件註冊任何事件監聽器，則為 True。

  • removeListener

    void

    從事件中取消註冊事件監聽器 callback。

    removeListener 函式如下所示： 

    (callback: H) =& gt;{...}

    • callback

      H

      要取消註冊的監聽器。

  • removeRules

    void

    取消註冊目前已註冊的規則。

    removeRules 函式如下所示： 

    (ruleIdentifiers?: string[], callback?: function) =& gt;{...}

    • ruleIdentifiers

      字串陣列 選用

      如果傳遞陣列，系統只會取消註冊含有這個陣列中 ID 的規則。

    • callback

      函式 選填

      callback 參數如下： 

      () =& gt;void

Rule

處理事件的宣告式規則說明。

屬性

  • 作業

    any[]

    如果符合其中一項條件，系統會觸發的動作清單。

  • conditions

    any[]

    可觸發動作的條件清單。

  • id

    字串 選填

    選用識別碼，可供參照這項規則。

  • 優先順序

    數字 選填

    這項規則的選用優先順序。預設值為 100。

  • 標記

    字串陣列 選用

    標記可用於註解規則，以及對規則集執行作業。

UrlFilter

依據各種條件篩選網址。請參閱事件篩選。所有條件都區分大小寫。

屬性

  • cidrBlocks

    字串陣列 選用

    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

    字串 選填

    如果網址的查詢片段結尾為指定字串，系統就會比對成功。

  • 配置

    字串陣列 選用

    如果網址的配置等於陣列中指定的任何配置，即為相符。

  • urlContains

    字串 選填

    如果網址 (不含片段 ID) 包含指定字串，系統就會比對成功。如果通訊埠編號與預設通訊埠編號相符，系統會從網址中移除通訊埠編號。

  • urlEquals

    字串 選填

    如果網址 (不含片段 ID) 等於指定字串，就會相符。如果通訊埠編號與預設通訊埠編號相符，系統會從網址中移除通訊埠編號。

  • urlMatches

    字串 選填

    如果網址 (不含片段 ID) 符合指定的規則運算式，系統就會比對成功。如果通訊埠編號與預設通訊埠編號相符，系統會從網址中移除通訊埠編號。規則運算式使用 RE2 語法。

  • urlPrefix

    字串 選填

    如果網址 (不含片段 ID) 以指定字串開頭，系統就會比對成功。如果通訊埠編號與預設通訊埠編號相符，系統會從網址中移除通訊埠編號。

  • urlSuffix

    字串 選填

    如果網址 (不含片段 ID) 結尾為指定字串，即為相符。如果通訊埠編號與預設通訊埠編號相符，系統會從網址中移除通訊埠編號。