类：WebRequest

¥Class: WebRequest

在请求生命周期的各个阶段拦截并修改请求的内容。

¥Intercept and modify the contents of a request at various stages of its lifetime.

进程：主进程
该类不是从 'electron' 模块导出的。它仅可用作 Electron API 中其他方法的返回值。

¥Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.

WebRequest 类的实例可以通过使用 Session 的 webRequest 属性来访问。

¥Instances of the WebRequest class are accessed by using the webRequest property of a Session.

WebRequest 的方法接受可选的 filter 和 listener。当 API 事件发生时，listener 将与 listener(details) 一起调用。details 对象描述请求。

¥The methods of WebRequest accept an optional filter and a listener. The listener will be called with listener(details) when the API's event has happened. The details object describes the request.

⚠️ 仅使用最后附加的 listener。将 null 作为 listener 传递将取消订阅该事件。

¥⚠️ Only the last attached listener will be used. Passing null as listener will unsubscribe from the event.

filter 对象有一个 urls 属性，它是一个 URL 模式数组，用于过滤掉与 URL 模式不匹配的请求。如果省略 filter，则所有请求都将被匹配。

¥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. If the filter is omitted then all requests will be matched.

对于某些事件，listener 与 callback 一起传递，当 listener 完成其工作时，应使用 response 对象调用 callback。

¥For certain events the listener is passed with a callback, which should be called with a response object when listener has done its work.

为请求添加 User-Agent 标头的示例：

¥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

以下方法可用于 WebRequest 的实例：

¥The following methods are available on instances of WebRequest:

