chrome.events

說明

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 範例：alarms、i18n、identity、runtime。大部分 Chrome API 的依附元件。

宣告式事件處理常式

宣告式事件處理常式可讓您定義由宣告式條件組成的規則 和動作系統會透過瀏覽器 (而不是 JavaScript 引擎) 評估條件，因此能降低 往返延遲時間也很高

宣告式事件處理常式適用於宣告式 Web Request API 宣告式 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」中的每項規則都必須包含 目前沒有其他規則或空白的識別碼使用。

移除規則

如要移除規則，請呼叫 removeRules() 函式。它接受選用的規則 ID 陣列 做為其第一個參數，並透過回呼函式做為第二個參數。

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

如果 rule_ids 是 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]);

篩選後的事件

篩選後的事件是一種機制，可讓事件監聽器指定其所符合的部分事件 使用篩選器的事件不會針對未傳遞 篩選器，讓聆聽程式碼更容易宣告式程式碼，更有效率。服務工作人員需求 讓使用者難以處理自身無關的事件。

篩選事件的用意是讓手動篩選程式碼產生轉換，如下所示：

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) => {...}

    • 規則

      規則<任意>[]

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

    • 回呼

      函式 選用

      callback 參數如下所示： 

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

      • 規則

        規則<任意>[]

        註冊規則後，選用參數就會填入值。

  • getRules

    void

    傳回目前已註冊的規則。

    getRules 函式如下所示： 

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

    • ruleIdentifiers

      string[] 選填

      如果傳遞陣列，系統只會傳回具備這個陣列中 ID 的規則。

    • 回呼

      函式

      callback 參數如下所示： 

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

      • 規則

        規則<任意>[]

        註冊規則後，選用參數就會填入值。

  • hasListener

    void

    hasListener 函式如下所示： 

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

    • 回呼

      H

      應測試註冊狀態的接聽程式。

    • returns

      布林值

      如果事件已登錄回呼，則為 True。

  • hasListeners

    void

    hasListeners 函式如下所示： 

    () => {...}

    • returns

      布林值

      如果事件已登錄任何事件監聽器，則為 True。

  • removeListener

    void

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

    removeListener 函式如下所示： 

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

    • 回呼

      H

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

  • removeRules

    void

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

    removeRules 函式如下所示： 

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

    • ruleIdentifiers

      string[] 選填

      如果傳送了陣列，則只有具備此陣列中 ID 的規則會取消註冊。

    • 回呼

      函式 選用

      callback 參數如下所示： 

      () => void

Rule

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

屬性

  • 作業

    任何 []

    符合任一條件時觸發的動作清單。

  • conditions

    任何 []

    可觸發動作的條件清單。

  • id

    string optional

    允許參照這項規則的選用 ID。

  • 優先順序

    編號 選填

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

  • 標記

    string[] 選填

    標記可用於為規則組合加註及執行操作。

UrlFilter

依不同條件篩選網址。請參閱事件篩選相關說明。所有條件都必須區分大小寫。

屬性

  • cidrBlocks

    string[] 選填

    Chrome 123 以上版本

    比對網址的主機部分是否為 IP 位址，且包含在陣列中指定的任何 CIDR 區塊中。

  • hostContains

    string optional

    比對網址的主機名稱是否包含指定字串。如要測試主機名稱元件是否含有前置字串「foo」，請使用 hostContains:「.foo」。與「www.foobar.com」相符和「foo.com」，因為主機名稱開頭會加上一個隱含點。同樣地， hostContains 也可用來比對元件後置字串 (「foo.」)，以及與元件 (「.foo.」) 完全相符。由於主機名稱結尾不會加上隱含點，因此最後一個元件的後置字串和完全相符的項目必須使用 hostSuffix 個別完成。

  • hostEquals

    string optional

    比對網址的主機名稱是否等於指定字串。

  • hostPrefix

    string optional

    比對網址主機名稱是否以指定字串開頭。

  • hostSuffix

    string optional

    比對網址的主機名稱是否以指定字串結尾。

  • originAndPathMatches

    string optional

    比對不含查詢片段和片段 ID 的網址是否符合指定的規則運算式。如果通訊埠號碼與預設的通訊埠號碼相符，就會從網址中移除。規則運算式使用 RE2 語法。

  • pathContains

    string optional

    比對網址的路徑部分是否包含指定字串。

  • pathEquals

    string optional

    比對網址的路徑區段是否等於指定字串。

  • pathPrefix

    string optional

    比對網址的路徑區段是否以指定字串開頭。

  • pathSuffix

    string optional

    比對網址的路徑區段是否以指定字串結尾。

  • ports

    (number | number[])[] 選填

    比對網址的通訊埠是否包含在任何指定的通訊埠清單中。舉例來說，[80, 443, [1000, 1200]] 會比對通訊埠 80、443 和範圍 1000-1200 中的所有要求。

  • queryContains

    string optional

    比對網址的查詢部分是否包含指定字串。

  • queryEquals

    string optional

    比對網址的查詢部分是否等於指定字串。

  • queryPrefix

    string optional

    比對網址的查詢區段是否以指定字串開頭。

  • querySuffix

    string optional

    比對網址的查詢區段是否以指定字串結尾。

  • 計劃

    string[] 選填

    比對網址的配置是否等於陣列中指定的任何配置。

  • urlContains

    string optional

    比對網址 (不含片段 ID) 是否含有指定字串。如果通訊埠號碼與預設的通訊埠號碼相符，就會從網址中移除。

  • urlEquals

    string optional

    比對網址 (不含片段 ID) 是否等於指定字串。如果通訊埠號碼與預設的通訊埠號碼相符，就會從網址中移除。

  • urlMatches

    string optional

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

  • urlPrefix

    string optional

    比對網址 (不含片段 ID) 的開頭是否為指定字串。如果通訊埠號碼與預設的通訊埠號碼相符，就會從網址中移除。

  • urlSuffix

    string optional

    比對網址 (不含片段 ID) 的結尾是否為指定字串。如果通訊埠號碼與預設的通訊埠號碼相符，就會從網址中移除。