chrome.webRequest

Description

使用 chrome.webRequest API 来观察和分析流量并拦截、阻止或修改进行中的请求。

Permissions

webRequest

# Manifest

您必须在扩展清单中声明“webRequest”权限才能使用 Web 请求 API，以及必要的主机权限。为了拦截子资源请求，扩展需要访问请求的 URL 和它的发起者。如果您想以阻塞方式使用 Web 请求 API，则需要另外请求“webRequestBlocking”权限。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest",
    "*://*.google.com/"
  ],
  ...
}

# Life cycle of requests(请求的生命周期)

Web 请求 API 定义了一组遵循 Web 请求生命周期的事件。您可以使用这些事件来观察和分析流量。某些同步事件将允许您拦截、阻止或修改请求。

此处说明了成功请求的事件生命周期，然后是事件定义：

14

  • onBeforeRequest （可选同步）

    当请求即将发生时触发。此事件在建立任何 TCP 连接之前发送，可用于取消或重定向请求。

  • onBeforeSendHeaders （可选同步）

    当请求即将发生并且初始标头已经准备好时触发。该事件旨在允许扩展添加、修改和删除请求标头 (*)。onBeforeSendHeaders 事件传递给所有订阅者，因此不同的订阅者可能会尝试修改请求；有关如何处理，请参阅实现细节部分。此事件可用于取消请求。

  • onSendHeaders

    在所有扩展都有机会修改请求标头后触发，并显示最终 (*) 版本。该事件在标头发送到网络之前触发。此事件提供信息并异步处理。它不允许修改或取消请求。

  • onHeadersReceived （可选同步）

    每次收到 HTTP(S) 响应标头时触发。由于重定向和身份验证请求，每个请求可能会发生多次。此事件旨在允许扩展添加、修改和删除响应标头，例如传入的 Content-Type 标头。缓存指令在触发此事件之前处理，因此修改 Cache-Control 等标头不会影响浏览器的缓存。它还允许您取消或重定向请求。

  • onAuthRequired （可选同步）

    当请求需要用户身份验证时触发。可以同步处理此事件以提供身份验证凭据。请注意，扩展程序可能会提供无效凭据。注意不要通过反复提供无效凭据进入无限循环。这也可用于取消请求。

  • onBeforeRedirect

    在即将执行重定向时触发。重定向可以由 HTTP 响应代码或扩展程序触发。此事件提供信息并异步处理。它不允许您修改或取消请求。

  • onResponseStarted

    当接收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着状态行和响应标头可用。此事件提供信息并异步处理。它不允许修改或取消请求。

  • onCompleted

    当请求被成功处理时触发。

  • onErrorOccurred

    当请求无法成功处理时触发。

Web 请求 API 保证对于每个请求，onCompleted 或 onErrorOccurred 作为最终事件触发，但有一个例外：如果请求被重定向到 data:// URL，则 onBeforeRedirect 是最后报告的事件。

* 请注意，Web 请求 API 为扩展提供了网络堆栈的抽象。在内部，一个 URL 请求可以拆分为多个 HTTP 请求（例如从一个大文件中获取单个字节范围），或者可以由网络堆栈处理而无需与网络通信。因此，API 不提供发送到网络的最终 HTTP 标头。例如，所有与缓存相关的标头对扩展是不可见的。

当前未向 onBeforeSendHeaders 事件提供以下标头。此列表不保证完整或稳定。

  • Authorization
  • Cache-Control
  • Connection
  • Content-Length
  • Host
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

从 Chrome 79 开始，请求标头修改会影响跨域资源共享 (CORS) 检查。如果跨域请求的修改标头不符合标准，将导致发送 CORS 预检以询问服务器是否可以接受此类标头。如果您确实需要以违反 CORS 协议的方式修改标头，则需要在 opt_extraInfoSpec 中指定“extraHeaders”。另一方面，响应头修改不能欺骗 CORS 检查。如果需要欺骗CORS协议，还需要为响应修改指定'extraHeaders'。

从 Chrome 79 开始，webRequest API 默认不会拦截 CORS 预检请求和响应。如果在 opt_extraInfoSpec 中为请求 URL 指定了带有“extraHeaders”的侦听器，则请求 URL 的 CORS 预检对扩展是可见的。 onBeforeRequest 也可以从 Chrome 79 中获取“extraHeaders”。

