This page was saved using WebZIP 7.0.3.1030 offline browser on 12/24/13 11:31:36.
Address: https://crxdoc-zh.appspot.com/extensions/events.html
Title: chrome.events - Google Chrome 扩展程序开发文档（非官方中文版）  •  Size: 68335

chrome.events

描述： 使用 chrome.events API 使您在感兴趣的事情发生时得到通知。
可用版本： 从 Chrome 21 开始稳定支持。

当发生一些您感兴趣的事情时，Event 对象可以使您收到通知。如下是一个使用 chrome.alarms.onAlarm 事件的例子，每当定时器触发时就收到通知： 

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

如这一例子所示，您使用 addListener() 注册来接收通知。addListener() 的参数总是一个您定义的处理事件的函数，但是函数的参数取决于您处理的事件。参考 alarms.onAlarm 的文档，您会看到该函数有一个参数：包含已触发定时器的 alarms.Alarm 对象。

声明式事件处理程序

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

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

规则

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

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

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

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

var rule = {
  id: "my rule",  // 可选，如果没有设置会自动生成。
  priority: 100,  // 可选，默认为 100。
  conditions: [ /* 我的条件 */ ],
  actions: [ /* 我的操作 */ ]
};

事件对象

事件对象可以支持规则。这样的事件对象在事件发生时不调用回调函数，而是测试已注册的规则中是否有至少一个满足的条件，并执行与该规则相关联的操作。支持声明式 API 的事件对象有三个有关方法：Event.addRules、Event.removeRules 以及 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]);
  • 在 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 时（如上如例子所示），除了协议与端口的匹配，事件过滤器支持与 UrlFilter 相同的 URL 匹配能力。

chrome.events 参考

类型

Rule

对用于处理事件的一条声明式规则的描述。

Rule 的属性

id ( optional string )

用于引用这一条规则的可选标志符。

tags ( optional array of string )

标签可以用来注解规则，并针对一系列规则进行操作。

conditions ( array of any )

可以触发指定操作的条件列表。

actions ( array of any )

任何一个条件满足时触发的操作列表。

priority ( optional integer )

该规则的优先级（可选），默认为 100。

Event

允许添加、删除 Chrome 浏览器事件监听器的对象。

Event 的方法

addListener

Event.addListener(function callback)

为事件注册事件监听器的回调函数。

参数

callback ( function )

事件发生时调用，该函数的参数取决于事件类型。

callback 参数应该指定一个如下形式的函数： 

function() {...};

removeListener

Event.removeListener(function callback)

为事件取消注册事件监听器的回调函数。

参数

callback ( function )

要取消注册的监听器。

callback 参数应该指定一个如下形式的函数： 

function() {...};

hasListener

boolean Event.hasListener(function callback)

参数

callback ( function )

要测试注册状态的监听器。

callback 参数应该指定一个如下形式的函数： 

function() {...};

hasListeners

boolean Event.hasListeners()

addRules

Event.addRules(array of Rule rules, function callback)

注册规则来处理事件。

参数

rules ( array of Rule )

要注册的规则，它们不会替换之前注册的规则。

callback ( optional function )

规则注册后调用。

如果您指定了 callback 参数，它应该指定一个如下形式的函数： 

function(array of Rule rules) {...};

rules ( array of Rule )

已注册的规则，可选参数将用默认值填充。

getRules

Event.getRules(array of string ruleIdentifiers, function callback)

返回当前注册的规则。

参数

ruleIdentifiers ( optional array of string )

如果传递了数组，只返回该数组中包含的标志符所对应的规则。

callback ( function )

调用时传递已注册的规则。

callback 参数应该指定一个如下形式的函数： 

function(array of Rule rules) {...};

rules ( array of Rule )

已注册的规则，可选参数将用默认值填充。

removeRules

Event.removeRules(array of string ruleIdentifiers, function callback)

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

参数

ruleIdentifiers ( optional array of string )

如果传递了数组，只移除该数组中包含的标志符所对应的规则。

callback ( optional function )

规则移除后调用。

如果您指定了 callback 参数，它应该指定一个如下形式的函数： 

function() {...};

UrlFilter

通过多种条件过滤 URL，参见事件过滤。所有条件都区分大小写。

UrlFilter 的属性

hostContains ( optional string )

如果 URL 中的主机名包含指定字符串则匹配。要测试主机名是否包含前缀 'foo'，请使用 hostContains: '.foo'，将匹配 'www.foobar.com' 和 'foo.com'，因为主机名前面会添加隐式的点。类似地，hostContains 可以用于匹配某一部分的后缀（'foo.'），或者精确匹配某一部分（'.foo.'）。最后一部分的后缀匹配和精确匹配需要单独用 hostSuffix 实现，因为主机名末尾不会添加隐式的点。

hostEquals ( optional string )

如果 URL 中的主机名与指定字符串相等则匹配。

hostPrefix ( optional string )

如果 URL 中的主机名以指定字符串开始则匹配。

hostSuffix ( optional string )

如果 URL 中的主机名以指定字符串结尾则匹配。

pathContains ( optional string )

如果 URL 中的路径部分包含指定字符串则匹配。

pathEquals ( optional string )

如果 URL 中的路径部分与指定字符串相等则匹配。

pathPrefix ( optional string )

如果 URL 中的路径部分以指定字符串开始则匹配。

pathSuffix ( optional string )

如果 URL 中的路径部分以指定字符串结尾则匹配。

queryContains ( optional string )

如果 URL 中的查询部分包含指定字符串则匹配。

queryEquals ( optional string )

如果 URL 中的查询部分与指定字符串相等则匹配。

queryPrefix ( optional string )

如果 URL 中的查询部分以指定字符串开始则匹配。

querySuffix ( optional string )

如果 URL 中的查询部分以指定字符串结尾则匹配。

urlContains ( optional string )

如果 URL（不包括片段标识符）包含指定字符串则匹配。端口号如果匹配默认端口号则将从 URL 中去除。

urlEquals ( optional string )

如果 URL（没有片段标识符）与指定字符串相等则匹配。端口号如果匹配默认端口号则将从 URL 中去除。

urlMatches ( optional string )

如果 URL（不包括片段标识符）匹配指定正则表达式则匹配。端口号如果匹配默认端口号则将从 URL 中去除。正则表达式使用 RE2 语法。

originAndPathMatches ( optional string )

如果不包含查询部分和片段标识符的 URL 匹配指定的正则表达式则匹配。如果端口号匹配默认端口号，则会从 URL 中去除。正则表达式使用 RE2 语法。

urlPrefix ( optional string )

如果 URL（不包括片段标识符）以指定字符串开始则匹配。端口号如果匹配默认端口号则将从 URL 中去除。

urlSuffix ( optional string )

如果 URL（不包括片段标识符）以指定字符串结尾则匹配。端口号如果匹配默认端口号则将从 URL 中去除。

schemes ( optional array of string )

如果 URL 的协议与数组中指定的任意一种协议相同则匹配。

ports ( optional array of integer or array of integer )

如果 URL 的端口包含在指定的端口列表中则匹配。例如 [80, 443, [1000, 1200]] 匹配端口为 80、443 或者在 1000—2000 范围内的所有请求。