本頁面由 Cloud Translation API 翻譯而成。

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 範例：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。

移除規則

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

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

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