browser.events

說明

chrome.events 命名空間包含 API 用來傳送事件的常見型別，可在發生有趣事件時通知您。

概念和用途

Event 是物件，可讓您在發生值得關注的事件時收到通知。以下範例說明如何使用 browser.alarms.onAlarm 事件，在鬧鐘響起時接收通知：

browser.alarms.onAlarm.addListener((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 引擎中評估，因此可減少往返延遲，並大幅提升效率。

舉例來說，宣告式事件處理常式用於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，也不得使用空白 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 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
偏好
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

在 events.UrlFilter 中，優先使用子字串比對，而非規則運算式。以子字串為準的比對速度極快。

而不是：
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
偏好
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

如果許多規則共用相同動作，請將這些規則合併為一。只要符合其中一項條件，規則就會觸發動作。這能加快比對速度，並減少重複動作集的記憶體用量。

而不是：
const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
偏好
const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

篩選後的事件

篩選事件機制可讓監聽器指定感興趣的事件子集。如果事件未通過篩選條件，系統就不會為使用篩選條件的監聽器叫用事件，這可讓監聽程式碼更具宣告性，也更有效率。Service Worker不必喚醒來處理不相關的事件。

篩選後的事件可讓您從手動篩選程式碼轉換。

而不是：
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
偏好
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

事件支援對該事件有意義的特定篩選器。事件支援的篩選器清單會列在該事件的「filters」部分文件中。

比對網址時 (如上例所示)，事件篩選器支援與 events.UrlFilter 可表達的網址比對功能相同的網址比對功能，但架構和連接埠比對除外。

類型

Event

這個物件可新增及移除 Chrome 事件的監聽器。

屬性

  • addListener

    void

    向事件註冊事件監聽器回呼。

    addListener 函式如下所示： 

    (callback: H) => {...}

    • callback

      H

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

  • addRules

    void

    註冊規則來處理事件。

    addRules 函式如下所示： 

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

    • 規則

      規則<anyany>[]

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

    • callback

      函式 選填

      callback 參數如下： 

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

      • 規則

        規則<anyany>[]

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

  • getRules

    void

    傳回目前已註冊的規則。

    getRules 函式如下所示： 

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      字串陣列 選用

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

    • callback

      函式

      callback 參數如下： 

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

      • 規則

        規則<anyany>[]

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

  • hasListener

    void

    hasListener 函式如下所示： 

    (callback: H) => {...}

    • callback

      H

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

    • returns

      布林值

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

  • hasListeners

    void

    hasListeners 函式如下所示： 

    () => {...}

    • returns

      布林值

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

  • removeListener

    void

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

    removeListener 函式如下所示： 

    (callback: H) => {...}

    • callback

      H

      要取消註冊的事件監聽器。

  • removeRules

    void

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

    removeRules 函式如下所示： 

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

      字串陣列 選用

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

    • callback

      函式 選填

      callback 參數如下： 

      () => void

Rule

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

屬性

  • 作業

    不限 []

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

  • conditions

    不限 []

    可觸發動作的條件清單。

  • 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) 以指定字串結尾，即為相符。如果通訊埠號碼與預設通訊埠號碼相符，系統會從網址中移除通訊埠號碼。