chrome.events

說明

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 範例:alarmsi18nidentityruntime大部分 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 相同,其中選用的參數 idpriority已填入產生的值。如有任何規則無效 (例如規則包含 條件或動作無效,則不會新增任何規則以及 runtime.lastError 變數 會在呼叫回呼函式時設定。「rule_list」中的每項規則都必須包含 ID 未用於其他規則或空白的 ID。

移除規則

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

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

如果 rule_ids 是 ID 陣列,則陣列中列出的所有規則都會是 已移除如果 rule_ids 列出不明 ID,則會在不發出通知的情況下略過這個 ID。如果 rule_idsundefined,請移除這則擴充功能的所有註冊規則。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]);

篩選後的事件

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

篩選事件的用意是讓這類程式碼從手動篩選程式碼轉換。

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

    • 規則

      規則<任意>[]

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

    • 回呼

      函式 選用

      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) 的結尾是否為指定字串。如果通訊埠號碼與預設的通訊埠號碼相符,就會從網址中移除。