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 请求 API 遵循声明式 API 的概念。您可以向 chrome.declarativeWebRequest.onRequest 事件对象注册规则。

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

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

由于方案，对 https://www.example.com 的请求会被 RequestMatcher 拒绝。 此外，由于存在 resourceType，所有针对嵌入式 iframe 的请求都会被拒绝。

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

如需取消对“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 Request API 的 Web 请求生命周期模型。这意味着，只能在 Web 请求的特定阶段测试条件，同样，也只能在特定阶段执行操作。下表列出了与条件和操作兼容的请求阶段。

可以处理条件属性的请求阶段。
“Condition”属性	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` 方法发出重定向。

示例：可以将 `new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})` 条件与 `new chrome.declarativeWebRequest.CancelRequest()` 操作结合使用，因为它们都可以在 `onHeadersReceived` 阶段进行评估。不过，无法将请求匹配器与 `new 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 操作不会在各个请求阶段之间保留。在 Web 请求的每个阶段，系统都会评估所有规则的所有条件。如果执行 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

将响应标头添加到相应 Web 请求的响应中。由于多个响应标头可能具有相同的名称，因此您需要先移除一个响应标头，然后再添加一个新的响应标头，才能替换该标头。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    AddResponseHeader

  • 返回

    AddResponseHeader

• name

  字符串

  HTTP 响应标头名称。

• 值

  字符串

  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

  number 可选

  Cookie 生命周期（以当前时间之后的秒数表示）的下限（含）。只有将失效日期时间设置为“now + ageLowerBound”或更晚时间的 Cookie 才能满足此条件。会话 Cookie 不符合此过滤条件的标准。Cookie 生命周期根据“max-age”或“expires”Cookie 属性计算得出。如果同时指定了这两个属性，系统会使用“max-age”来计算 Cookie 的有效期。

• ageUpperBound

  number 可选

  Cookie 生命周期的上限（含边界值，以当前时间之后的秒数表示）。只有过期日期时间位于 [now, now + ageUpperBound] 区间内的 Cookie 才符合此条件。会话 Cookie 和过期日期时间为过去的 Cookie 不符合此过滤条件的标准。Cookie 生命周期根据“max-age”或“expires”Cookie 属性计算得出。如果同时指定了这两个属性，系统会使用“max-age”来计算 Cookie 的有效期。

• 域名

  字符串 可选

  Domain cookie 属性的值。

• expires

  字符串 可选

  Expires cookie 属性的值。

• httpOnly

  字符串 可选

  HttpOnly cookie 属性是否存在。

• maxAge

  number 可选

  Max-Age cookie 属性的值

• name

  字符串 可选

  Cookie 的名称。

• 路径

  字符串 可选

  Path cookie 属性的值。

• 安全

  字符串 可选

  是否存在 Secure Cookie 属性。

• sessionCookie

  布尔值 （可选）

  过滤会话 Cookie。会话 Cookie 未在任何“max-age”或“expires”属性中指定生命周期。

• 值

  字符串 可选

  Cookie 的值，可能用英文双引号填充。

HeaderFilter

按各种条件过滤请求标头。多个条件会作为合取进行评估。

属性

• nameContains

  字符串 | 字符串数组 可选

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

• nameEquals

  字符串 可选

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

• 名称前缀

  字符串 可选

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

• nameSuffix

  字符串 可选

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

• valueContains

  字符串 | 字符串数组 可选

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

• valueEquals

  字符串 可选

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

• valuePrefix

  字符串 可选

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

• valueSuffix

  字符串 可选

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

IgnoreRules

屏蔽符合指定条件的所有规则。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    IgnoreRules

  • 返回

    IgnoreRules

• hasTag

  字符串 可选

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

• lowerPriorityThan

  number 可选

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

RedirectByRegEx

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

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    RedirectByRegEx

  • 返回

    RedirectByRegEx

• 来自

  字符串

  可能包含捕获组的匹配模式。为了更贴近 JavaScript 正则表达式，捕获组采用 Perl 语法 ($1、$2 等) 而非 RE2 语法 (\1、\2 等) 进行引用。

• 至

  字符串

  目标模式。

