chrome.declarativeWebRequest

说明

注意：此 API 已废弃。请改为查看 declarativeNetRequest API。使用 chrome.declarativeWebRequest API 拦截、屏蔽或修改运行中的请求。其速度明显快于 chrome.webRequest API，因为您可以注册在浏览器中（而非 JavaScript 引擎）中评估的规则，从而减少往返延迟时间并提高效率。

权限

declarativeWebRequest

您必须在扩展程序清单中声明“declarativeWebRequest”权限以及主机权限，才能使用此 API。

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

可用性

Beta 版 ≤ MV2

清单

请注意，某些类型的非敏感操作不需要主机权限：

• CancelRequest
• IgnoreRules
• RedirectToEmptyDocument
• RedirectToTransparentImage

对于您要在其上触发消息的网络请求，SendMessageToExtension() 操作需要任何主机的主机权限。

所有其他操作都需要所有网址的主机权限。

例如，如果 "https://*.google.com/*" 是扩展程序的唯一主机权限，则此类扩展程序可能会设置如下规则：

• 取消对 https://www.google.com 或 https://anything.else.com 的请求。
• 在导航到 https://www.google.com 时发送消息，但不在 https://something.else.com 时发送消息。

此扩展程序无法设置将 https://www.google.com 重定向至 https://mail.google.com 的规则。

规则

声明式 Web Request API 遵循声明式 API 的概念。您可以将规则注册到 chrome.declarativeWebRequest.onRequest 事件对象。

声明式 Web 请求 API 支持一种匹配类型，即 RequestMatcher。当且仅当满足列出的所有条件时，RequestMatcher 才会匹配网络请求。当用户在 Ominibox 中输入 https://www.example.com 时，以下 RequestMatcher 将与网络请求匹配：

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

根据架构，RequestMatcher 会拒绝对 https://www.example.com 的请求。此外，针对嵌入式 iframe 的所有请求都会因 resourceType 而被拒绝。

注意：所有条件和操作都是通过构造函数创建的，如上例所示。

要取消对“example.com”的所有请求，您可以按如下方式定义规则：

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

如需取消对 example.com 和 foobar.com 的所有请求，您可以添加第二个条件，因为每个条件都足以触发所有指定的操作：

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

按如下方式注册规则：

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

注意：您应始终批量（而不是单独）注册或取消注册规则，因为这些操作都会重新创建内部数据结构。这种重新创建方法在计算上成本很高，但有助于为数十万个网址实现非常快速的网址匹配算法。如需了解更多性能提示，请参阅 Events API 的“性能”部分。

条件和操作评估

声明式 Web 请求 API 遵循 Web 请求 API 的网络请求的生命周期模型。这意味着只能在 Web 请求的特定阶段测试条件，同样，操作也只能在特定阶段执行。下表列出了与条件和操作兼容的请求阶段。

可以处理条件属性的请求阶段。
使用情况属性	onBeforeRequest	onBeforeSendHeaders	onHeadersReceived	onAuthRequired
url	✓	✓	✓	✓
resourceType	✓	✓	✓	✓
contentType			✓
excludeContentType			✓
responseHeaders			✓
excludeResponseHeaders			✓
requestHeaders		✓
excludeRequestHeaders		✓
thirdPartyForCookies	✓	✓	✓	✓
可以执行操作的请求阶段。
事件	onBeforeRequest	onBeforeSendHeaders	onHeadersReceived	onAuthRequired
AddRequestCookie		✓
AddResponseCookie			✓
AddResponseHeader			✓
CancelRequest	✓	✓	✓	✓
EditRequestCookie		✓
EditResponseCookie			✓
IgnoreRules	✓	✓	✓	✓
RedirectByRegEx	✓		✓
RedirectRequest	✓		✓
RedirectToEmptyDocument	✓		✓
RedirectToTransparentImage	✓		✓
RemoveRequestCookie		✓
RemoveRequestHeader		✓
RemoveResponseCookie			✓
RemoveResponseHeader			✓
SendMessageToExtension	✓	✓	✓	✓
SetRequestHeader		✓

注意：您可以使用“stages”属性进一步限制适用的阶段。

注意：由重定向操作发起的重定向会使用重定向的原始请求方法，但有一种例外情况：如果在“onHeadersReceived”阶段启动重定向，则将使用“GET”方法发出重定向。

示例：可以将“新的 chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})”条件与“新的 chrome.declarativeWebRequest.CancelRequest()”操作结合使用，因为两者都可以在“onHeadersReceived”阶段进行评估。但是，无法将请求匹配器与“新的 chrome.declarativeWebRequest.SetRequestHeader()”结合使用，因为当内容类型终止后，无法再设置请求标头。

使用优先级来覆盖规则

