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 对象。

使用事件的 API 有很多，例如：alarms、app.runtime、app.window、i18n、identity、runtime，大部分 Chrome API 都是如此。

摘要

类型
Rule
Event
UrlFilter

类型

Rule

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

属性
string	（可选） id	用于引用这一条规则的可选标志符。
array of string	（可选） tags	从 Chrome 28 开始支持。标签可以用来注解规则，并针对一系列规则进行操作。
array of any	conditions	可以触发指定操作的条件列表。
array of any	actions	任何一个条件满足时触发的操作列表。
integer	（可选） priority	该规则的优先级（可选），默认为 100。

Event

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

方法

addListener


                    Event.addListener(function callback)

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

参数

function

callback

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

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

function() {...};

removeListener


                    Event.removeListener(function callback)

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

参数

function

callback

要取消注册的监听器。

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

function() {...};

hasListener


                    boolean
                    Event.hasListener(function callback)

参数

function

callback

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

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

function() {...};

hasListeners


                    boolean
                    Event.hasListeners()

addRules


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

注册规则来处理事件。

参数

array of Rule

rules

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

function

（可选）
callback

规则注册后调用。

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

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

array of Rule

rules

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

getRules


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

返回当前注册的规则。

参数

array of string

（可选）
ruleIdentifiers

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

function

callback

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

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

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

array of Rule

rules

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

removeRules


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

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

参数

array of string

（可选）
ruleIdentifiers

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

function

（可选）
callback

规则移除后调用。

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

function() {...};

UrlFilter

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

属性
string	（可选） hostContains	如果 URL 中的主机名包含指定字符串则匹配。要测试主机名是否包含前缀 'foo'，请使用 hostContains: '.foo'，将匹配 'www.foobar.com' 和 'foo.com'，因为主机名前面会添加隐式的点。类似地，hostContains 可以用于匹配某一部分的后缀（'foo.'），或者精确匹配某一部分（'.foo.'）。最后一部分的后缀匹配和精确匹配需要单独用 hostSuffix 实现，因为主机名末尾不会添加隐式的点。
string	（可选） hostEquals	如果 URL 中的主机名与指定字符串相等则匹配。
string	（可选） hostPrefix	如果 URL 中的主机名以指定字符串开始则匹配。
string	（可选） hostSuffix	如果 URL 中的主机名以指定字符串结尾则匹配。
string	（可选） pathContains	如果 URL 中的路径部分包含指定字符串则匹配。
string	（可选） pathEquals	如果 URL 中的路径部分与指定字符串相等则匹配。
string	（可选） pathPrefix	如果 URL 中的路径部分以指定字符串开始则匹配。
string	（可选） pathSuffix	如果 URL 中的路径部分以指定字符串结尾则匹配。
string	（可选） queryContains	如果 URL 中的查询部分包含指定字符串则匹配。
string	（可选） queryEquals	如果 URL 中的查询部分与指定字符串相等则匹配。
string	（可选） queryPrefix	如果 URL 中的查询部分以指定字符串开始则匹配。
string	（可选） querySuffix	如果 URL 中的查询部分以指定字符串结尾则匹配。
string	（可选） urlContains	如果 URL（不包括片段标识符）包含指定字符串则匹配。端口号如果匹配默认端口号则将从 URL 中去除。
string	（可选） urlEquals	如果 URL（没有片段标识符）与指定字符串相等则匹配。端口号如果匹配默认端口号则将从 URL 中去除。
string	（可选） urlMatches	从 Chrome 23 开始支持。如果 URL（不包括片段标识符）匹配指定正则表达式则匹配。端口号如果匹配默认端口号则将从 URL 中去除。正则表达式使用 RE2 语法。
string	（可选） originAndPathMatches	从 Chrome 28 开始支持。如果不包含查询部分和片段标识符的 URL 匹配指定的正则表达式则匹配。如果端口号匹配默认端口号，则会从 URL 中去除。正则表达式使用 RE2 语法。
string	（可选） urlPrefix	如果 URL（不包括片段标识符）以指定字符串开始则匹配。端口号如果匹配默认端口号则将从 URL 中去除。
string	（可选） urlSuffix	如果 URL（不包括片段标识符）以指定字符串结尾则匹配。端口号如果匹配默认端口号则将从 URL 中去除。
array of string	（可选） schemes	如果 URL 的协议与数组中指定的任意一种协议相同则匹配。
array of integer or array of integer	（可选） ports	如果 URL 的端口包含在指定的端口列表中则匹配。例如 [80, 443, [1000, 1200]] 匹配端口为 80、443 或者在 1000—2000 范围内的所有请求。