RedirectRequest

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

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    RedirectRequest

  • 返回

    RedirectRequest

• redirectUrl

  字符串

  请求重定向到的目的地。

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

  字符串

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

RemoveResponseCookie

移除响应的一个或多个 Cookie。请注意，最好使用 Cookies API，因为这样计算开销更低。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    RemoveResponseCookie

  • 返回

    RemoveResponseCookie

• filter

  FilterResponseCookie

  用于过滤要移除的 Cookie。系统会忽略所有空条目。

RemoveResponseHeader

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

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    RemoveResponseHeader

  • 返回

    RemoveResponseHeader

• name

  字符串

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

• 值

  字符串 可选

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

RequestCookie

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

属性

• name

  字符串 可选

  Cookie 的名称。

• 值

  字符串 可选

  Cookie 的值，可能用英文双引号填充。

RequestMatcher

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

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    RequestMatcher

  • 返回

    RequestMatcher

• contentType

  string[] 可选

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

• excludeContentType

  string[] 可选

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

• excludeRequestHeaders

  HeaderFilter[] 可选HeaderFilter

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

• excludeResponseHeaders

  HeaderFilter[] 可选HeaderFilter

  如果没有任何响应标头与任何 HeaderFilter 相匹配，则匹配。

• firstPartyForCookiesUrl

  UrlFilter（可选）

  已弃用

  自版本 82 发布以来一直被忽略。

  如果请求的“第一方”网址满足 UrlFilter 的条件，则匹配。请求的“第一方”网址（如果存在）可以与请求的目标网址不同，并且描述了在进行第三方 Cookie 检查时，哪些内容被视为“第一方”。

• requestHeaders

  HeaderFilter[] 可选HeaderFilter

  如果某个请求标头与某个 HeaderFilter 匹配，则匹配。

• resourceType

  ResourceType[] 可选

  如果请求的请求类型包含在列表中，则匹配。无法与任何类型匹配的请求会被过滤掉。

• responseHeaders

  HeaderFilter[] 可选HeaderFilter

  如果某个响应标头与某个 HeaderFilter 相匹配，则匹配成功。

• 阶段

  阶段 [] 可选

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

• thirdPartyForCookies

  布尔值 （可选）

  已弃用

  自版本 87 起被忽略。

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

• 网址

  UrlFilter（可选）

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

ResponseCookie

HTTP 响应中 Cookie 的规范。

属性

• 域名

  字符串 可选

  Domain cookie 属性的值。

• expires

  字符串 可选

  Expires cookie 属性的值。

• httpOnly

  字符串 可选

  HttpOnly cookie 属性是否存在。

• maxAge

  number 可选

  Max-Age cookie 属性的值

• name

  字符串 可选

  Cookie 的名称。

• 路径

  字符串 可选

  Path cookie 属性的值。

• 安全

  字符串 可选

  是否存在 Secure Cookie 属性。

• 值

  字符串 可选

  Cookie 的值，可能用英文双引号填充。

SendMessageToExtension

触发 declarativeWebRequest.onMessage 事件。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    SendMessageToExtension

  • 返回

    SendMessageToExtension

• 私信

  字符串

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

SetRequestHeader

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

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    SetRequestHeader

  • 返回

    SetRequestHeader

• name

  字符串

  HTTP 请求标头名称。

• 值

  字符串

  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

      数值

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

    • frameType

      extensionTypes.FrameType

      发生导航的框架的类型。

    • 私信

      字符串

      调用脚本发送的消息。

    • 方法

      字符串

      标准 HTTP 方法。

    • parentDocumentId

      字符串 可选

      拥有相应框架的父级文档的 UUID。如果没有父级，则不设置此属性。

    • parentFrameId

      数值

      封装了发送请求的帧的帧的 ID。如果没有父框架，则设置为 -1。

    • requestId

      字符串

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

    • 阶段

      阶段

      触发相应事件时网络请求所处的阶段。

    • tabId

      数值

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

    • timeStamp

      数值

      触发相应信号的时间，以自纪元以来的毫秒数表示。

    • 类型

      webRequest.ResourceType

      所请求资源的使用方式。

    • 网址

      字符串

onRequest

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

条件

RequestMatcher

操作

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules