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

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

宣告式事件處理常式

宣告式事件處理常式可讓您定義由宣告式條件和動作組成的規則。條件會在瀏覽器中評估，而不是在 JavaScript 引擎中評估，這樣可以減少往返延遲，並提高效率。

舉例來說，Declarative 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 重複。

注意：規則在瀏覽工作階段中會持續生效。因此，您應在安裝擴充功能時，使用 runtime.onInstalled 事件安裝規則。請注意，更新擴充功能時也會觸發這個事件。因此，您應先清除先前安裝的規則，再註冊新規則。

移除規則

如要移除規則，請呼叫 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'}]});

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

比對網址時 (如上例所示)，事件篩選器支援與 events.UrlFilter 相同的網址比對功能，但通訊協定和通訊埠比對除外。

類型

Event

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

屬性

• addListener

  void

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

  addListener 函式如下所示：

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

  • callback

    H

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

• addRules

  void

  註冊規則來處理事件。

  addRules 函式如下所示：

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

  • 規則

    Rule<anyany>[]

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

  • callback

    函式 選填

    callback 參數如下：

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

    • 規則

      Rule<anyany>[]

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

• getRules

  void

  傳回目前註冊的規則。

  getRules 函式如下所示：

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

  • ruleIdentifiers

    string[] 選填

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

  • callback

    函式

    callback 參數如下：

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

    • 規則

      Rule<anyany>[]

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

• hasListener

  void

  hasListener 函式如下所示：

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

  • callback

    H

    要測試註冊狀態的事件監聽器。

  • returns

    布林值

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

• hasListeners

  void

  hasListeners 函式如下所示：

  () => {...}

  • returns

    布林值

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

• removeListener

  void

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

  removeListener 函式如下所示：

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

  • callback

    H

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

• removeRules

  void

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

  removeRules 函式如下所示：

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

  • ruleIdentifiers

    string[] 選填

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

  • callback

    函式 選填

    callback 參數如下：

    () => void

Rule

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

屬性

• 作業

  any[]

  符合其中一項條件時觸發的動作清單。

• conditions

  any[]

  可觸發動作的條件清單。

• id

  字串 選填

  選用的 ID，可用於參照這項規則。

• 優先順序

  數字 選填

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

• 標記

  string[] 選填

  標記可用來為規則加上註解，以及對一組規則執行操作。

UrlFilter

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

屬性

• cidrBlocks

  string[] 選填

  Chrome 123 以上版本 Chrome 148 以上版本支援 browser.*

  如果網址的主機部分是 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

  字串 選填

  如果網址的查詢區隔結尾為指定字串，則視為相符。

• 配置

  string[] 選填

  如果網址的配置與陣列中指定的任何配置相同，即符合條件。

• urlContains

  字串 選填

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

• urlEquals

  字串 選填

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

• urlMatches

  字串 選填

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

• urlPrefix

  字串 選填

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

• urlSuffix

  字串 選填

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