这篇翻译不完整。请帮忙从英语翻译这篇文章

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

概况

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

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

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

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

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

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

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

Modifying requests

在下边这些事件中,你可以修改请求. Specifically, you can:

To do this, you need to pass an option with the value "blocking" in the extraInfoSpec argument to the event's addListener(). This makes the listener synchronous. In the listener, you can then return a BlockingResponse object, which indicates the modification you need to make: for example, the modified request header you want to send.

From Firefox 52 onwards, instead of returning BlockingResponse, the listener can return a Promise which is resolved with a BlockingResponse. This enables the listener to process the request asynchronously.

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.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
BlockingResponseChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
CertificateInfoChrome No support NoEdge No support NoFirefox Full support 62Opera No support NoFirefox Android Full support 62
HttpHeadersChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTESChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
RequestFilterChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
ResourceTypeChrome Full support 44Edge No support NoFirefox Full support 45Opera Full support 31Firefox Android Full support 48
SecurityInfoChrome No support NoEdge No support NoFirefox Full support 62Opera No support NoFirefox Android Full support 62
StreamFilterChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
UploadDataChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
filterResponseDataChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
getSecurityInfoChrome No support NoEdge No support NoFirefox Full support 62Opera No support NoFirefox Android Full support 62
handlerBehaviorChangedChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
onAuthRequiredChrome Full support YesEdge Full support 14Firefox Full support 54
Notes
Full support 54
Notes
Notes To handle a request asynchronously, return a Promise from the listener.
Opera Full support YesFirefox Android Full support 54
Notes
Full support 54
Notes
Notes To handle a request asynchronously, return a Promise from the listener.
onBeforeRedirectChrome Full support YesEdge Full support 14Firefox Full support 46Opera Full support YesFirefox Android Full support 48
onBeforeRequestChrome Full support Yes
Notes
Full support Yes
Notes
Notes Asynchronous event listeners are not supported.
Edge Full support 14
Notes
Full support 14
Notes
Notes Asynchronous event listeners are not supported.
Firefox Full support 46
Notes
Full support 46
Notes
Notes Asynchronous event listeners are supported from version 52.
Opera Full support Yes
Notes
Full support Yes
Notes
Notes Asynchronous event listeners are not supported.
Firefox Android Full support 48
Notes
Full support 48
Notes
Notes Asynchronous event listeners are supported from version 52.
onBeforeSendHeadersChrome Full support Yes
Notes
Full support Yes
Notes
Notes Asynchronous event listeners are not supported.
Edge Full support 14
Notes
Full support 14
Notes
Notes Asynchronous event listeners are not supported.
Firefox Full support 45
Notes
Full support 45
Notes
Notes Asynchronous event listeners are supported from version 52.
Opera Full support Yes
Notes
Full support Yes
Notes
Notes Asynchronous event listeners are not supported.
Firefox Android Full support 48
Notes
Full support 48
Notes
Notes Asynchronous event listeners are supported from version 52.
onCompletedChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
onErrorOccurredChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
onHeadersReceivedChrome Full support Yes
Notes
Full support Yes
Notes
Notes Asynchronous event listeners are not supported.
Edge Full support 14
Notes
Full support 14
Notes
Notes Asynchronous event listeners are not supported.
Firefox Full support 45
Notes
Full support 45
Notes
Notes Modification of the 'Content-Type' header is supported from version 51.
Notes Asynchronous event listeners are supported from version 52.
Opera Full support Yes
Notes
Full support Yes
Notes
Notes Asynchronous event listeners are not supported.
Firefox Android Full support 48
Notes
Full support 48
Notes
Notes Modification of the 'Content-Type' header is supported from version 51.
Notes Asynchronous event listeners are supported from version 52.
onResponseStartedChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
onSendHeadersChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Edge incompatibilities

Promises are not supported in Edge. Use callbacks instead.

Chrome incompatibilities

webRequest

  • In Firefox requests can be redirected only if their original URL uses the http: or https: scheme.
  • In Firefox, events are not fired for system requests (for example, extension upgrades or searchbar suggestions). From Firefox 57 onwards, Firefox makes an exception for extensions that need to intercept webRequest.onAuthRequired for proxy authorization. See the documentation for webRequest.onAuthRequired.
  • In Firefox, if an extension wants to redirect a public (e.g. HTTPS) URL to an extension page, the extension's manifest.json file must contain a web_accessible_resources key that lists the URL for the extension page. Note that any website may then link or redirect to that url, and extensions should treat any input (POST data, for examples) as if it came from an untrusted source, just as a normal web page should.
  • In Firefox, starting from Firefox 52, some of the browser.webRequest.* APIs allow returning Promises that resolves webRequest.BlockingResponse asynchronously. In Chrome, only webRequest.onAuthRequired supports asynchronous webRequest.BlockingResponse via supplying 'asyncBlocking'.

Example extensions

Acknowledgements

This API is based on Chromium's chrome.webRequest API. This documentation is derived from web_request.json in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

文档标签和贡献者

此页面的贡献者: fkyq01, h4ck2fun_xiaoshi, abbycar
最后编辑者: fkyq01,