Class: WebRequest

Class: WebRequest

Intercept and modify the contents of a request at various stages of its lifetime.在请求生命周期的各个阶段拦截和修改请求的内容。

Process:进程：Main
This class is not exported from the 'electron' module. 此类不是从'electron'模块导出的。It is only available as a return value of other methods in the Electron API.它只能作为Electron API中其他方法的返回值使用。

Instances of the WebRequest class are accessed by using the webRequest property of a Session.通过使用Session的WebRequest属性来访问WebRequest类的实例。

The methods of WebRequest accept an optional filter and a listener. WebRequest的方法接受一个可选的filter和一个listener。The listener will be called with listener(details) when the API's event has happened. 当API的事件发生时，将使用listener(details)调用listener。The details object describes the request.details对象描述了请求。

⚠️ Only the last attached listener will be used. 将只使用最后一个附加的listener。Passing null as listener will unsubscribe from the event.将null作为listener传递将取消订阅该事件。

The filter object has a urls property which is an Array of URL patterns that will be used to filter out the requests that do not match the URL patterns. filter对象有一个urls属性，它是一个URL模式数组，将用于筛选出与URL模式不匹配的请求。If the filter is omitted then all requests will be matched.如果省略了filter，那么所有请求都将被匹配。

For certain events the listener is passed with a callback, which should be called with a response object when listener has done its work.对于某些事件，listener会传递一个callback，当listener完成工作时，应该使用response对象来调用该回调。

An example of adding User-Agent header for requests:为请求添加用户代理标头的示例：

const { session } = require('electron')

// Modify the user agent for all requests to the following urls.
const filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io']
}

session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({ requestHeaders: details.requestHeaders })
})

Instance Methods实例方法

The following methods are available on instances of WebRequest:以下方法可用于WebRequest实例：

webRequest.onBeforeRequest([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • uploadData UploadData[]
  • callback Function
    • response Object
      • cancel boolean (optional)
      • redirectURL string (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.原始请求被阻止发送或完成，而是被重定向到给定的URL。

The listener will be called with listener(details, callback) when a request is about to occur.当请求即将发生时，将以listener(details, callback)的形式调用listener。

The uploadData is an array of UploadData objects.uploadData是uploadData对象的数组。

The callback has to be called with an response object.callback必须使用response对象进行调用。

Some examples of valid urls:有效urls的一些示例：

'http://foo:1234/'
'http://foo.com/'
'http://foo:1234/bar'
'*://*/*'
'*://example.com/*'
'*://example.com/foo/*'
'http://*.foo:1234/'
'file://foo:1234/bar'
'http://foo:*/'
'*://www.foo.com/'

webRequest.onBeforeSendHeaders([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • uploadData UploadData[] (optional)
    • requestHeaders Record<string, string>
  • callback Function
    • beforeSendResponse Object
    • cancel boolean (optional)
    • requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.如果提供，将使用这些标头提出请求。

The listener will be called with listener(details, callback) before sending an HTTP request, once the request headers are available. 一旦请求头可用，在发送HTTP请求之前，将以listener(details, callback)的形式调用listener。This may occur after a TCP connection is made to the server, but before any http data is sent.这可能发生在与服务器建立TCP连接之后，但在发送任何http数据之前。

The callback has to be called with a response object.callback必须使用response对象进行调用。

webRequest.onSendHeaders([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • requestHeaders Record<string, string>

The listener will be called with listener(details) just before a request is going to be sent to the server, modifications of previous onBeforeSendHeaders response are visible by the time this listener is fired.在将请求发送到服务器之前，将以listener(details)的形式调用listener，在激发此listener时，可以看到对先前onBeforeSendHeaders响应的修改。

webRequest.onHeadersReceived([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • statusLine string
    • statusCode Integer
    • responseHeaders Record<string, string[]> (optional)
  • callback Function
    • headersReceivedResponse Object
      • cancel boolean (optional)
      • responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.当提供时，假设服务器已经用这些头进行了响应。
      • statusLine string (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.应在重写responseHeaders以更改标头状态时提供，否则将使用原始响应标头的状态。

The listener will be called with listener(details, callback) when HTTP response headers of a request have been received.当接收到请求的HTTP响应标头时，将以listener(details, callback)的形式调用listener。

The callback has to be called with a response object.callback必须使用response对象进行调用。

webRequest.onResponseStarted([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • responseHeaders Record<string, string[]> (optional)
    • fromCache boolean - Indicates whether the response was fetched from disk cache.指示是否从磁盘缓存中提取响应。
    • statusCode Integer
    • statusLine string

The listener will be called with listener(details) when first byte of the response body is received. 当接收到响应主体的第一个字节时，将以listener(details)的形式调用listener。For HTTP requests, this means that the status line and response headers are available.对于HTTP请求，这意味着状态行和响应头是可用的。

webRequest.onBeforeRedirect([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • redirectURL string
    • statusCode Integer
    • statusLine string
    • ip string (optional) - The server IP address that the request was actually sent to.请求实际发送到的服务器IP地址。
    • fromCache boolean
    • responseHeaders Record<string, string[]> (optional)

The listener will be called with listener(details) when a server initiated redirect is about to occur.当服务器启动的重定向即将发生时，将以listener(details)的形式调用listener。

webRequest.onCompleted([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • responseHeaders Record<string, string[]> (optional)
    • fromCache boolean
    • statusCode Integer
    • statusLine string
    • error string

The listener will be called with listener(details) when a request is completed.当一个请求完成时，将以listener(details)的形式调用listener。

webRequest.onErrorOccurred([filter, ]listener)

• filter WebRequestFilter (optional)
• listener Function | null
  • details Object
    • id Integer
    • url string
    • method string
    • webContentsId Integer (optional)
    • webContents WebContents (optional)
    • frame WebFrameMain (optional)
    • resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.可以是mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或other。
    • referrer string
    • timestamp Double
    • fromCache boolean
    • error string - The error description.错误描述。

The listener will be called with listener(details) when an error occurs.当发生错误时，将以listener(details)的形式调用listener。