chrome.events

说明

概念和用法

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 */ ]
};

事件对象

Event 对象可能支持规则。当事件发生时，这些事件对象不会调用回调函数，但会测试任何注册的规则是否至少有一个已满足的条件，并执行与此规则关联的操作。支持声明式 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'}]});

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

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