chrome.events

Description

chrome.events 命名空间包含 API 调度事件使用的常用类型，以便在发生有趣的事情时通知您。

Event 是一个对象，它允许您在发生有趣的事情时收到通知。下面是使用 chrome.alarms.onAlarm 事件在闹钟结束时收到通知的示例：

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
如示例所示，您使用 addListener() 注册通知。 addListener() 的参数始终是您定义的用于处理事件的函数，但该函数的参数取决于您正在处理的事件。查看 alarms.onAlarm 的文档，您可以看到该函数只有一个参数：一个 alarms.Alarm 对象，其中包含有关已过警报的详细信息。
使用事件的示例 API：警报(alarms)、i18n、身份(identity)、运行时(runtime)。大多数 chrome API 都可以。
# Declarative Event Handlers(声明性事件处理程序)
声明性事件处理程序提供了一种定义由声明性条件和操作组成的规则的方法。条件是在浏览器而不是 JavaScript 引擎中评估的，这减少了往返延迟并允许非常高的效率。
例如，声明性事件处理程序用于声明性 Web 请求 API（Declarative Web Request API） 和声明性内容 API（Declarative Content API）。本页描述了所有声明性事件处理程序的基本概念。
# Rules
最简单的可能规则由一个或多个条件和一个或多个操作组成：
var rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
如果满足任何条件，则执行所有操作。
除了条件和操作之外，您还可以给每个规则一个标识符，这简化了取消注册以前注册的规则的过程，以及定义规则之间优先级的优先级。仅当规则相互冲突或需要按特定顺序执行时才考虑优先级。操作按其规则的优先级降序执行。
var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
# Event objects(事件对象)
事件对象可能支持规则。这些事件对象在事件发生时不会调用回调函数，而是测试任何已注册的规则是否至少具有一个满足的条件并执行与此规则关联的操作。支持声明式 API 的事件对象具有三个相关方法：events.Event.addRules、events.Event.removeRules 和 events.Event.getRules。
# Adding rules(添加规则)
要添加规则，请调用事件对象的 addRules() 函数。它接受一个规则实例数组作为它的第一个参数和一个在完成时调用的回调函数。
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
如果规则插入成功，则 details 参数包含一组插入的规则，它们的出现顺序与传递的 rule_list 中的顺序相同，其中可选参数 id 和 priority 用生成的值填充。如果任何规则无效，例如，因为它包含无效的条件或操作，则不会添加任何规则，并在调用回调函数时设置 runtime.lastError 变量。rule_list 中的每个规则都必须包含一个当前未被其他规则使用的唯一标识符或一个空标识符。
注意：规则在浏览会话中是持久的。因此，您应该在扩展安装期间使用 runtime.onInstalled 事件安装规则。请注意，此事件也会在扩展更新时触发。因此，您应该先清除以前安装的规则，然后再注册新规则。
# Removing rules(删除规则)
要删除规则，请调用 removeRules() 函数。它接受一个可选的规则标识符数组作为它的第一个参数和一个回调函数作为它的第二个参数。
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
如果 rule_ids 是一个标识符数组，则删除所有具有在该数组中列出的标识符的规则。如果 rule_ids 列出了一个未知的标识符，则该标识符将被静默忽略。如果 rule_ids 未定义，则删除此扩展的所有注册规则。删除规则时调用 callback() 函数。
# Retrieving rules(检索规则)
要检索当前注册的规则列表，请调用 getRules() 函数。它接受一个可选的规则标识符数组，其语义与 removeRules 和回调函数相同。
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});
传递给 callback() 函数的 details 参数是指包含填充的可选参数的规则数组。
# Performance(表现)
为了获得最佳性能，您应该牢记以下准则：
批量注册和注销规则。每次注册或注销后，Chrome 都需要更新内部数据结构。此更新是一项昂贵的操作。 代替
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
更喜欢写(prefer to write)
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
在 events.UrlFilter 中使用正则表达式优先匹配子字符串匹配。基于子串的匹配非常快。 代替
var match = new chrome.declarativeWebRequest.RequestMatcher({
    url: {urlMatches: "example.com/[^?]*foo" } });
更喜欢写(prefer to write)
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]);
更喜欢写(prefer to write)
var rule = { conditions: [condition1, condition2],
              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule]);