规则可以与优先级相关联，如 Events API 中所述。此机制可用于表达异常。以下示例将屏蔽对名为 evil.jpg 的映像的所有请求（服务器“myserver.com”除外）。

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

请务必注意，IgnoreRules 操作不会跨请求阶段持久保存。系统会在网络请求的每个阶段评估所有规则的所有条件。如果执行了 IgnoreRules 操作，该操作仅会应用于同一阶段针对同一 Web 请求执行的其他操作。

类型

AddRequestCookie

在请求中添加 Cookie 或覆盖 Cookie（在已存在其他同名 Cookie 的情况下）。请注意，最好使用 Cookies API，因为其计算成本较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: AddRequestCookie)=> {...}

  • 参数

    AddRequestCookie

  • 返回

    AddRequestCookie

• 饼干

  RequestCookie

  要添加到请求的 Cookie。没有可以未定义的字段。

AddResponseCookie

在响应中添加一个 Cookie 或覆盖某个 Cookie（如果已存在其他同名 Cookie）。请注意，最好使用 Cookies API，因为其计算成本较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: AddResponseCookie)=> {...}

  • 参数

    AddResponseCookie

  • 返回

    AddResponseCookie

• 饼干

  ResponseCookie

  要添加到响应的 Cookie。需要指定名称和值。

AddResponseHeader

将响应标头添加到此网络请求的响应中。由于多个响应标头可能共用相同的名称，您需要先移除标头，然后再添加新的响应标头，以便替换标头。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: AddResponseHeader)=> {...}

  • 参数

    AddResponseHeader

  • 返回

    AddResponseHeader

• name

  string

  HTTP 响应标头名称。

• 值

  string

  HTTP 响应标头值。

CancelRequest

用于取消网络请求的声明性事件操作。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: CancelRequest)=> {...}

  • 参数

    CancelRequest

  • 返回

    CancelRequest

EditRequestCookie

修改请求的一个或多个 Cookie。请注意，最好使用 Cookies API，因为其计算成本较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: EditRequestCookie)=> {...}

  • 参数

    EditRequestCookie

  • 返回

    EditRequestCookie

• filter

  RequestCookie

  过滤出将要修改的 Cookie。系统会忽略所有空条目。

• 修改

  RequestCookie

  在管理过滤器的 Cookie 中，应被覆盖的属性。设置为空字符串的属性会被移除。

EditResponseCookie

修改一个或多个响应 Cookie。请注意，最好使用 Cookies API，因为其计算成本较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: EditResponseCookie)=> {...}

  • 参数

    EditResponseCookie

  • 返回

    EditResponseCookie

• filter

  FilterResponseCookie

  过滤出将要修改的 Cookie。系统会忽略所有空条目。

• 修改

  ResponseCookie

  在管理过滤器的 Cookie 中，应被覆盖的属性。设置为空字符串的属性会被移除。

FilterResponseCookie

HTTP 响应中的 Cookie 过滤器。

属性

• ageLowerBound

  数字可选

  Cookie 生命周期的包含下限（指定在当前时间之后的秒数）。只有失效日期设置为“现在 + ageLowerBound”或更晚的 Cookie 才满足此条件。会话 Cookie 不符合此过滤器的条件。Cookie 生命周期通过“max-age”或“expires”Cookie 属性计算得出。如果两个都指定，则使用“max-age”来计算 Cookie 生命周期。

• ageUpperBound

  数字可选

  Cookie 生命周期的包含上限（以当前时间过后的秒数指定）。只有失效日期在 [现在，现在 + ageUpperBound] 间隔范围内的 Cookie 才满足此条件。会话 Cookie 和失效日期为过去时间的 Cookie 不符合此过滤条件的条件。Cookie 生命周期通过“max-age”或“expires”Cookie 属性计算得出。如果两个都指定，则使用“max-age”来计算 Cookie 生命周期。

• 网域

  字符串（可选）

  网域 Cookie 属性的值。

• 到期时间

  字符串（可选）

  到期 Cookie 属性的值。

• httpOnly

  字符串（可选）

  HttpOnly Cookie 属性是否存在。

• maxAge

  数字可选

  “Max-Age”Cookie 属性的值

• name

  字符串（可选）

  Cookie 的名称。

• path

  字符串（可选）

  路径 Cookie 属性的值。

• 安全

  字符串（可选）

  安全 Cookie 属性是否存在。

• sessionCookie

  布尔值 选填

  过滤会话 Cookie。会话 Cookie 的任何“max-age”或“expires”属性中都未指定有效期。

• 值

  字符串（可选）

  Cookie 的值，可以用双引号括起来。

HeaderFilter

针对各种条件过滤请求标头。系统会同时对多个条件进行评估。

属性

• nameContains

  string|string[] optional

  如果标头名称包含所有指定字符串，则匹配。

