browser.events

说明

chrome.events 命名空间包含 API 在调度事件时使用的常见类型，用于在发生值得注意的事情时通知您。

概念和使用

Event 是一种对象，可让您在发生值得注意的事情时收到通知。以下示例展示了如何使用 browser.alarms.onAlarm 事件在每次闹钟时间到期时收到通知：

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

如示例所示，您可以使用 addListener() 注册通知。addListener() 的实参始终是您定义的用于处理事件的函数，但该函数的形参取决于您要处理的事件。查看 alarms.onAlarm 的文档，您会发现该函数只有一个参数：一个 alarms.Alarm 对象，其中包含有关已消逝闹钟的详细信息。

使用事件的 API 示例：alarms、i18n、identity、runtime。大多数 Chrome API 都是如此。

声明式事件处理脚本

声明性事件处理程序提供了一种定义规则的方法，该规则由声明性条件和操作组成。条件是在浏览器中而非 JavaScript 引擎中进行评估的，这可减少往返延迟时间，从而实现极高的效率。

声明式事件处理程序用于声明式 Content API 等。本页介绍了所有声明性事件处理程序的底层概念。

规则

最简单的规则包含一个或多个条件以及一个或多个操作：

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

如果满足任何条件，系统就会执行所有操作。

除了条件和操作，您还可以为每条规则提供一个标识符（用于简化取消注册之前注册的规则）和一个优先级（用于定义规则之间的优先顺序）。只有当规则相互冲突或需要按特定顺序执行时，才会考虑优先级。系统会按规则优先级的降序执行操作。

const 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() 函数。它将规则实例数组作为第一个参数，并将在完成时调用的回调函数作为第二个参数。

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

如果规则插入成功，details 参数将包含一个已插入规则的数组，该数组的顺序与传递的 rule_list 中的顺序相同，其中可选参数 id 和 priority 已填充生成的值。如果任何规则无效（例如，因为其中包含无效的条件或操作），则不会添加任何规则，并且在调用回调函数时会设置 runtime.lastError 变量。rule_list 中的每条规则都必须包含一个唯一的标识符，该标识符不得已被其他规则使用，也不得为空。

移除规则

如需移除规则，请调用 removeRules() 函数。它接受一个可选的规则标识符数组作为第一个参数，并接受一个回调函数作为第二个参数。

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

如果 rule_ids 是标识符数组，则会移除具有数组中所列标识符的所有规则。如果 rule_ids 列出了一个未知标识符，系统会以静默方式忽略该标识符。如果 rule_ids 为 undefined，则移除相应扩展程序的所有已注册规则。移除规则时会调用 callback() 函数。

检索规则

如需检索已注册规则的列表，请调用 getRules() 函数。它接受一个可选的规则标识符数组（与 removeRules() 具有相同的语义）和一个回调函数。

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

传递给 callback() 函数的 details 参数是指包含已填充的可选参数的规则数组。

性能

如需实现最佳性能，您应牢记以下准则。

批量注册和取消注册规则。每次注册或取消注册后，Chrome 都需要更新内部数据结构。此更新操作的开销很大。

而不是
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
交通工具偏好
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

在 events.UrlFilter 中，首选子字符串匹配而非正则表达式。 基于子字符串的匹配速度非常快。

而不是
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
交通工具偏好
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

如果有多条规则共享相同的操作，请将这些规则合并为一条。只要满足一个条件，规则就会触发其操作。这样可以加快匹配速度，并减少重复操作集的内存消耗。

而不是
const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
交通工具偏好
const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

过滤后的事件

过滤后的事件是一种机制，可让监听器指定他们感兴趣的事件子集。对于未通过过滤器的事件，使用过滤器的监听器不会被调用，这使得监听代码更具声明性且更高效。无需唤醒 service worker 来处理它不关心的事件。

过滤后的事件旨在实现从手动过滤代码的过渡。

而不是
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
交通工具偏好
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {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) => {...}

    • 规则

      规则<anyany>[]

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

    • callback

      函数 可选

      callback 参数的格式如下： 

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

      • 规则

        规则<anyany>[]

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

  • getRules

    void

    返回当前已注册的规则。

    getRules 函数如下所示： 

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      string[] 可选

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

    • callback

      函数

      callback 参数的格式如下： 

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

      • 规则

        规则<anyany>[]

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

  • 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

用于处理事件的声明性规则的说明。

属性

  • 操作

    任何 []

    如果满足其中一个条件，则触发的操作列表。

  • conditions

    任何 []

    可触发操作的条件列表。

  • 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

    字符串 可选

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

  • urlEquals

    字符串 可选

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

  • urlMatches

    字符串 可选

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

  • urlPrefix

    字符串 可选

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

  • urlSuffix

    字符串 可选

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