# Filtered events(过滤事件)
过滤事件是一种机制，允许侦听器指定他们感兴趣的事件子集。不会为未通过过滤器的事件调用使用过滤器的侦听器，这使侦听代码更具声明性和效率 - 无需唤醒事件event page页面页面来处理它不关心的事件关于。
过滤事件旨在允许从这样的手动过滤代码转换：
chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
into this:
chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});
事件支持对该事件有意义的特定过滤器。事件支持的过滤器列表将在“过滤器(filters)”部分的该事件的文档中列出。
匹配 URL 时（如上例所示），事件过滤器支持与 events.UrlFilter 相同的 URL 匹配功能，但方案(scheme)和端口(port)匹配除外。
Summary
Types
Event
Rule
UrlFilter
Types
Event 
一个允许为 Chrome 事件添加和删除侦听器的对象。
PROPERTIES
addListener
function
将事件侦听器回调注册到事件。
The addListener function looks like:
(callback: H) => {...}
callback
H
事件发生时调用。此函数的参数取决于事件的类型。
addRules
function
注册规则来处理事件。
The addRules function looks like:
(rules: Rule[], callback?: function) => {...}
rules
Rule[]
注册规则。这些不会取代以前注册的规则。
callback
function optional
The callback parameter looks like:
(rules: Rule[]) => void
rules
Rule[]
已注册的规则，可选参数填充有值。
getRules
function
返回当前注册的规则。
The getRules function looks like:
(ruleIdentifiers?: string[], callback: function) => {...}
ruleIdentifiers
string[] optional
如果传递了一个数组，则只返回包含在该数组中的标识符的规则。
callback
function
The callback parameter looks like:
(rules: Rule[]) => void
rules
Rule[]
已注册的规则，可选参数填充有值。
hasListener
function
The hasListener function looks like:
(callback: H) => {...}
callback
H
需要测试注册状态的监听器。
returns
boolean
如果回调已注册到事件，则为真。
hasListeners
function
The hasListeners function looks like:
() => {...}
returns
boolean
如果有任何事件侦听器注册到该事件，则为 True。
removeListener
function
从事件中注销事件侦听器回调。
The removeListener function looks like:
(callback: H) => {...}
callback
H
应取消注册的侦听器。
removeRules
function
取消注册当前注册的规则。
The removeRules function looks like:
(ruleIdentifiers?: string[], callback?: function) => {...}
ruleIdentifiers
string[] optional
如果传递了一个数组，则只有具有包含在该数组中的标识符的规则才会被取消注册。
callback
function optional
The callback parameter looks like:
() => void
Rule 
处理事件的声明性规则的描述。
PROPERTIES
actions
any[]
满足其中一个条件时触发的操作列表。
conditions
any[]
可以触发操作的条件列表。
id
string optional
允许引用此规则的可选标识符
priority
number optional
此规则的可选优先级。默认为 100。
tags
string[] optional
标签可用于注释规则并对规则集执行操作。
UrlFilter 
根据各种条件过滤 URL。请参阅事件过滤event filtering。所有条件都区分大小写。
PROPERTIES
hostContains
string optional
如果 URL 的主机名包含指定的字符串，则匹配。要测试主机名组件是否具有前缀 'foo'，请使用 hostContains: '.foo'。这匹配 'www.foobar.com' 和 'foo.com'，因为在主机名的开头添加了一个隐式点。类似地，hostContains 可用于匹配组件后缀 ('foo.') 和精确匹配组件 ('.foo.')。最后一个组件的后缀匹配和精确匹配需要使用 hostSuffix 单独完成，因为在主机名的末尾没有添加隐式点。
hostEquals
string optional
如果 URL 的主机名等于指定的字符串，则匹配。
hostPrefix
string optional
如果 URL 的主机名以指定字符串开头，则匹配。
hostSuffix
string optional
如果 URL 的主机名以指定字符串结尾，则匹配。
originAndPathMatches
string optional
如果没有查询段和片段标识符的 URL 匹配指定的正则表达式，则匹配。如果端口号与默认端口号匹配，则会从 URL 中删除它们。正则表达式使用 RE2 syntax。
pathContains
string optional
如果 URL 的路径段包含指定的字符串，则匹配。
pathEquals
string optional
如果 URL 的路径段等于指定的字符串，则匹配。
pathPrefix
string optional
如果 URL 的路径段以指定字符串开头，则匹配。
pathSuffix
string optional
如果 URL 的路径段以指定字符串结尾，则匹配。
ports
(number | number[])[] optional
如果 URL 的端口包含在任何指定的端口列表中，则匹配。例如 [80, 443, [1000, 1200]] 匹配端口 80、443 和 1000-1200 范围内的所有请求。
queryContains
string optional
如果 URL 的查询段包含指定的字符串，则匹配。
queryEquals
string optional
如果 URL 的查询段等于指定的字符串，则匹配。
queryPrefix
string optional
如果 URL 的查询段以指定字符串开头，则匹配。
querySuffix
string optional
如果 URL 的查询段以指定字符串结尾，则匹配。
schemes
string[] optional
如果 URL 的方案等于数组中指定的任何方案，则匹配。
urlContains
string optional
如果 URL（没有片段标识符）包含指定的字符串，则匹配。如果端口号与默认端口号匹配，则会从 URL 中删除它们。
urlEquals
string optional
如果 URL（没有片段标识符）等于指定的字符串，则匹配。如果端口号与默认端口号匹配，则会从 URL 中删除它们。
urlMatches
string optional
如果 URL（不带片段标识符）与指定的正则表达式匹配，则匹配。如果端口号与默认端口号匹配，则会从 URL 中删除它们。正则表达式使用 RE2 syntax。
urlPrefix
string optional
如果 URL（不带片段标识符）以指定字符串开头，则匹配。如果端口号与默认端口号匹配，则会从 URL 中删除它们。
urlSuffix
string optional
如果 URL（不带片段标识符）以指定字符串结尾，则匹配。如果端口号与默认端口号匹配，则会从 URL 中删除它们。
By.一粒技术服务.