从 Chrome 79 开始，不提供以下请求标头，如果不在 opt_extraInfoSpec 中指定'extraHeaders'，则无法修改或删除：

  • Origin

    注意：修改 Origin 请求标头可能无法按预期工作，并可能导致响应的 CORS 检查出现意外错误。这是因为虽然扩展只能修改 Origin 请求标头，但它们不能更改请求来源(request origin)或发起者(initiator)，这是 Fetch 规范中定义的一个概念，用于表示谁发起请求。在这种情况下，服务器可能会允许修改请求的 CORS 访问，并将标头的 Origin 放入响应中的 Access-Control-Allow-Origin 标头中。但它不会匹配不可变的请求来源(request origin)并导致 CORS 失败。

从 Chrome 72 开始，如果您需要在跨域读取阻止 (CORB) 阻止响应之前修改响应，则需要在 opt_extraInfoSpec 中指定“extraHeaders”。

从 Chrome 72 开始，不提供以下请求标头，如果不在 opt_extraInfoSpec 中指定“extraHeaders”，则无法修改或删除：

  • Accept-Language
  • Accept-Encoding
  • Referer
  • Cookie

从 Chrome 72 开始，不提供 Set-Cookie 响应标头，如果不在 opt_extraInfoSpec 中指定“extraHeaders”，则无法修改或删除。

从 Chrome 89 开始，如果不在 opt_extraInfoSpec 中指定“extraHeaders”，则无法有效修改或删除 X-Frame-Options响应标头。

注意：在 opt_extraInfoSpec 中指定 'extraHeaders' 可能会对性能产生负面影响，因此只应在真正必要时使用它。

webRequest API 仅公开扩展程序有权查看的请求，前提是其主机权限。此外，只能访问以下方案：http://、https://、ftp://、file://、ws://（Chrome 58 起）、wss://（Chrome 58 起）、urn :（自 Chrome 91 起），或 chrome-extension://。此外，即使使用上述方案之一的 URL 的某些请求也是隐藏的。其中包括 chrome-extension://other_extension_id，其中other_extension_id 不是处理请求的扩展程序的 ID，https://www.google.com/chrome，以及浏览器功能的其他敏感请求核心。此外，来自扩展的同步 XMLHttpRequest 对阻塞事件处理程序隐藏，以防止死锁。请注意，对于某些受支持的方案，由于相应协议的性质，可用事件集可能会受到限制。例如，对于 file: 方案，只能调度 onBeforeRequest、onResponseStarted、onCompleted 和 onErrorOccurred。

从 Chrome 58 开始，webRequest API 支持拦截 WebSocket 握手请求。由于握手是通过 HTTP 升级请求完成的，因此其流程适合面向 HTTP 的 webRequest 模型。请注意，该 API 不会拦截：

  • 通过已建立的 WebSocket 连接发送的单个消息。
  • WebSocket 关闭连接。

WebSocket 请求不支持重定向。

从 Chrome 72 开始，扩展程序只有在对请求的 URL 和请求发起者都具有主机权限时才能拦截请求。

# Concepts(概念)

如以下部分所述，Web 请求 API 中的事件使用请求 ID，您可以在注册事件侦听器时选择指定过滤器和额外信息。

# Request IDs

每个请求都由一个请求 ID 标识。此 ID 在浏览器会话和扩展程序上下文中是唯一的。它在请求的生命周期中保持不变，可用于匹配同一请求的事件。请注意，在 HTTP 重定向或 HTTP 身份验证的情况下，多个 HTTP 请求会映射到一个 Web 请求。

# Registering event listeners(注册事件监听器)

要为 Web 请求注册事件侦听器，请使用通常的 addListener() 函数的变体。除了指定回调函数之外，您还必须指定过滤器参数，并且可以指定可选的额外信息参数。

Web 请求 API 的 addListener() 的三个参数具有以下定义：

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

下面是一个监听 onBeforeRequest 事件的例子：

chrome.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

每个 addListener() 调用都将强制回调函数作为第一个参数。此回调函数传递一个包含有关当前 URL 请求的信息的字典。该字典中的信息取决于具体的事件类型以及 opt_extraInfoSpec 的内容。

如果可选的 opt_extraInfoSpec 数组包含字符串 'blocking'（仅允许用于特定事件），则同步处理回调函数。这意味着请求被阻塞，直到回调函数返回。在这种情况下，回调可以返回一个 webRequest.BlockingResponse 来确定请求的进一步生命周期。根据上下文，此响应允许取消或重定向请求 (onBeforeRequest)，取消请求或修改标头（onBeforeSendHeaders、onHeadersReceived），以及取消请求或提供身份验证凭据（onAuthRequired）。

如果可选的 opt_extraInfoSpec 数组包含字符串 'asyncBlocking'（仅允许 onAuthRequired），则扩展可以异步生成 webRequest.BlockingResponse 。

webRequest.RequestFilter 过滤器允许限制在各个维度触发事件的请求：

  • URLs: URL patterns 比如 *://www.google.com/foo*bar.
  • Types：请求类型，例如 main_frame（为顶级框架加载的文档）、sub_frame（为嵌入的框架加载的文档）和image（网站上的图像）。请参阅 webRequest.RequestFilter。
  • Tab ID：一个选项卡的标识符。
  • Window ID：窗口的标识符。

根据事件类型，您可以在 opt_extraInfoSpec 中指定字符串以询问有关请求的其他信息。这仅用于在明确请求时提供有关请求数据的详细信息。

# Implementation details(实施细则)

在开发使用 Web 请求 API 的扩展时，了解几个实现细节可能很重要：

# Conflict resolution(解决冲突)

在 Web 请求 API 的当前实现中，如果至少有一个扩展指示取消请求，则该请求被视为已取消。如果一个扩展取消了一个请求，所有的扩展都会被一个 onErrorOccurred 事件通知。一次只允许一个扩展重定向请求或修改标头。如果多个扩展程序尝试修改请求，则最近安装的扩展程序获胜，而其他所有扩展程序都将被忽略。如果扩展的修改或重定向指令被忽略，则不会通知扩展。

# Caching(缓存)

Chrome 使用两种缓存——一个磁盘缓存和一个非常快的内存缓存。内存缓存的生命周期与渲染进程的生命周期相关联，大致对应于一个选项卡。从内存缓存中响应的请求对于 Web 请求 API 是不可见的。如果请求处理程序改变了它的行为（例如，请求被阻止的行为），简单的页面刷新可能不会尊重这个改变的行为。要确保行为更改通过，请调用 handlerBehaviorChanged() 以刷新内存中的缓存。但不要经常这样做；刷新缓存是一项非常昂贵的操作。在注册或取消注册事件侦听器后，您不需要调用 handlerBehaviorChanged()。

# Timestamps(时间戳)

Web 请求事件的时间戳(timestamp)属性仅保证内部一致。将一个事件与另一个事件进行比较将为您提供它们之间的正确偏移量，但将它们与扩展中的当前时间进行比较（例如，通过 (new Date()).getTime()）可能会产生意想不到的结果。

# Error handling(错误处理)

如果您尝试使用无效参数注册事件，则会引发 JavaScript 错误，并且不会注册事件处理程序。如果在处理事件时抛出错误，或者如果事件处理程序返回无效的阻塞响应，则会将错误消息记录到您的扩展的控制台，并且该请求的处理程序将被忽略。

# Examples(例子)

以下示例说明了如何阻止对 www.evil.com 的所有请求：

chrome.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

由于此函数使用阻塞事件处理程序，因此它需要清单文件中的“webRequest”和“webRequestBlocking”权限。

以下示例以更有效的方式实现了相同的目标，因为不需要将不针对 www.evil.com 的请求传递给扩展：

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

以下示例说明了如何从所有请求中删除 User-Agent 标头：

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

有关更多示例代码，请参阅 Web 请求示例。

Summary

Types
Properties
Methods
Events

Types

BlockingResponse

返回应用了“阻塞”extraInfoSpec 的事件处理程序的值。允许事件处理程序修改网络请求。

PROPERTIES

authCredentials

​ object optional

仅用作对 onAuthRequired 事件的响应。如果设置，则使用提供的凭据发出请求。

  • password

    string

  • username

    string

cancel

​ boolean optional

如果为真，则取消请求。这可以防止发送请求。这可以用作对 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件的响应。

redirectUrl

​ string optional

仅用作对 onBeforeRequest 和 onHeadersReceived 事件的响应。如果设置，原始请求将被阻止发送/完成，而是重定向到给定的 URL。允许重定向到非 HTTP 方案，例如 data:。由重定向操作发起的重定向使用重定向的原始请求方法，但有一个例外：如果重定向是在 onHeadersReceived 阶段启动的，则将使用 GET 方法发出重定向。从带有ws:// 和 wss:// 方案的 URL 重定向将被忽略。

requestHeaders

​ HttpHeaders optional