• nameEquals

  字符串（可选）

  如果标头名称等于指定字符串，则匹配。

• namePrefix

  字符串（可选）

  如果标头名称以指定字符串开头，则匹配。

• nameSuffix

  字符串（可选）

  如果标头名称以指定字符串结尾，则匹配。

• valueContains

  string|string[] optional

  如果标头值包含所有指定字符串，则匹配。

• valueEquals

  字符串（可选）

  如果标头值等于指定字符串，则匹配。

• valuePrefix

  字符串（可选）

  如果标头值以指定字符串开头，则匹配。

• valueSuffix

  字符串（可选）

  如果标头值以指定字符串结尾，则匹配。

IgnoreRules

遮盖符合指定条件的所有规则。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: IgnoreRules)=> {...}

  • 参数

    IgnoreRules

  • 返回

    IgnoreRules

• hasTag

  字符串（可选）

  如果设置了此字段，则具有指定标记的规则会被忽略。忽略的操作不会持续存在，只会影响同一网络请求阶段的规则及其操作。请注意，规则按其优先级的降序执行。此操作会影响优先级低于当前规则的规则。系统可能不会忽略具有相同优先级的规则。

• lowerPriorityThan

  数字可选

  如果设置了此字段，系统会忽略优先级低于指定值的规则。此边界不会持久保留，而只会影响同一网络请求阶段的规则及其操作。

RedirectByRegEx

通过对网址应用正则表达式来重定向请求。正则表达式使用 RE2 语法。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RedirectByRegEx)=> {...}

  • 参数

    RedirectByRegEx

  • 返回

    RedirectByRegEx

• 来自

  string

  可能包含捕获组的匹配模式。为了更接近 JavaScript 正则表达式，引用捕获组时使用的是 Perl 语法（$1、$2...），而非 RE2 语法（\1、\2...）。

• to

  string

  目标模式。

RedirectRequest

用于重定向网络请求的声明性事件操作。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RedirectRequest)=> {...}

  • 参数

    RedirectRequest

  • 返回

    RedirectRequest

• redirectUrl

  string

  请求重定向到的目标位置。

RedirectToEmptyDocument

将网络请求重定向到空文档的声明性事件操作。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RedirectToEmptyDocument)=> {...}

  • 参数

    RedirectToEmptyDocument

  • 返回

    RedirectToEmptyDocument

RedirectToTransparentImage

将网络请求重定向到透明图片的声明性事件操作。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RedirectToTransparentImage)=> {...}

  • 参数

    RedirectToTransparentImage

  • 返回

    RedirectToTransparentImage

RemoveRequestCookie

移除一个或多个请求的 Cookie。请注意，最好使用 Cookies API，因为其计算成本较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RemoveRequestCookie)=> {...}

  • 参数

    RemoveRequestCookie

  • 返回

    RemoveRequestCookie

• filter

  RequestCookie

  过滤出将被移除的 Cookie。系统会忽略所有空条目。

RemoveRequestHeader

移除指定名称的请求标头。请勿在同一请求中使用具有相同标头名称的 SetRequestHeader 和 RemoveRequestHeader。每个请求标头名称在每个请求中仅出现一次。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RemoveRequestHeader)=> {...}

  • 参数

    RemoveRequestHeader

  • 返回

    RemoveRequestHeader

• name

  string

  HTTP 请求标头名称（不区分大小写）。

RemoveResponseCookie

删除一个或多个响应 Cookie。请注意，最好使用 Cookies API，因为其计算成本较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RemoveResponseCookie)=> {...}

  • 参数

    RemoveResponseCookie

  • 返回

    RemoveResponseCookie

• filter

  FilterResponseCookie

  过滤出将被移除的 Cookie。系统会忽略所有空条目。

RemoveResponseHeader

移除指定名称和值的所有响应标头。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RemoveResponseHeader)=> {...}

  • 参数

    RemoveResponseHeader

  • 返回

    RemoveResponseHeader

• name

  string

  HTTP 请求标头名称（不区分大小写）。

• 值

  字符串（可选）

  HTTP 请求标头值（不区分大小写）。

RequestCookie

HTTP 请求中 Cookie 的过滤器或规范。

属性

• name

  字符串（可选）

  Cookie 的名称。

• 值

  字符串（可选）

  Cookie 的值，可以用双引号括起来。

RequestMatcher

根据各种条件匹配网络事件。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: RequestMatcher)=> {...}

  • 参数

    RequestMatcher

  • 返回

    RequestMatcher

• contentType

  string[] 可选

  如果列表中包含响应的 MIME 媒体类型（来自 HTTP Content-Type 标头），则匹配。

• excludeContentType

  string[] 可选

  如果列表中不包含响应的 MIME 媒体类型（来自 HTTP Content-Type 标头），则匹配。

