类: WebRequest

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

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

WebRequest 类的实例通过使用 Session 的 webRequest 属性进行访问。

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

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

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

对于某些事件，listener 会传递一个 callback，当 listener 完成其工作后，应该使用一个 response 对象调用它。

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

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 })
})

实例方法

以下方法在 WebRequest 的实例上可用

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - uploadData UploadData[]
- callback 函数
  - response 对象
    - cancel 布尔值 (可选)
    - redirectURL 字符串 (可选) - 原始请求被阻止发送或完成，而是重定向到给定的 URL。

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

uploadData 是一个 UploadData 对象数组。

callback 必须使用 response 对象调用。

一些有效的 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 (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - uploadData UploadData[] (可选)
  - requestHeaders Record<string, string>
- callback 函数
  - beforeSendResponse 对象
    - cancel 布尔值 (可选)
    - requestHeaders Record<string, string | string[]> (可选) - 如果提供，则将使用这些标头进行请求。

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

callback 必须使用 response 对象调用。

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - requestHeaders Record<string, string>

在即将向服务器发送请求之前，将使用 listener(details) 调用 listener，之前的 onBeforeSendHeaders 响应的修改在这个监听器触发时可见。

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - statusLine 字符串
  - statusCode 整数
  - responseHeaders Record<string, string[]> (可选)
- callback 函数
  - headersReceivedResponse 对象
    - cancel 布尔值 (可选)
    - responseHeaders Record<string, string | string[]> (可选) - 如果提供，则假定服务器已使用这些标头进行响应。
    - statusLine 字符串 (可选) - 应该在覆盖 responseHeaders 以更改标头状态时提供，否则将使用原始响应标头的状态。

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

callback 必须使用 response 对象调用。

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - responseHeaders Record<string, string[]> (可选)
  - fromCache 布尔值 - 指示是否从磁盘缓存中获取了响应。
  - statusCode 整数
  - statusLine 字符串

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

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - redirectURL 字符串
  - statusCode 整数
  - statusLine 字符串
  - ip 字符串 (可选) - 请求实际发送到的服务器 IP 地址。
  - fromCache 布尔值
  - responseHeaders Record<string, string[]> (可选)

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

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - responseHeaders Record<string, string[]> (可选)
  - fromCache 布尔值
  - statusCode 整数
  - statusLine 字符串
  - error 字符串

当请求完成时，将使用 listener(details) 调用 listener。

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

filter WebRequestFilter (可选)
listener 函数 | null
- details 对象
  - id 整数
  - url 字符串
  - method 字符串
  - webContentsId 整数 (可选)
  - webContents WebContents (可选)
  - frame WebFrameMain | null (可选) - 请求的框架。如果在框架导航或销毁后访问，则可能为 null。
  - resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
  - referrer 字符串
  - timestamp 双精度浮点数
  - fromCache 布尔值
  - error 字符串 - 错误描述。

当发生错误时，将使用 listener(details) 调用 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)​

类: 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)`