该 API 还在 beta 测试中，仅对 beta 分支和 dev 分支的 Chrome 用户可用。

chrome.declarativeWebRequest

描述： 注意：该 API 目前无人维护，什么时候正式支持还没有具体的计划。使用 chrome.declarativeWebRequest API 实时地拦截、阻止或修改请求，它比 chrome.webRequest API 要快得多，因为您注册的规则在浏览器中而不是 JavaScript 引擎中求值，这样就减少了来回延迟，效率更高。
可用版本： 仅用于 Beta 和 Dev 分支。了解更多内容
权限： "declarativeWebRequest"
主机权限

清单文件

您必须在扩展程序的清单文件中声明 "declarativeWebRequest" 权限和主机权限才能使用这一 API。 

      {
        "name": "我的扩展程序",
        ...
        "permissions": [
          "declarativeWebRequest",
          "*://*/*"
        ],
        ...
      }

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

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

对于您希望触发消息的网络请求，SendMessageToExtension 操作要求对应主机的主机权限。

所有其他操作要求访问所有 URL 的主机权限。

例如，如果扩展程序唯一拥有的主机权限是 "*://*.google.com/*"，这样的扩展程序可以设置如下规则：

  • 取消发送自“http://www.google.com”或“http://anything.else.com”的请求
  • 导航至“http://www.google.com”时发送消息，但是导航至“http://something.else.com”时不能发送消息。
扩展程序不能设置规则，将“http://www.google.com”重定向至“http://mail.google.com”。

规则

声明式网络请求 API 遵循声明式 API 的概念，您可以向 chrome.declarativeWebRequest.onRequest 事件对象注册规则。

声明式网络请求API支持一种匹配条件的类型，即 RequestMatcher，当且仅当列出的所有条件都满足时 RequestMatcher 才会匹配网络请求。当用户在 URL 栏中输入“http://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，所有内嵌框架的请求也不会匹配。

注意：所有条件与操作都必须通过上述例子中所示的构造函数创建。

为了取消所有发送至“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]);

注意：您始终应该一次性批量注册或取消注册规则，而不是单独进行，因为每一次这样的操作都需要重新创建内部的数据结构，这一重新创建的过程需要大量的计算，但是可以利用一种极快的 URL 匹配算法，用于几十万个 URL。事件 API 的性能部分提供了进一步的性能提示。

条件与操作的求值

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

能够处理条件属性的请求阶段：
条件属性 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() 组合，因为内容类型确定后就不能再设置请求标头了。

使用优先级覆盖规则

规则中可以包含优先级，如事件 API 中所述，这种机制可以用来表达例外。如下例子将阻止除了来自服务器 "myserver.com" 以外所有名称为 "evil.jpg" 的图片请求，。 

      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 操作，它仅应用于同一网络请求在同一阶段执行的其他操作。

摘要

类型
HeaderFilter
RequestMatcher
CancelRequest
RedirectRequest
RedirectToTransparentImage
RedirectToEmptyDocument
RedirectByRegEx
SetRequestHeader
RemoveRequestHeader
AddResponseHeader
RemoveResponseHeader
IgnoreRules
SendMessageToExtension
RequestCookie
ResponseCookie
FilterResponseCookie
AddRequestCookie
AddResponseCookie
EditRequestCookie
EditResponseCookie
RemoveRequestCookie
RemoveResponseCookie
事件
onRequest
onMessage

类型

HeaderFilter

通过各种条件过滤请求标头，多个条件将同时求值。
属性
string （可选）
namePrefix

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

string （可选）
nameSuffix

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

array of string or string （可选）
nameContains

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

string （可选）
nameEquals

如果标头的名称与指定字符串相同则匹配。

string （可选）
valuePrefix

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

string （可选）
valueSuffix

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

array of string or string （可选）
valueContains

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

string （可选）
valueEquals

如果标头的值与指定字符串相同则匹配。

RequestMatcher

通过各种条件匹配网络事件。
属性
events.UrlFilter （可选）
url

如果请求所对应的 URL 满足 UrlFilter 的条件则匹配。

events.UrlFilter （可选）
firstPartyForCookiesUrl

如果请求的“第一方”URL 满足 UrlFilter 的条件则匹配，请求的“第一方”URL（如果存在的话）可能与请求的目标 URL 不同，描述的是相对于第三方 Cookie 检查的“第一方”。

array of enum of "main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", or "other" （可选）
resourceType

如果请求的类型包含在列表中则匹配，不匹配指定的任何类型的请求将被过滤出去。