• excludeRequestHeaders

  HeaderFilter[] 可选

  如果没有任何 HeaderFilters 与请求标头匹配，则匹配。

• excludeResponseHeaders

  HeaderFilter[] 可选

  如果任何响应标头与任何 HeaderFilters 都不匹配，则匹配。

• firstPartyForCookiesUrl

  UrlFilter 可选

  已废弃

  从版本 82 开始忽略。

  如果针对请求的“第一方”网址满足 UrlFilter 的条件，则匹配。请求的“第一方”网址（如果存在）可以与请求的目标网址不同，用于描述为了进行第三方 Cookie 检查而被视为“第一方”的网址。

• requestHeaders

  HeaderFilter[] 可选

  如果某些请求标头与其中一个 HeaderFilters 匹配，则匹配。

• resourceType

  ResourceType[] 可选

  如果列表中包含请求的请求类型，则匹配。与任何类型都不匹配的请求将被滤除。

• responseHeaders

  HeaderFilter[] 可选

  如果某些响应标头与其中一个 HeaderFilters 匹配，则匹配。

• 阶段

  阶段[] 选填

  包含描述阶段的字符串列表。允许的值为“onBeforeRequest”“onBeforeSendHeaders”“onHeadersReceived”“onAuthRequired”。如果该属性存在，则适用阶段仅限于列出的阶段。请注意，整个条件仅适用于与所有属性都兼容的阶段。

• thirdPartyForCookies

  布尔值 选填

  已废弃

  从版本 87 开始被忽略。

  如果此政策设为 true，系统会匹配受第三方 Cookie 政策约束的请求。如果设置为 false，则匹配所有其他请求。

• 网址

  UrlFilter 可选

  如果针对请求的网址满足 UrlFilter 的条件，则匹配。

ResponseCookie

HTTP 响应中的 Cookie 规范。

属性

• 网域

  字符串（可选）

  网域 Cookie 属性的值。

• 到期时间

  字符串（可选）

  到期 Cookie 属性的值。

• httpOnly

  字符串（可选）

  HttpOnly Cookie 属性是否存在。

• maxAge

  数字可选

  “Max-Age”Cookie 属性的值

• name

  字符串（可选）

  Cookie 的名称。

• path

  字符串（可选）

  路径 Cookie 属性的值。

• 安全

  字符串（可选）

  安全 Cookie 属性是否存在。

• 值

  字符串（可选）

  Cookie 的值，可以用双引号括起来。

SendMessageToExtension

触发 declarativeWebRequest.onMessage 事件。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: SendMessageToExtension)=> {...}

  • 参数

    SendMessageToExtension

  • 返回

    SendMessageToExtension

• 信息

  string

  将在传递给事件处理脚本的字典的 message 属性中传递的值。

SetRequestHeader

将指定名称的请求标头设置为指定值。如果之前不存在具有指定名称的标头，系统会创建一个新标头。标头名称比较始终不区分大小写。每个请求标头名称在每个请求中仅出现一次。

属性

• 构造函数

  void

  constructor 函数如下所示：

  (arg: SetRequestHeader)=> {...}

  • 参数

    SetRequestHeader

  • 返回

    SetRequestHeader

• name

  string

  HTTP 请求标头名称。

• 值

  string

  HTTP 请求标头值。

Stage

枚举

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

活动

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

在声明式 Web 请求 API 的某个操作通过 declarativeWebRequest.SendMessageToExtension 发送消息时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      字符串（可选）

      发出请求的文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      文档所在的生命周期。

    • frameId

      number

      值 0 表示请求发生在主帧中；正值表示请求发生时所在的子帧的 ID。如果（子）帧的文档已加载（type 为 main_frame 或 sub_frame），则 frameId 表示此帧的 ID，而不是外框架的 ID。帧 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      发生导航的帧类型。

    • 信息

      string

      调用脚本发送的消息。

    • method

      string

      标准 HTTP 方法。

    • parentDocumentId

      字符串（可选）

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      用于封装发送请求的帧的帧的 ID。如果不存在父框架，则设置为 -1。

    • requestId

      string

      请求的 ID。在浏览器会话中，请求 ID 是唯一的。因此，可用于关联同一请求的不同事件。

    • 流程中的

      阶段

      触发事件的网络请求的阶段。

    • tabId

      number

      发出请求的标签页的 ID。如果请求与标签页无关，则设为 -1。

    • timeStamp

      number

      此信号触发的时间（以毫秒为单位，从 Epoch 起算）。

    • 类型

      webRequest.ResourceType

      将如何使用请求的资源。

    • 网址

      string

onRequest

提供由 addRules、removeRules 和 getRules 组成的声明式事件 API。

条件

RequestMatcher

Action

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules