refresh date: 2026-09-25 robots: noindex
说明
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 引擎中进行评估，这可以减少往返延迟时间并实现极高的效率。
例如，Declarative Web Request API 和 Declarative 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 */ ]
};
事件对象
事件对象可能支持规则。这些事件对象在事件发生时不会调用回调函数，而是测试是否有任何已注册规则至少有一个满足的条件，并执行与此规则关联的操作。支持声明式 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]);
prefer:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
在 events.UrlFilter 中，优先使用子字符串匹配，而不是正则表达式。 基于子字符串的匹配速度非常快。
来替代：
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" } });
prefer:
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:
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
要测试其注册状态的监听器。
-
返回
布尔值
如果 callback 已注册到事件，则为 true。
-
-
hasListeners
void
hasListeners函数如下所示：() => {...}-
返回
布尔值
如果任何事件监听器已注册到该事件，则为 true。
-
-
removeListener
void
从事件中取消注册事件监听器回调。
removeListener函数如下所示：(callback: H) => {...}
-
callback
H
应取消注册的监听器。
-
-
removeRules
void
取消注册当前已注册的规则。
removeRules函数如下所示：(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] 可选
如果传递了数组，则只有标识符包含在此数组中的规则会被取消注册。
-
callback
函数可选
callback参数如下所示：() => void
-
Rule
用于处理事件的声明式规则的说明。
属性
-
操作
any[]
如果满足其中一个条件，则会触发的操作列表。
-
conditions
any[]
可触发操作的条件列表。
-
id
字符串 可选
可选标识符，用于引用此规则。
-
优先级
number 可选
此规则的可选优先级。默认值为 100。
-
标签
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
字符串 可选
如果网址的查询片段以指定字符串结尾，则匹配。
-
架构
string[] 可选
如果网址的 scheme 与数组中指定的任何 scheme 相同，则匹配。
-
urlContains
字符串 可选
如果网址（不含片段标识符）包含指定字符串，则匹配。如果端口号与默认端口号一致，则会从网址中移除。
-
urlEquals
字符串 可选
如果网址（不含片段标识符）与指定字符串相同，则匹配。如果端口号与默认端口号一致，则会从网址中移除。
-
urlMatches
字符串 可选
如果网址（不含片段标识符）与指定的正则表达式匹配，则匹配。如果端口号与默认端口号一致，则会从网址中移除。正则表达式使用 RE2 语法。
-
urlPrefix
字符串 可选
如果网址（不含片段标识符）以指定字符串开头，则匹配。如果端口号与默认端口号一致，则会从网址中移除。
-
urlSuffix
字符串 可选
如果网址（不含片段标识符）以指定字符串结尾，则匹配。如果端口号与默认端口号一致，则会从网址中移除。