array of string （可选）
contentType

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

array of string （可选）
excludeContentType

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

array of HeaderFilter （可选）
requestHeaders

如果某些请求标头匹配 HeaderFilter 中的某一个则匹配该请求。

array of HeaderFilter （可选）
excludeRequestHeaders

如果请求标头都不匹配任何一个 HeaderFilter 则匹配该请求。

array of HeaderFilter （可选）
responseHeaders

如果某些响应标头匹配 HeaderFilter 中的某一个则匹配该请求。

array of HeaderFilter （可选）
excludeResponseHeaders

如果响应标头都不匹配任何一个 HeaderFilter 则匹配该请求。

boolean （可选）
thirdPartyForCookies

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

array of enum of "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", or "onAuthRequired" （可选）
stages

包含描述阶段的字符串列表，允许的值包括 'onBeforeRequest'、'onBeforeSendHeaders'、'onHeadersReceived'、'onAuthRequired'。如果该属性存在的话，它会将适用的阶段限制在这一列表中。注意整个条件只能在与所有属性兼容的阶段中适用。

CancelRequest

声明式事件操作，取消网络请求。

RedirectRequest

声明式事件操作，重定向网络请求。
属性
string redirectUrl

请求重定向的目标。

RedirectToTransparentImage

声明式事件操作，将网络请求重定向至透明图片。

RedirectToEmptyDocument

声明式事件操作，将网络请求重定向至空文档。

RedirectByRegEx

对 URL 应用正则表达式，重定向请求。正则表达式采用 RE2 语法。
属性
string from

匹配表达式，可以包含捕获性分组。为了更接近 JavaScript 正则表达式，捕获性分组以 Perl 语法（$1、$2……），而不是 RE2 语法（\1、\2……）引用。

string to

目标表达式。

SetRequestHeader

将指定名称的请求标头设置为指定值。如果指定名称的标头原来不存在，则会创建新的。标头名称的比较不区分大小写，且每个请求中每个请求标头名称只会出现一次。
属性
string name

HTTP 请求标头的名称。

string value

HTTP 请求标头的值。

RemoveRequestHeader

移除指定名称的请求标头。不要在同一请求的同一标头名称上同时使用 SetRequestHeader 和 RemoveRequestHeader。每个请求中每个请求标头名称只会出现一次。
属性
string name

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

AddResponseHeader

向当前网络请求的响应中添加响应标头。由于多个响应标头可能会使用相同的名称，您需要首先删除然后再添加新的响应标头才能完成替换。
属性
string name

HTTP 响应标头的名称。

string value

HTTP 响应标头的值。

RemoveResponseHeader

删除指定名称和值的所有响应标头。
属性
string name

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

string （可选）
value

HTTP 响应标头的值（不区分大小写）。

IgnoreRules

排除所有匹配指定条件的规则。
属性
integer （可选）
lowerPriorityThan

如果设置的话，将忽略优先级低于指定值的规则。这一界限不是持久的，它只会影响同一网络请求阶段的规则与它们对应的操作。

string （可选）
hasTag

如果设置的话，包含指定标签的规则将被忽略。这一忽略不是持久的，它只影响同一网络请求阶段的规则及其操作。注意，规则按照优先级递减的顺序执行，该操作只会影响优先级低于当前规则的规则，具有相同优先级的规则可能会也可能不会被忽略。

SendMessageToExtension

触发 declarativeWebRequest.onMessage 事件。
属性
string message

传递给事件处理函数的词典中 message 属性的值。

RequestCookie

用于过滤或指定 HTTP 请求中的 Cookie。
属性
string （可选）
name

Cookie 的名称。

string （可选）
value

Cookie 的值，可以填充在双引号中。

ResponseCookie

用于指定 HTTP 响应中的 Cookie。
属性
string （可选）
name

Cookie 的名称。

string （可选）
value

Cookie 的值，可以填充在双引号中。

string （可选）
expires

Cookie 的 Expires 属性值。

double （可选）
maxAge

Cookie 的 Max-Age 属性值。

string （可选）
domain

Cookie 的 Domain 属性值。

string （可选）
path

Cookie 的 Path 属性值。

string （可选）
secure

Cookie 的 Secure 属性是否存在。

string （可选）
httpOnly

Cookie 的 HttpOnly 属性是否存在。

FilterResponseCookie

用于 HTTP 响应 Cookie 的过滤器。
属性
string （可选）
name

Cookie 的名称。

string （可选）
value

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