仅用作对 onBeforeSendHeaders 事件的响应。如果设置，则使用这些请求标头发出请求。

responseHeaders

​ HttpHeaders optional

仅用作对 onHeadersReceived 事件的响应。如果设置，则假定服务器已使用这些响应标头进行响应。仅当您确实要修改标头以限制冲突数量时才返回 responseHeaders（每个请求只有一个扩展可以修改 responseHeaders）。

FormDataItem

Chrome 66+

包含在表单数据中传递的数据。对于 urlencoded 形式，如果数据是 utf-8 字符串，则存储为字符串，否则存储为 ArrayBuffer。对于表单数据，它是 ArrayBuffer。如果form-data 表示上传文件，则是带有文件名的字符串，如果提供了文件名。

TYPE

ArrayBuffer, or string

HttpHeaders

一组 HTTP 标头。每个标头都表示为一个字典，其中包含键名称和value 或 binaryValue。

TYPE

object[]

PROPERTIES

binaryValue

​ number[] optional

如果不能用 UTF-8 表示，则 HTTP 标头的值存储为单个字节值 (0..255)。

name

​ string

HTTP 标头的名称。

value

​ string optional

如果可以用 UTF-8 表示，则 HTTP 标头的值。

IgnoredActionType

Chrome 70+

TYPE

"redirect", "request_headers", "response_headers", or "auth_credentials"

OnAuthRequiredOptions

Chrome 44+

TYPE

"responseHeaders", "blocking", "asyncBlocking", or "extraHeaders"

OnBeforeRedirectOptions

Chrome 44+

TYPE

"responseHeaders", or "extraHeaders"

OnBeforeRequestOptions

Chrome 44+

TYPE

"blocking", "requestBody", or "extraHeaders"

OnBeforeSendHeadersOptions

Chrome 44+

TYPE

"requestHeaders", "blocking", or "extraHeaders"

OnCompletedOptions

Chrome 44+

TYPE

"responseHeaders", or "extraHeaders"

OnErrorOccurredOptions

Chrome 79+

VALUE

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44+

TYPE

"blocking", "responseHeaders", or "extraHeaders"

OnResponseStartedOptions

Chrome 44+

TYPE

"responseHeaders", or "extraHeaders"

OnSendHeadersOptions

Chrome 44+

TYPE

"requestHeaders", or "extraHeaders"

RequestFilter

描述要应用于 webRequest 事件的过滤器的对象。

PROPERTIES

tabId

​ number optional

types

​ ResourceType[] optional

请求类型列表。不能匹配任何类型的请求将被过滤掉。

urls

​ string[]

URL 或 URL 模式列表。无法匹配任何 URL 的请求将被过滤掉。

windowId

​ number optional

ResourceType

Chrome 44+

TYPE

"main_frame", "sub_frame", "stylesheet", "script", "image", "font", "object", "xmlhttprequest", "ping", "csp_report", "media", "websocket", or "other"

UploadData

包含在 URL 请求中上传的数据。

PROPERTIES

bytes

​ any optional

带有数据副本的 ArrayBuffer。

file

​ string optional

包含文件路径和名称的字符串。

Properties

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

每 10 分钟持续间隔可以调用 handlerBehaviorChanged 的最大次数。 handlerBehaviorChanged 是一个昂贵的函数调用，不应该经常调用。

VALUE

20

Methods

handlerBehaviorChanged

chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

当 webRequest 处理程序的行为发生变化时需要调用，以防止由于缓存导致的错误处理。这个函数调用是昂贵的。不要经常调用(call it often)。

PARAMETERS

callback

​ function optional

回调(callback)参数如下所示：

() => void

Events

onActionIgnored

chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

Chrome 70+

当扩展对网络请求的修改提议被忽略时触发。如果与其他扩展发生冲突，就会发生这种情况。

PARAMETERS

callback

​ function

callback 参数看起来像：

(details: object) => void

details

​ object

  • action

    ​ IgnoredActionType

    被忽略的提议行动。

  • requestId

    ​ string

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

onAuthRequired

chrome.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

收到身份验证失败时触发。侦听器有三个选项：它可以提供身份验证凭据，它可以取消请求并显示错误页面，或者它可以对质询不采取任何行动。如果提供了错误的用户凭据，则可能会针对同一请求多次调用此方法。请注意，必须在 extraInfoSpec 参数中指定“blocking”或“asyncBlocking”模式中的一种。

PARAMETERS

callback

​ function