`webRequest.onBeforeRequest([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - uploadData UploadData[]
- callback 函数
  
  ¥callback Function
  - response 对象
    
    ¥response Object
    - cancel 布尔值（可选）
      
      ¥cancel boolean (optional)
    - redirectURL 字符串（可选） - 原始请求无法发送或完成，而是重定向到给定的 URL。
      
      ¥redirectURL string (optional) - The original request is prevented from being sent or completed and is instead redirected to the given URL.

当请求即将发生时，listener 将与 listener(details, callback) 一起调用。

¥The listener will be called with listener(details, callback) when a request is about to occur.

uploadData 是 UploadData 对象的数组。

¥The uploadData is an array of UploadData objects.

必须使用 response 对象调用 callback。

¥The callback has to be called with an response object.

有效 urls 的一些示例：

¥Some examples of valid urls:

'<all_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 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - uploadData UploadData[]（可选）
    
    ¥uploadData UploadData[] (optional)
  - requestHeaders 记录<字符串，字符串>
    
    ¥requestHeaders Record<string, string>
- callback 函数
  
  ¥callback Function
  - beforeSendResponse 对象
    
    ¥beforeSendResponse Object
    - cancel 布尔值（可选）
      
      ¥cancel boolean (optional)
    - requestHeaders Record<string，字符串 | string[]>（可选） - 提供后，将使用这些标头发出请求。
      
      ¥requestHeaders Record<string, string | string[]> (optional) - When provided, request will be made with these headers.

一旦请求标头可用，在发送 HTTP 请求之前，将使用 listener(details, callback) 调用 listener。这可能发生在与服务器建立 TCP 连接之后、发送任何 http 数据之前。

¥The listener will be called with listener(details, callback) before sending an HTTP request, once the request headers are available. This may occur after a TCP connection is made to the server, but before any http data is sent.

必须使用 response 对象调用 callback。

¥The callback has to be called with a response object.

`webRequest.onSendHeaders([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - requestHeaders 记录<字符串，字符串>
    
    ¥requestHeaders Record<string, string>

在将请求发送到服务器之前，将使用 listener(details) 调用 listener，在触发此监听器时可以看到先前 onBeforeSendHeaders 响应的修改。

¥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.

`webRequest.onHeadersReceived([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - statusLine 字符串
    
    ¥statusLine string
  - statusCode 整数
    
    ¥statusCode Integer
  - responseHeaders 记录<字符串， string[]>（可选）
    
    ¥responseHeaders Record<string, string[]> (optional)
- callback 函数
  
  ¥callback Function
  - headersReceivedResponse 对象
    
    ¥headersReceivedResponse Object
    - cancel 布尔值（可选）
      
      ¥cancel boolean (optional)
    - responseHeaders Record<string，字符串 | string[]>（可选） - 当提供时，假定服务器已使用这些标头进行响应。
      
      ¥responseHeaders Record<string, string | string[]> (optional) - When provided, the server is assumed to have responded with these headers.
    - statusLine 字符串（可选） - 当覆盖 responseHeaders 以更改标头状态时应提供，否则将使用原始响应标头的状态。
      
      ¥statusLine string (optional) - Should be provided when overriding responseHeaders to change header status otherwise original response header's status will be used.

当收到请求的 HTTP 响应标头时，将使用 listener(details, callback) 调用 listener。

¥The listener will be called with listener(details, callback) when HTTP response headers of a request have been received.

必须使用 response 对象调用 callback。

¥The callback has to be called with a response object.

`webRequest.onResponseStarted([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - responseHeaders 记录<字符串， string[]>（可选）
    
    ¥responseHeaders Record<string, string[]> (optional)
  - fromCache 布尔值 - 指示是否从磁盘缓存中获取响应。
    
    ¥fromCache boolean - Indicates whether the response was fetched from disk cache.
  - statusCode 整数
    
    ¥statusCode Integer
  - statusLine 字符串
    
    ¥statusLine string

当收到响应正文的第一个字节时，将使用 listener(details) 调用 listener。对于 HTTP 请求，这意味着状态行和响应标头可用。

¥The listener will be called with listener(details) when first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

`webRequest.onBeforeRedirect([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - redirectURL 字符串
    
    ¥redirectURL string
  - statusCode 整数
    
    ¥statusCode Integer
  - statusLine 字符串
    
    ¥statusLine string
  - ip 字符串（可选） - 请求实际发送到的服务器 IP 地址。
    
    ¥ip string (optional) - The server IP address that the request was actually sent to.
  - fromCache 布尔值
    
    ¥fromCache boolean
  - responseHeaders 记录<字符串， string[]>（可选）
    
    ¥responseHeaders Record<string, string[]> (optional)

当服务器发起的重定向即将发生时，listener 将与 listener(details) 一起调用。

¥The listener will be called with listener(details) when a server initiated redirect is about to occur.

`webRequest.onCompleted([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - responseHeaders 记录<字符串， string[]>（可选）
    
    ¥responseHeaders Record<string, string[]> (optional)
  - fromCache 布尔值
    
    ¥fromCache boolean
  - statusCode 整数
    
    ¥statusCode Integer
  - statusLine 字符串
    
    ¥statusLine string
  - error 字符串
    
    ¥error string

当请求完成时，listener 将与 listener(details) 一起调用。

¥The listener will be called with listener(details) when a request is completed.

`webRequest.onErrorOccurred([filter, ]listener)`

filter 网络请求过滤器（可选）

¥filter WebRequestFilter (optional)
listener Function | null
- details 对象
  
  ¥details Object
  - id 整数
    
    ¥id Integer
  - url 字符串
    
    ¥url string
  - method 字符串
    
    ¥method string
  - webContentsId 整数（可选）
    
    ¥webContentsId Integer (optional)
  - webContents 网页内容（可选）
    
    ¥webContents WebContents (optional)
  - frame WebFrameMain | null（可选） - 请求框架。如果在框架导航或被销毁后访问，则可能是 null。
    
    ¥frame WebFrameMain | null (optional) - Requesting frame. May be null if accessed after the frame has either navigated or been destroyed.
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    
    ¥resourceType string - Can be mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket or other.
  - referrer 字符串
    
    ¥referrer string
  - timestamp 双倍的
    
    ¥timestamp Double
  - fromCache 布尔值
    
    ¥fromCache boolean
  - error 字符串 - 错误描述。
    
    ¥error string - The error description.

当发生错误时，listener 将与 listener(details) 一起调用。

¥The listener will be called with listener(details) when an error occurs.

类：WebRequest​

实例方法​

webRequest.onBeforeRequest([filter, ]listener)​

webRequest.onBeforeSendHeaders([filter, ]listener)​

webRequest.onSendHeaders([filter, ]listener)​

webRequest.onHeadersReceived([filter, ]listener)​

webRequest.onResponseStarted([filter, ]listener)​

webRequest.onBeforeRedirect([filter, ]listener)​

webRequest.onCompleted([filter, ]listener)​

webRequest.onErrorOccurred([filter, ]listener)​

类：WebRequest

实例方法

`webRequest.onBeforeRequest([filter, ]listener)`

`webRequest.onBeforeSendHeaders([filter, ]listener)`

`webRequest.onSendHeaders([filter, ]listener)`

`webRequest.onHeadersReceived([filter, ]listener)`

`webRequest.onResponseStarted([filter, ]listener)`

`webRequest.onBeforeRedirect([filter, ]listener)`

`webRequest.onCompleted([filter, ]listener)`

`webRequest.onErrorOccurred([filter, ]listener)`