This page was saved using WebZIP 7.0.3.1030 offline browser on 12/24/13 11:31:36.
Address: https://crxdoc-zh.appspot.com/extensions/declarativeWebRequest.html
Title: chrome.declarativeWebRequest - Google Chrome 扩展程序开发文档（非官方中文版）  •  Size: 101952

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

chrome.declarativeWebRequest

描述： 使用 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" 属性进一步地约束。

例子：可以将 new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"])) 条件与 new chrome.declarativeWebRequest.CancelRequest() 操作组合，因为它们都可以在 onHeadersReceived 阶段求值，然而不能将该请求匹配器与 new chrome.declarativeWebRequest.RedirectToTransparentImage() 组合，因为内容类型确定后就不能再进行重定向了。

使用优先级覆盖规则

规则中可以包含优先级，如事件 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 操作，它仅应用于同一网络请求在同一阶段执行的其他操作。

chrome.declarativeWebRequest 参考

类型

HeaderFilter

通过各种条件过滤请求头信息，多个条件将同时求值。

HeaderFilter 的属性

namePrefix ( optional string )

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

nameSuffix ( optional string )

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

nameContains ( optional array of string or string )

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

nameEquals ( optional string )

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

valuePrefix ( optional string )

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

valueSuffix ( optional string )

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

valueContains ( optional array of string or string )

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

valueEquals ( optional string )

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

RequestMatcher

通过各种条件匹配网络事件。

RequestMatcher 的属性

url ( optional events.UrlFilter )

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

firstPartyForCookiesUrl ( optional events.UrlFilter )

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

resourceType ( optional array of enum of "main_frame", "sub_frame", "stylesheet", "script", "image", "object", "xmlhttprequest", or "other" )

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

contentType ( optional array of string )

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

excludeContentType ( optional array of string )

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

requestHeaders ( optional array of HeaderFilter )

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

excludeRequestHeaders ( optional array of HeaderFilter )

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

responseHeaders ( optional array of HeaderFilter )

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

excludeResponseHeaders ( optional array of HeaderFilter )

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

thirdPartyForCookies ( optional boolean )

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

stages ( optional array of enum of "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", or "onAuthRequired" )

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

CancelRequest

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

RedirectRequest

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

RedirectRequest 的属性

redirectUrl ( string )

请求重定向的目标。

RedirectToTransparentImage

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

RedirectToEmptyDocument

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

RedirectByRegEx

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

RedirectByRegEx 的属性

from ( string )

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

to ( string )

目标表达式。

SetRequestHeader

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

SetRequestHeader 的属性

name ( string )

HTTP 请求头信息的名称。

value ( string )

HTTP 请求头信息的值。

RemoveRequestHeader

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

RemoveRequestHeader 的属性

name ( string )

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

AddResponseHeader

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

AddResponseHeader 的属性

name ( string )

HTTP 响应头信息的名称。

value ( string )

HTTP 响应头信息的值。

RemoveResponseHeader

删除指定名称和值的所有响应头信息。

RemoveResponseHeader 的属性

name ( string )

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

value ( optional string )

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

IgnoreRules

排除所有匹配指定条件的规则。

IgnoreRules 的属性

lowerPriorityThan ( optional integer )

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

hasTag ( optional string )

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

SendMessageToExtension

触发 onMessage 事件。

SendMessageToExtension 的属性

message ( string )

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

RequestCookie

用于过滤或指定 HTTP 请求中的 Cookie。

RequestCookie 的属性

name ( optional string )

Cookie 的名称。

value ( optional string )

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

ResponseCookie

用于指定 HTTP 响应中的 Cookie。

ResponseCookie 的属性

name ( optional string )

Cookie 的名称。

value ( optional string )

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

expires ( optional string )

Cookie 的 Expires 属性值。

maxAge ( optional double )

Cookie 的 Max-Age 属性值。

domain ( optional string )

Cookie 的 Domain 属性值。

path ( optional string )

Cookie 的 Path 属性值。

secure ( optional string )

Cookie 的 Secure 属性是否存在。

httpOnly ( optional string )

Cookie 的 HttpOnly 属性是否存在。

FilterResponseCookie

用于 HTTP 响应 Cookie 的过滤器。

FilterResponseCookie 的属性

name ( optional string )

Cookie 的名称。

value ( optional string )

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

expires ( optional string )

Cookie 的 Expires 属性值。

maxAge ( optional double )

Cookie 的 Max-Age 属性值。

domain ( optional string )

Cookie 的 Domain 属性值。

path ( optional string )

Cookie 的 Path 属性值。

secure ( optional string )

Cookie 的 Secure 属性是否存在。

httpOnly ( optional string )

Cookie 的 HttpOnly 属性是否存在。

ageUpperBound ( optional integer )

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

ageLowerBound ( optional integer )

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

sessionCookie ( optional boolean )

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

AddRequestCookie

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

AddRequestCookie 的属性

要添加至请求的 Cookie，所有字段都不能为 undefined。

AddResponseCookie

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

AddResponseCookie 的属性

要添加至响应的 Cookie，name 与 value 必须指定。

EditRequestCookie

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

EditRequestCookie 的属性

filter ( RequestCookie )

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

modification ( RequestCookie )

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

EditResponseCookie

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

EditResponseCookie 的属性

filter ( FilterResponseCookie )

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

modification ( ResponseCookie )

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

RemoveRequestCookie

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

RemoveRequestCookie 的属性

filter ( RequestCookie )

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

RemoveResponseCookie

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

RemoveResponseCookie 的属性

filter ( FilterResponseCookie )

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

事件

onRequest

提供声明式事件 API，包括 $ref:[events.Event.addRules addRules]、$ref:[events.Event.removeRules removeRules] 和 $ref:[events.Event.getRules 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 的 SendMessageToExtension 操作发送时产生。

addListener

chrome.declarativeWebRequest.onMessage.addListener(function callback)

参数

callback ( function )

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

function(object details) {...};

details ( object )

属性

message ( string )

调用脚本发送的消息。

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

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

requestId ( string )

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

url ( string )

method ( string )

标准 HTTP 方法。

frameId ( integer )

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

parentFrameId ( integer )

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

tabId ( integer )

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

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

请求的资源将如何使用。

timeStamp ( double )

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