回调(callback)参数如下所示：

(details: object, asyncCallback?: function) => BlockingResponse | undefined

details

​ object

challenger

​ object

请求身份验证的服务器。

  • host

    ​ string

  • port

    ​ number

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • isProxy

    ​ boolean

    Proxy-Authenticate 为真，WWW-Authenticate 为假。

  • method

    ​ string

    标准 HTTP 方法。

  • parentFrameId

    ​ number

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

  • realm

    ​ string optional

    服务器提供的身份验证领域（如果有）。

  • requestId

    ​ string

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

  • responseHeaders

    ​ HttpHeaders optional

    与此响应一起收到的 HTTP 响应标头。

  • scheme

    ​ string

    身份验证方案，例如基本或摘要。

  • statusCode

    ​ number

    Chrome 43+

    服务器返回的标准 HTTP 状态代码。

  • statusLine

    ​ string

    响应的 HTTP 状态行或 HTTP/0.9 响应的“HTTP/0.9 200 OK”字符串（即，缺少状态行的响应）或空字符串（如果没有标头）。

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

asyncCallback

​ function optional

Chrome 58+

asyncCallback 参数如下所示：

(response: BlockingResponse) => void

response

​ BlockingResponse

returns

​ BlockingResponse | undefined

如果在“extraInfoSpec”参数中指定了“blocking”，则事件侦听器应返回此类型的对象。

filter

​ RequestFilter

extraInfoSpec

​ OnAuthRequiredOptions[] optional

onBeforeRedirect

chrome.webRequest.onBeforeRedirect.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnBeforeRedirectOptions[], )

当服务器启动的重定向即将发生时触发。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => void

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • fromCache

    ​ boolean

    指示此响应是否是从磁盘缓存中获取的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • ip

    ​ string optional

    请求实际发送到的服务器 IP 地址。请注意，它可能是文字 IPv6 地址。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • redirectUrl

    ​ string

    新网址。

  • requestId

    ​ string

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

  • responseHeaders

    ​ HttpHeaders optional

    与此重定向一起收到的 HTTP 响应标头。

  • statusCode

    ​ number

    服务器返回的标准 HTTP 状态代码。

  • statusLine

    ​ string

    响应的 HTTP 状态行或 HTTP/0.9 响应的“HTTP/0.9 200 OK”字符串（即，缺少状态行的响应）或空字符串（如果没有标头）。

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

filter

​ RequestFilter

extraInfoSpec

​ OnBeforeRedirectOptions optional

onBeforeRequest

chrome.webRequest.onBeforeRequest.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnBeforeRequestOptions[], )

当请求即将发生时触发。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => BlockingResponse | undefined

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestBody

    ​ object optional

    包含 HTTP 请求正文数据。仅在 extraInfoSpec 包含“requestBody”时提供。

    • error

      ​ string optional

      获取请求正文数据时出错。

    • formData

      ​ object optional

      如果请求方法是 POST 并且主体是以 UTF8 编码的键值对序列，编码为 multipart/form-data 或 application/x-www-form-urlencoded，该字典存在并且对于每个键都包含该键的所有值的列表。如果数据是另一种媒体类型，或者格式不正确，则字典不存在。此字典的示例值是 {'key': ['value1', 'value2']}。

    • raw

      ​ UploadData[] optional

      如果请求方法是 PUT 或 POST，并且 body 还没有在 formData 中解析，则未解析的请求正文元素包含在此数组中。

  • requestId

    ​ string

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

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

returns

​ BlockingResponse | undefined

如果在“extraInfoSpec”参数中指定了“blocking”，则事件侦听器应返回此类型的对象。

filter

​ RequestFilter

extraInfoSpec

​ OnBeforeRequestOptions[] optional

onBeforeSendHeaders

chrome.webRequest.onBeforeSendHeaders.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnBeforeSendHeadersOptions[], )

一旦请求标头可用，在发送 HTTP 请求之前触发。这可能发生在与服务器建立 TCP 连接之后，但在发送任何 HTTP 数据之前。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => BlockingResponse | undefined

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestHeaders

    ​ HttpHeaders optional

    将随此请求发送出去的 HTTP 请求标头。

  • requestId

    ​ string

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

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

returns

​ BlockingResponse | undefined

如果在“extraInfoSpec”参数中指定了“blocking”，则事件侦听器应返回此类型的对象。

filter

​ RequestFilter

extraInfoSpec

​ OnBeforeSendHeadersOptions[] optional

