说明
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 都可以做到这一点。
声明式事件处理脚本
声明性事件处理脚本提供了一种方法来定义由声明性条件和操作组成的规则。条件是在浏览器(而不是 JavaScript 引擎)中评估的,这可以减少往返延迟时间并实现非常高的效率。
例如,声明式 Web Request API 和声明式 Content API 中使用了声明式事件处理脚本。本页面介绍了所有声明式事件处理脚本的基本概念。
规则
可能的规则是最简单的方式,由一个或多个条件以及一项或多项操作构成:
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 对象可能支持规则。当事件发生时,这些事件对象不会调用回调函数,但会测试任何注册的规则是否至少有一个已满足的条件,并执行与此规则关联的操作。支持声明式 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
中的每条规则都必须包含一个当前未被其他规则使用的唯一标识符,或者包含一个空标识符。
正在移除规则
如需移除规则,请调用 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]);
过滤出的事件
过滤事件是一种机制,可让监听器指定其感兴趣的部分事件。系统不会为未通过过滤器的事件调用使用过滤器的监听器,这使得监听代码的声明性更强、更高效。无需唤醒 Service Worker 来处理它不需要的事件。
过滤的事件旨在让手动过滤代码实现转换,如下所示:
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'}]});
事件支持对该事件有意义的特定过滤条件。事件支持的过滤器列表将列在该事件文档的“过滤器”部分。
在匹配网址时(如上例所示),事件过滤器支持通过 events.UrlFilter
表示的相同网址匹配功能,但架构和端口匹配除外。
类型
Event
允许添加和移除 Chrome 事件监听器的对象。
属性
-
addListener
void
向事件注册事件监听器回调。
addListener
函数如下所示:(callback: H) => {...}
-
callback
H
在事件发生时调用。此函数的参数取决于事件类型。
-
-
addRules
void
注册用于处理事件的规则。
addRules
函数如下所示:(rules: Rule<anyany>[], callback?: function) => {...}
-
getRules
void
返回当前注册的规则。
getRules
函数如下所示:(ruleIdentifiers?: string[], callback: function) => {...}
-
hasListener
void
hasListener
函数如下所示:(callback: H) => {...}
-
callback
H
要测试其注册状态的监听器。
-
返回
boolean
如果 callback 已注册到事件,则为 true。
-
-
hasListeners
void
hasListeners
函数如下所示:() => {...}
-
返回
boolean
如果事件监听器已注册到事件,则为 true。
-
-
removeListener
void
从事件中取消注册事件监听器回调。
removeListener
函数如下所示:(callback: H) => {...}
-
callback
H
应取消注册的监听器。
-
-
removeRules
void
取消注册当前注册的规则。
removeRules
函数如下所示:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] 可选
如果传递了一个数组,则系统只会取消注册此数组中包含标识符的规则。
-
callback
函数(可选)
callback
参数如下所示:() => void
-
Rule
有关处理事件的声明性规则的说明。
属性
-
操作
任意 []
在满足其中一个条件时触发的操作的列表。
-
conditions
任意 []
可以触发操作的条件列表。
-
id
字符串(可选)
允许引用此规则的可选标识符。
-
优先级
数字可选
此规则的可选优先级。默认值为 100。
-
tags
string[] 可选
标记可用于为规则添加注释并对规则集执行操作。
UrlFilter
根据各种条件过滤网址。请参阅事件过滤。所有条件都区分大小写。
属性
-
cidrBlocks
string[] 可选
Chrome 123 及更高版本如果网址的主机部分是 IP 地址,并且包含在数组中指定的任何 CIDR 块中,则匹配。
-
hostContains
字符串(可选)
如果网址的主机名包含指定字符串,则匹配。如需测试主机名组成部分是否具有前缀“foo”,请使用 hostContains: '.foo'。这与“www.foobar.com”和“foo.com”匹配,因为主机名开头添加了一个隐式点。同样,hostContains 可用于匹配组件后缀(“foo.”)和完全匹配组件(“.foo.”)。最后一个组成部分的后缀和完全匹配需要使用 hostSuffix 单独完成,因为主机名末尾没有添加隐式点。
-
hostEquals
字符串(可选)
如果网址的主机名等于指定字符串,则匹配。
-
hostPrefix
字符串(可选)
如果网址的主机名以指定字符串开头,则匹配。
-
hostSuffix
字符串(可选)
如果网址的主机名以指定字符串结尾,匹配。
-
originAndPathMatches
字符串(可选)
如果不含查询细分和片段标识符的网址与指定的正则表达式匹配,则匹配。如果端口号与默认端口号匹配,则系统会从网址中去掉端口号。正则表达式使用 RE2 语法。
-
pathContains
字符串(可选)
如果网址的路径段包含指定字符串,则匹配。
-
pathEquals
字符串(可选)
如果网址的路径段等于指定字符串,则匹配。
-
pathPrefix
字符串(可选)
如果网址的路径段以指定字符串开头,则匹配。
-
pathSuffix
字符串(可选)
如果网址的路径段以指定字符串结尾,则匹配。
-
ports
(number | number[])[] 选填
如果网址的端口包含在任意指定的端口列表中,则匹配。例如,
[80, 443, [1000, 1200]]
会匹配端口 80、443 和 1000-1200 范围内的所有请求。 -
queryContains
字符串(可选)
如果网址的查询段包含指定字符串,则匹配。
-
queryEquals
字符串(可选)
如果网址的查询段等于指定字符串,则匹配。
-
queryPrefix
字符串(可选)
如果网址的查询段以指定字符串开头,则匹配。
-
querySuffix
字符串(可选)
如果网址的查询段以指定字符串结尾,则匹配。
-
schemes
string[] 可选
如果网址的架构等于数组中指定的任一架构,则匹配。
-
urlContains
字符串(可选)
如果网址(不含片段标识符)包含指定字符串,则匹配。如果端口号与默认端口号匹配,则系统会从网址中去掉端口号。
-
urlEquals
字符串(可选)
如果网址(无片段标识符)等于指定字符串,则匹配。如果端口号与默认端口号匹配,则系统会从网址中去掉端口号。
-
urlMatches
字符串(可选)
如果网址(不含片段标识符)与指定的正则表达式匹配,则匹配。如果端口号与默认端口号匹配,则系统会从网址中去掉端口号。正则表达式使用 RE2 语法。
-
urlPrefix
字符串(可选)
如果网址(不含片段标识符)以指定字符串开头,则匹配。如果端口号与默认端口号匹配,则系统会从网址中去掉端口号。
-
urlSuffix
字符串(可选)
如果网址(无片段标识符)以指定字符串结尾,则匹配。如果端口号与默认端口号匹配,则系统会从网址中去掉端口号。