chrome.events

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) =& gt;{...}

    • callback

      H

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

  • addRules

    void

    注册用于处理事件的规则。

    addRules 函数如下所示： 

    (rules: Rule<anyany>[], callback?: function) =& gt;{...}

    • 规则

      规则<anyany>[]

      要注册的规则。这些规则不会取代之前注册的规则。

    • callback

      函数 可选

      callback 参数如下所示： 

      (rules: Rule<anyany>[]) =& gt;void

      • 规则

        规则<anyany>[]

        已注册的规则，可选参数已填充值。

  • getRules

    void

    返回当前已注册的规则。

    getRules 函数如下所示： 

    (ruleIdentifiers?: string[], callback: function) =& gt;{...}

    • ruleIdentifiers

      string[] 可选

      如果传递的是数组，则仅返回标识符包含在此数组中的规则。

    • callback

      函数

      callback 参数如下所示： 

      (rules: Rule<anyany>[]) =& gt;void

      • 规则

        规则<anyany>[]

        已注册的规则，可选参数已填充值。

  • hasListener

    void

    hasListener 函数如下所示： 

    (callback: H) =& gt;{...}

    • callback

      H

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

    • 返回

      布尔值

      如果 callback 已注册到相应事件，则为 true。

  • hasListeners

    void

    hasListeners 函数如下所示： 

    () =& gt;{...}

    • 返回

      布尔值

      如果已为相应事件注册任何事件监听器，则为 True。

  • removeListener

    void

    从事件中取消注册事件监听器 callback。

    removeListener 函数如下所示： 

    (callback: H) =& gt;{...}

    • callback

      H

      要取消注册的监听器。

  • removeRules

    void

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

    removeRules 函数如下所示： 

    (ruleIdentifiers?: string[], callback?: function) =& gt;{...}

    • ruleIdentifiers

      string[] 可选

      如果传递的是数组，则只会取消注册标识符包含在此数组中的规则。

    • callback

      函数 可选

      callback 参数如下所示： 

      () =& gt;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[] 可选

    如果网址的方案与数组中指定的任何方案相同，则匹配。

  • urlContains

    字符串 可选

    如果网址（不含 fragment 标识符）包含指定字符串，则匹配。如果端口号与默认端口号一致，则会从网址中移除端口号。

  • urlEquals

    字符串 可选

    如果网址（不含片段标识符）等于指定字符串，则匹配。如果端口号与默认端口号一致，则会从网址中移除端口号。

  • urlMatches

    字符串 可选

    如果网址（不含片段标识符）与指定的正则表达式匹配，则匹配。如果端口号与默认端口号一致，则会从网址中移除端口号。正则表达式使用 RE2 语法。

  • urlPrefix

    字符串 可选

    如果网址（不含片段标识符）以指定字符串开头，则匹配。如果端口号与默认端口号一致，则会从网址中移除端口号。

  • urlSuffix

    字符串 可选

    如果网址（不含片段标识符）以指定字符串结尾，则匹配。如果端口号与默认端口号一致，则会从网址中移除端口号。