onCompleted

chrome.webRequest.onCompleted.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnCompletedOptions[], )

当请求完成时触发。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => void

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • fromCache

    ​ boolean

    指示此响应是否是从磁盘缓存中获取的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • Ip

    ​ string optional

    请求实际发送到的服务器 IP 地址。请注意，它可能是文字 IPv6 地址。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestId

    ​ string

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

  • responseHeaders

    ​ HttpHeaders optional

    与此响应一起收到的 HTTP 响应标头

  • statusCode

    ​ number

    服务器返回的标准 HTTP 状态代码。

  • statusLine

    ​ string

    响应的 HTTP 状态行或 HTTP/0.9 响应的“HTTP/0.9 200 OK”字符串（即，缺少状态行的响应）或空字符串（如果没有标头）。

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

filter

​ RequestFilter

extraInfoSpec

​ OnCompletedOptions[] optional

onErrorOccurred

chrome.webRequest.onErrorOccurred.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnErrorOccurredOptions[], )

发生错误时触发。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => void

details

​ object

  • error

    ​ string

    错误描述。不保证此字符串在版本之间保持向后兼容。您不得根据其内容进行解析和操作。

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • fromCache

    ​ boolean

    指示此响应是否是从磁盘缓存中获取的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • Ip

    ​ string optional

    请求实际发送到的服务器 IP 地址。请注意，它可能是文字 IPv6 地址。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestId

    ​ string

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

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

filter

​ RequestFilter

extraInfoSpec

​ OnErrorOccurredOptions[] optional

onHeadersReceived

chrome.webRequest.onHeadersReceived.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnHeadersReceivedOptions[], )

当收到请求的 HTTP 响应标头时触发。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => BlockingResponse | undefined

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestId

    ​ string

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

  • responseHeaders

    ​ HttpHeaders optional

    与此响应一起收到的 HTTP 响应标头

  • statusCode

    ​ number

    Chrome 43+

    服务器返回的标准 HTTP 状态代码。

  • statusLine

    ​ string

    响应的 HTTP 状态行或 HTTP/0.9 响应的“HTTP/0.9 200 OK”字符串（即，缺少状态行的响应）或空字符串（如果没有标头）。

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

returns

​ BlockingResponse | undefined

如果在“extraInfoSpec”参数中指定了“blocking”，则事件侦听器应返回此类型的对象。

filter

​ RequestFilter

extraInfoSpec

​ OnHeadersReceivedOptions[] optional

onResponseStarted

chrome.webRequest.onResponseStarted.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnResponseStartedOptions[], )

当收到响应正文的第一个字节时触发。对于 HTTP 请求，这意味着状态行和响应标头可用。

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => void

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • fromCache

    ​ boolean

    指示此响应是否是从磁盘缓存中获取的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • ip

    ​ string optional

    请求实际发送到的服务器 IP 地址。请注意，它可能是文字 IPv6 地址。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestId

    ​ string

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

  • responseHeaders

    ​ HttpHeaders optional

    与此响应一起收到的 HTTP 响应标头。

  • statusCode

    ​ number

    服务器返回的标准 HTTP 状态代码。

  • statusLine

    ​ string

    响应的 HTTP 状态行或 HTTP/0.9 响应的“HTTP/0.9 200 OK”字符串（即，缺少状态行的响应）或空字符串（如果没有标头）。

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

filter

​ RequestFilter

extraInfoSpec

​ OnResponseStartedOptions[] optional

onSendHeaders

chrome.webRequest.onSendHeaders.addListener( callback: function, filter: RequestFilter, extraInfoSpec?: OnSendHeadersOptions[], )

PARAMETERS

callback

​ function

回调参数如下所示：

(details: object) => void

details

​ object

  • frameId

    ​ number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（类型为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • initiator

    ​ string optional

    Chrome 63+

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • method

    ​ string

    标准 HTTP 方法

  • parentFrameId

    ​ number

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

  • requestHeaders

    ​ HttpHeaders optional

    将随此请求发送出去的 HTTP 请求标头。

  • requestId

    ​ string

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

  • tabId

    ​ number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • timeStamp

    ​ number

    触发此信号的时间，以纪元以来的毫秒数为单位。

  • type

    ​ ResourceType

    如何使用请求的资源。

  • url

    ​ string

filter

​ RequestFilter

extraInfoSpec

​ OnSendHeadersOptions[] optional

By.一粒技术服务

results matching ""

    No results matching ""