类：WebRequest

类：WebRequest

🌐 Class: WebRequest

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

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

可以通过 Session 的 webRequest 属性访问 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 传递将取消订阅该事件。

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 对象来调用它。

🌐 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 WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • webContents 网页内容（可选）
    • frame WebFrameMain | null（可选）- 请求的框架。如果在框架导航后或被销毁后访问，可能为 null。
    • resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字符串
    • timestamp 双倍
    • uploadData 上传数据
  • callback 函数
    • response 对象
      • cancel 布尔值（可选）
      • redirectURL 字符串（可选）- 原始请求不会被发送或完成，而是重定向到指定的 URL。

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

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

callback 必须使用一个 response 对象来调用。

🌐 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 WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • webContents 网页内容（可选）
    • frame WebFrameMain | null（可选）- 请求的框架。如果在框架导航后或被销毁后访问，可能为 null。
    • resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字符串
    • timestamp 双倍
    • uploadData 上传数据[]（可选）
    • requestHeaders Record<string, string>
  • callback 函数
    • beforeSendResponse 对象
      • cancel 布尔值（可选）
      • requestHeaders Record<string, string | string[]> （可选）——提供后，将使用这些头部进行请求。

listener 会在发送 HTTP 请求之前与 listener(details, callback) 一起调用，一旦请求头可用。这可能发生在与服务器建立 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.

callback 必须使用一个 response 对象来调用。

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

webRequest.onSendHeaders([filter, ]listener)

• filter WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • 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 会在请求发送到服务器之前与 listener(details) 一起被调用，此时可以看到对之前 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 WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • 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 以更改头部状态时应提供，否则将使用原始响应头的状态。

listener将在接收到请求的HTTP响应头时与listener(details, callback)一起被调用。

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

callback 必须使用一个 response 对象来调用。

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

webRequest.onResponseStarted([filter, ]listener)

• filter WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • 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 将在接收到响应体的第一个字节时与 listener(details) 一起调用。对于 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 WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • 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 将会被用 listener(details) 调用。

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

webRequest.onCompleted([filter, ]listener)

• filter WebRequestFilter（可选）
• listener 函数 | 空
  • details 对象
    • id 整数
    • url 字符串
    • method 字符串
    • webContentsId 整数（可选）
    • 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将在请求完成时被listener(details)调用。

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

webRequest.onErrorOccurred([filter, ]listener)

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

当发生错误时，listener 将会被 listener(details) 调用。

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