chrome.declarativeWebRequest

说明

注意：此 API 已废弃。不妨改用 declarativeNetRequest API。使用 chrome.declarativeWebRequest API 拦截、阻止或修改传输中的请求。它比 chrome.webRequest API 快得多，因为您可以注册在浏览器（而不是 JavaScript 引擎）中评估的规则，从而减少往返延迟时间并提高效率。

权限

declarativeWebRequest

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

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

可用性

<ph type="x-smartling-placeholder"></ph> Beta 渠道 &amp;leq;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 才会匹配网络请求。以下 当用户在RequestMatcherhttps://www.example.com 多功能框：

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

由于 scheme，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 的“性能”部分提供了进一步的性能提示。

条件和操作的评估

声明式网络请求 API 遵循网络请求的生命周期模型 请求 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		✓

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

注意：由重定向操作发起的重定向会使用重定向的原始请求方法 但有一个例外：如果重定向是在“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 操作在请求中不会持久保留 阶段。系统会在网络请求的每个阶段评估所有规则的所有条件。如果 已执行 IgnoreRules 操作，但它仅适用于针对同一网页执行的其他操作 Web 请求。

类型

AddRequestCookie

向请求添加 Cookie 或覆盖 Cookie，以防已存在其他同名的 Cookie。请注意，最好使用 Cookies API，因为此 API 的计算开销较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    AddRequestCookie

  • 返回

    AddRequestCookie

• 饼干

  RequestCookie

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

AddResponseCookie

向响应添加一个 Cookie，如果已存在另一个同名的 Cookie，则覆盖一个 Cookie。请注意，最好使用 Cookies API，因为此 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，因为此 API 的计算开销较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    EditRequestCookie

  • 返回

    EditRequestCookie

• filter

  RequestCookie

  过滤出要修改的 Cookie。所有空条目都会被忽略。

• 修改

  RequestCookie

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

EditResponseCookie

修改一个或多个响应 Cookie。请注意，最好使用 Cookies API，因为此 API 的计算开销较低。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    EditResponseCookie

  • 返回

    EditResponseCookie

• filter

  FilterResponseCookie

  过滤出要修改的 Cookie。所有空条目都会被忽略。

• 修改

  ResponseCookie

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

FilterResponseCookie

HTTP 响应中 Cookie 的过滤器。

属性

• ageLowerBound

  编号（选填）

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

• ageUpperBound

  编号（选填）

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

• 网域

  字符串（可选）

  网域 Cookie 属性的值。

• expires

  字符串（可选）

  到期 Cookie 属性的值。

• httpOnly

  字符串（可选）

  是否存在 HttpOnly Cookie 属性。

• maxAge

  编号（选填）

  Max-Age Cookie 属性的值

• name

  字符串（可选）

  Cookie 的名称。

• 路径

  字符串（可选）

  路径 Cookie 属性的值。

• 安全

  字符串（可选）

  安全 Cookie 属性是否存在。

• 会话 Cookie

  布尔值（可选）

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

• 值

  字符串（可选）

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

HeaderFilter

针对各种条件的过滤器请求标头。多个条件会作为一个连接进行求值。

属性

• nameContains

  string |string[] 选填

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

• nameEquals

  字符串（可选）

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

• 名称前缀

  字符串（可选）

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

• nameSuffix

  字符串（可选）

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

• valueContains

  string |string[] 选填

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

• valueEquals

  字符串（可选）

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

• valuePrefix

  字符串（可选）

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

• valueSuffix

  字符串（可选）

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

IgnoreRules

遮盖与指定条件匹配的所有规则。

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    IgnoreRules

  • 返回

    IgnoreRules

• hasTag

  字符串（可选）

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

• lowerPriorityThan

  编号（选填）

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

RedirectByRegEx

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

属性

• 构造函数

  void

  constructor 函数如下所示：

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

  • 参数

    RedirectByRegEx

  • 返回

    RedirectByRegEx

• 来自

  字符串

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

• 至

  字符串

  目标格式。

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，因为此 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，因为此 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[] 选填

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

• excludeContentType

  string[] 选填

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

• excludeRequestHeaders

  HeaderFilter[] 可选

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

• excludeResponseHeaders

  HeaderFilter[] 可选

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

• firstPartyForCookiesUrl

  UrlFilter 可选

  <ph type="x-smartling-placeholder"></ph> 已弃用

  自版本 82 起已忽略。

  如果“第一方”满足 UrlFilter 的条件，则匹配请求的网址。“第一方”请求的网址（如果存在）可以与请求的目标网址不同，并说明什么是“第一方”以便进行第三方 Cookie 检查。

• requestHeaders

  HeaderFilter[] 可选

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

• resourceType

  ResourceType[] 选填

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

• responseHeaders

  HeaderFilter[] 可选

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

• 阶段

  Stage[]（可选）

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

• thirdPartyForCookies

  布尔值（可选）

  <ph type="x-smartling-placeholder"></ph> 已弃用

  自版本 87 起已忽略。

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

• 网址

  UrlFilter 可选

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

ResponseCookie

HTTP 响应中 Cookie 规范。

属性

• 网域

  字符串（可选）

  网域 Cookie 属性的值。

• expires

  字符串（可选）

  到期 Cookie 属性的值。

• httpOnly

  字符串（可选）

  是否存在 HttpOnly Cookie 属性。

• maxAge

  编号（选填）

  Max-Age Cookie 属性的值

• name

  字符串（可选）

  Cookie 的名称。

• 路径

  字符串（可选）

  路径 Cookie 属性的值。

• 安全

  字符串（可选）

  安全 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,
)

通过声明式网络请求 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

      导航发生的帧类型。

    • 消息

      字符串

      由调用脚本发送的消息。

    • method

      字符串

      标准 HTTP 方法。

    • parentDocumentId

      字符串（可选）

      拥有此框架的父文档的 UUID。如果没有父级，则不会设置此字段。

    • parentFrameId

      number

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

    • requestId

      字符串

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

    • 流程中的

      阶段

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

    • tabId

      number

      发生请求的标签页的 ID。如果请求与标签页无关，请将其设为 -1。

    • timeStamp

      number

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

    • 类型

      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