chrome.events

      chrome.alarms.onAlarm.addListener(function(alarm) {
        appendToLog('alarms.onAlarm --'
                    + ' 名称：'          + alarm.name
                    + ' 计划的时间：' + alarm.scheduledTime);
      });
      

声明式事件处理程序

声明式事件处理程序提供了一种方式，来定义由声明式条件与操作组成的规则。条件将在浏览器而不是 JavaScript 引擎中求值，因而减少了来回的延迟，并提供极高的效率。

声明式事件处理程序在诸如声明式网络请求 API 与 声明式内容 API中使用，该网页描述所有声明式事件处理程序背后的概念。

规则

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

      var rule = {
        conditions: [ /* 我的条件 */ ],
        actions: [ /* 我的规则 */ ]
      };
      

如果任何一个条件满足，则执行所有的操作。

除了条件和操作外，您还可以为每一条规则提供标志符，这样可以更简单地取消注册之前注册的规则，以及通过优先级定义规则间的优先顺序。只有当规则互相之间冲突或者需要以特定的顺序执行时才会考虑优先级。操作以对应规则优先级从大到小的顺序执行。

      var rule = {
        id: "my rule",  // 可选，如果没有设置会自动生成。
        priority: 100,  // 可选，默认为 100。
        conditions: [ /* 我的条件 */ ],
        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 中的每条规则都必须包含其他规则当前没有使用的唯一标志符，或者为空标志符。

注意：规则在浏览器会话间持久存在，所以您应该使用 runtime.onInstalled 在扩展程序安装期间安装规则。注意该事件在扩展程序更新时也会触发，所以您应该首先清除之前安装的规则并注册新规则。

移除规则

要移除规则，请调用 removeRules() 函数。它接受的第一个参数为可选的规则标志符数组，第二个参数为回调函数。

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

如果 rule_ids 为包含标志符的数组，将移除具有数组中所列出的标志符的规则。如果 rule_ids 包含未知标志符，将忽略该标志符。如果 rule_ids 为 undefined，将移除当前扩展程序注册的所有规则。规则移除后将调用 callback()函数。

获取规则

要获取当前已注册规则的列表，请调用 getRules() 函数，它接受的第一个参数为可选的规则标志符数组，与 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'}]});
      

事件支持对于某个事件有意义的特定过滤器，事件支持的过滤器列表将在事件文档的“过滤器”部分列出。

当匹配 URL 时（如上如例子所示），除了协议与端口的匹配，事件过滤器支持与 events.UrlFilter 相同的 URL 匹配能力。