string （可选）
expires

Cookie 的 Expires 属性值。

double （可选）
maxAge

Cookie 的 Max-Age 属性值。

string （可选）
domain

Cookie 的 Domain 属性值。

string （可选）
path

Cookie 的 Path 属性值。

string （可选）
secure

Cookie 的 Secure 属性是否存在。

string （可选）
httpOnly

Cookie 的 HttpOnly 属性是否存在。

integer （可选）
ageUpperBound

Cookie 生命周期的上界（包含）（以当前时间之后多少秒的形式指定），只有过期日期时间在区间 [现在, 现在 + ageUpperBound] 内的 Cookie 满足这一条件，会话 Cookie 以及过期时间在过去的 Cookie 不满足该过滤器的条件。Cookie 的生命周期通过 Cookie 的 'max-age' 或 'expires' 属性来计算，如果两者都指定则使用 'max-age' 来计算 Cookie 的生命周期。

integer （可选）
ageLowerBound

Cookie 生命周期的下界（包含）（以当前时间之后多少秒的形式指定），只有过期日期时间在区间 [现在 + ageLowerBound, 现在] 内的 Cookie 满足这一条件，会话 Cookie 以及过期时间在过去的 Cookie 不满足该过滤器的条件。Cookie 的生命周期通过 Cookie 的 'max-age' 或 'expires' 属性来计算，如果两者都指定则使用 'max-age' 来计算 Cookie 的生命周期。

boolean （可选）
sessionCookie

过滤会话 Cookie，会话 Cookie 没有 'max-age' 或 'expires' 属性指定的生命周期。

AddRequestCookie

向请求中添加或者覆盖（如果相同名称的 Cookie 已经存在）Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。
属性

AddResponseCookie

向响应中添加或者覆盖（如果相同名称的 Cookie 已经存在）Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。
属性

EditRequestCookie

编辑请求中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。
属性
declarativeWebRequest.RequestCookie filter

过滤要修改的 Cookie，所有空项都会忽略。

declarativeWebRequest.RequestCookie modification

在匹配过滤器的 Cookie 中应该覆盖的属性，设置为空字符串的属性将移除。

EditResponseCookie

编辑响应中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。
属性
declarativeWebRequest.FilterResponseCookie filter

过滤要修改的 Cookie，所有空项都会忽略。

declarativeWebRequest.ResponseCookie modification

在匹配过滤器的 Cookie 中应该覆盖的属性，设置为空字符串的属性将移除。

RemoveRequestCookie

移除请求中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。
属性
declarativeWebRequest.RequestCookie filter

过滤要移除的 Cookie，所有空项都会忽略。

RemoveResponseCookie

移除响应中的一个或多个 Cookie。注意，您应该首选 Cookie API，因为它在计算上开销更少。
属性
declarativeWebRequest.FilterResponseCookie filter

过滤要移除的 Cookie，所有空项都会忽略。

事件

onRequest

提供声明式事件 API，包括 addRules、removeRules 和 getRules。

chrome.declarativeWebRequest.onRequest.addRules(array of Rule rules, function callback) chrome.declarativeWebRequest.onRequest.removeRules(array of string ruleIdentifiers, function callback) chrome.declarativeWebRequest.onRequest.getRules(array of string ruleIdentifiers, function callback)

支持的条件

支持的操作

onMessage

当消息通过声明式网络请求 API 的 declarativeWebRequest.SendMessageToExtension 操作发送时产生。

addListener

chrome.declarativeWebRequest.onMessage.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
string message

调用脚本发送的消息。

enum of "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", or "onAuthRequired" stage

事件发生时网络请求所处的阶段。

string requestId

请求标识符。请求标识符在浏览器会话中保证唯一，所以，它们可以用来联系同一请求的不同事件。

string url
string method

标准 HTTP 方法。

integer frameId

0 表示请求发生在主框架中，正数表示发出请求的子框架标识符。如果加载了（子）框架的文档（type 为 "main_frame" 或 "sub_frame"），frameId 指定该框架的标识符，而不是外层框架的标识符。框架标识符在标签页中保证唯一。

integer parentFrameId

包含发送请求框架的框架（即父框架）标识符，如果不存在父框架则为 -1。

integer tabId

产生请求的标签页标识符。如果请求与标签页无关则为 -1。

enum of "main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", or "other" type

请求的资源将如何使用。

double timeStamp

该信号触发的时间，以 1970 年 1 月 1 日午夜开始所经过的毫秒数表示。

示例扩展程序