此页面由 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 引擎中评估的，这样可以减少并实现极高的效率

声明式事件处理脚本用于声明式 Content API。本页介绍了所有声明式事件的基本概念处理程序。

规则

最简单的规则是包含一个或多个条件以及一项或多项操作：

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

如果满足其中任一条件，则执行所有操作。

除了条件和操作之外，您还可以为每条规则指定一个标识符，这样可以简化取消注册先前注册的规则，以及定义规则优先级的优先级。只有在规则之间相互冲突或需要在特定环境中执行时，系统才会考虑优先级订单。操作按其规则优先级的降序执行。

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 中的每条规则都必须包含一个唯一的其他规则尚未使用的标识符或空标识符。

移除规则

如需移除规则，请调用 removeRules() 函数。它接受一组规则标识符（可选）作为其第一个参数，并将回调函数作为其第二个参数。

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

如果 rule_ids 是一个标识符数组，则所有在数组中列出标识符的规则都是已移除。如果 rule_ids 列出了未知的标识符，系统会以静默方式忽略此标识符。如果 rule_ids 为 undefined，此扩展程序的所有已注册规则均已移除。callback() 函数会在规则被删除时调用。

检索规则

如需检索已注册规则的列表，请调用 getRules() 函数。它接受可选的规则标识符数组，其语义与 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]);

过滤出的活动

过滤事件是一种机制，可让监听器指定它们属于。不会针对未传递过滤器，这使得监听代码更具声明性和效率。Service Worker 需求被唤醒以处理其不关心的事件。

被滤除的事件旨在让手动过滤代码顺利过渡。

而不是

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'}]});

事件支持对该事件有意义的特定过滤条件。事件可过滤的过滤条件的列表支持将会在该事件的文档的“filters”部分中列出部分。

匹配网址时（如上例所示），事件过滤器支持同一网址匹配可通过 events.UrlFilter 表达的功能（架构和端口匹配除外）。

类型

Event

一个对象，用于添加和移除 Chrome 事件监听器。

属性

添加监听器

void

为事件注册事件监听器回调。

addListener 函数如下所示：
```
(callback: H) => {...}
```
- callback
  
  H
  
  在事件发生时调用。此函数的参数取决于事件类型。
addRules

void

注册用于处理事件的规则。

addRules 函数如下所示：
```
(rules: Rule<anyany>[], callback?: function) => {...}
```
- 规则
  
  规则<any>[]
  
  要注册的规则。这些规则不会取代以前注册的规则。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
(rules: Rule<anyany>[]) => void
```
  - 规则
    
    规则<any>[]
    
    已注册规则，可选参数会填入值。
getRules

void

返回当前注册的规则。

getRules 函数如下所示：
```
(ruleIdentifiers?: string[], callback: function) => {...}
```
- ruleIdentifiers
  
  string[] 选填
  
  如果传递的是数组，则系统仅返回具有此数组所含标识符的规则。
- callback
  
  函数
  
  callback 参数如下所示：
```
(rules: Rule<anyany>[]) => void
```
  - 规则
    
    规则<any>[]
    
    已注册规则，可选参数会填入值。
hasListener

void

hasListener 函数如下所示：
```
(callback: H) => {...}
```
- callback
  
  H
  
  要测试其注册状态的监听器。
- 返回
  布尔值
  
  如果为事件注册了回调函数，则为 true。
hasListeners

void

hasListeners 函数如下所示：
```
() => {...}
```
- 返回
  布尔值
  
  如果有任何事件监听器已注册到该事件，则为 true。
removeListener

void

从事件中取消注册事件监听器回调。

removeListener 函数如下所示：
```
(callback: H) => {...}
```
- callback
  
  H
  
  应取消注册的监听器。
removeRules

void

取消注册当前已注册的规则。

removeRules 函数如下所示：
```
(ruleIdentifiers?: string[], callback?: function) => {...}
```
- ruleIdentifiers
  
  string[] 选填
  
  如果传递了一个数组，则系统只会取消注册此数组中所含的标识符的规则。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
() => void
```

Rule

对用于处理事件的声明式规则的说明。

属性

操作

任何 []

在满足其中一个条件时触发的操作的列表。
conditions

任何 []

可触发操作的条件列表。
id

字符串（可选）

允许引用此规则的可选标识符。
优先级

编号（选填）

此规则的可选优先级。默认值为 100。
标记

string[] 选填

标记可用于为规则添加注释，以及对规则集执行操作。

UrlFilter

根据各种条件过滤网址。请参阅事件过滤。所有条件均区分大小写。

属性

cidrBlocks

string[] 选填

Chrome 123 及更高版本

如果网址的主机部分是 IP 地址，并且包含在数组中指定的任何 CIDR 地址块中，则匹配。
hostContains

字符串（可选）

如果网址的主机名包含指定字符串，则匹配。如需测试主机名组件是否具有前缀“foo”，请使用 hostcontains: “.foo”。这与“www.foobar.com”一致和“foo.com”，因为在主机名的开头添加了隐式点。同样，hostcontains 可用于匹配组件后缀（“foo.”）及与组件（“.foo.”）完全匹配。由于在主机名末尾未添加隐式点，因此最后组件的后缀和完全匹配需要使用 host 最终到达网址后缀单独执行。
hostEquals

字符串（可选）

如果网址的主机名等于指定字符串，则匹配。
hostPrefix

字符串（可选）

如果网址的主机名以指定字符串开头，则匹配。
hostSuffix

字符串（可选）

如果网址的主机名以指定字符串结尾，则匹配。
originAndPathMatches

字符串（可选）

如果不带查询片段和片段标识符的网址与指定的正则表达式匹配，则匹配。如果端口号与默认端口号匹配，则会从网址中删除。正则表达式使用 RE2 语法。
pathContains

字符串（可选）

如果网址的路径段包含指定字符串，则匹配。
pathEquals

字符串（可选）

如果网址的路径段等于指定字符串，则匹配。
pathPrefix

字符串（可选）

如果网址的路径段以指定字符串开头，则匹配。
pathSuffix

字符串（可选）

如果网址的路径段以指定字符串结尾，则匹配。
ports

(number | number[])[] 选填

如果网址的端口包含在任何指定端口列表中，则匹配。例如，[80, 443, [1000, 1200]] 会匹配端口 80、443 上以及 1000-1200 范围内的所有请求。
queryContains

字符串（可选）

如果网址的查询段包含指定字符串，则匹配。
queryEquals

字符串（可选）

如果网址的查询段等于指定字符串，则匹配。
queryPrefix

字符串（可选）

如果网址的查询片段以指定字符串开头，则匹配。
querySuffix

字符串（可选）

如果网址的查询片段以指定字符串结尾，则匹配。
架构

string[] 选填

如果网址的架构等于数组中指定的任何架构，则匹配。
urlContains

字符串（可选）

如果网址（不含片段标识符）包含指定字符串，则匹配。如果端口号与默认端口号匹配，则会从网址中删除。
urlEquals

字符串（可选）

在网址（不含片段标识符）等于指定字符串时匹配。如果端口号与默认端口号匹配，则会从网址中删除。
urlMatches

字符串（可选）

如果网址（不带片段标识符）与指定的正则表达式匹配，则匹配。如果端口号与默认端口号匹配，则会从网址中删除。正则表达式使用 RE2 语法。
urlPrefix

字符串（可选）

如果网址（不带片段标识符）以指定字符串开头，则匹配。如果端口号与默认端口号匹配，则会从网址中删除。
urlSuffix

字符串（可选）

如果网址（无片段标识符）以指定字符串结尾，则匹配。如果端口号与默认端口号匹配，则会从网址中删除。