webRequest

为发出的 HTTP 请求在不同阶段添加事件监听器。事件监听器可以接收到请求的详细信息,也可以修改或取消请求。

概况

每个事件都会在请求的特定阶段触发。事件的顺序大概是这样的:

在请求过程中的任意时间,onErrorOccurred 可以被触发。虽然有时候触发的事件顺序不同,举个例子,在火狐浏览器中的 HSTS 过程,在 onBeforeRequest 事件执行后,onBeforeRedirect 事件会被立即触发。

所有的事件,接受 onErrorOccurred 事件,addListener() 有三个参数:

  • 监听本身
  • 一个 filter 对象,所以你仅可以被特定请求或特定的资源类型提醒
  • 一个可选的extraInfoSpec对象。你可以使用这个对象添加特定的事件命令

这个监听函数接收一个details对象,这个对象包含这个请求的信息。他包含一个请求 ID, 在插件中这个 ID 可以关联唯一个请求事件。这个 ID 是浏览器会话和插件上下文中唯一的。他始终在同一个请求中,贯穿着转发和授权等事件中。

在一个给定的主机上使用 webRequest API, 你必须有这个主机的相关权限,包括"webRequest" API permissionhost permission. 为了使用 "blocking" 特性,你必须有 "webRequestBlocking" API 权限。

这个 webRequest API 不能让你进入一些安全敏感的请求,比如update checks and OCSP checks.

Modifying requests

在下边这些事件中,你可以修改请求。比如一些特别的操作:

为了完成这些操作,你需要在extraInfoSpec参数中添加"blocking"的值到事件的addListener()。这将使得监听器变成同步执行。在监听器中,你可以返回一个表明需要作修改的BlockingResponse对象:比如说,你想要发送的修改后的请求头。

从 Firefox 52 开始,监听器会返回一个resolve(BlockingResponse)Promise,而不是直接返回一个BlockingResponse。这使得监听器可以异步地处理请求。

Types

webRequest.ResourceType

Represents a particular kind of resource fetched in a web request.

webRequest.RequestFilter

An object describing filters to apply to webRequest events.

webRequest.HttpHeaders

An array of HTTP headers. Each header is represented as an object with two properties: name and either value or binaryValue.

webRequest.BlockingResponse

An object of this type is returned by event listeners that have set "blocking" in their extraInfoSpec argument. By setting particular properties in BlockingResponse, the listener can modify network requests.

webRequest.UploadData

Contains data uploaded in a URL request.

Properties

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

The maximum number of times that handlerBehaviorChanged() can be called in a 10 minute period.

Functions

webRequest.handlerBehaviorChanged()

This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.

Events

webRequest.onBeforeRequest

Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.

webRequest.onBeforeSendHeaders

Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.

webRequest.onSendHeaders

Fired just before sending headers. If your add-on or some other add-on modified headers in onBeforeSendHeaders, you'll see the modified version here.

webRequest.onHeadersReceived

Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.

webRequest.onAuthRequired

Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.

webRequest.onResponseStarted

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

webRequest.onBeforeRedirect

Fired when a server-initiated redirect is about to occur.

webRequest.onCompleted

Fired when a request is completed.

webRequest.onErrorOccurred

Fired when an error occurs.

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
webRequest
BlockingResponse
BlockingResponse.upgradeToSecure
CertificateInfo
HttpHeaders
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
RequestFilter
RequestFilter.tabId
RequestFilter.urls
RequestFilter.view-source
RequestFilter.windowId
ResourceType
ResourceType.beacon
ResourceType.csp_report
ResourceType.font
ResourceType.image
ResourceType.imageset
ResourceType.main_frame
ResourceType.media
ResourceType.object
ResourceType.object_subrequest
ResourceType.other
ResourceType.ping
ResourceType.script
ResourceType.speculative
ResourceType.stylesheet
ResourceType.sub_frame
ResourceType.web_manifest
ResourceType.websocket
ResourceType.xml_dtd
ResourceType.xmlhttprequest
ResourceType.xslt
SecurityInfo
SecurityInfo.certificateTransparencyStatus
SecurityInfo.certificates
SecurityInfo.cipherSuite
SecurityInfo.errorMessage
SecurityInfo.hsts
SecurityInfo.isDomainMismatch
SecurityInfo.isExtendedValidation
SecurityInfo.isNotValidAtThisTime
SecurityInfo.isUntrusted
SecurityInfo.keaGroupName
SecurityInfo.protocolVersion
SecurityInfo.secretKeyLength
SecurityInfo.signatureSchemeName
SecurityInfo.state
SecurityInfo.usedDelegatedCredentials
SecurityInfo.usedEch
SecurityInfo.usedOcsp
SecurityInfo.usedPrivateDns
SecurityInfo.weaknessReasons
StreamFilter
StreamFilter.close
StreamFilter.disconnect
StreamFilter.error
StreamFilter.ondata
StreamFilter.onerror
StreamFilter.onstart
StreamFilter.onstop
StreamFilter.resume
StreamFilter.status
StreamFilter.suspend
StreamFilter.write
UploadData
filterResponseData
getSecurityInfo
getSecurityInfo.options
handlerBehaviorChanged
onAuthRequired
onAuthRequired.asyncBlocking
onAuthRequired.details
details.challenger
details.cookieStoreId
details.documentUrl
details.frameId
details.incognito
details.isProxy
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.realm
details.requestId
details.responseHeaders
details.scheme
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onBeforeRedirect
onBeforeRedirect.details
details.cookieStoreId
details.documentUrl
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.redirectUrl
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onBeforeRequest
onBeforeRequest.details
details.cookieStoreId
details.documentUrl
details.frameAncestors
details.frameId
details.incognito
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestBody
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onBeforeSendHeaders
onBeforeSendHeaders.details
details.cookieStoreId
details.documentUrl
details.frameAncestors
details.frameId
details.incognito
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestHeaders
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onCompleted
onCompleted.details
details.cookieStoreId
details.documentUrl
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onErrorOccurred
onErrorOccurred.details
details.cookieStoreId
details.documentUrl
details.error
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onHeadersReceived
onHeadersReceived.details
details.cookieStoreId
details.documentUrl
details.frameAncestors
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onResponseStarted
onResponseStarted.details
details.cookieStoreId
details.documentUrl
details.frameId
details.fromCache
details.incognito
details.ip
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestId
details.responseHeaders
details.statusCode
details.statusLine
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification
onSendHeaders
onSendHeaders.details
details.cookieStoreId
details.documentUrl
details.frameId
details.incognito
details.method
details.originUrl
details.parentFrameId
details.proxyInfo
details.requestHeaders
details.requestId
details.tabId
details.thirdParty
details.timeStamp
details.type
details.url
details.urlClassification

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.
Has more compatibility info.