跳至主要内容

类：WebRequest

类：WebRequest​

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

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

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

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

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

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

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

为请求添加 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（可选）
      • 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 对象的数组。

必须使用 response 对象调用 callback。

一些有效 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（可选）
      • 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 数据之前。

必须使用 response 对象调用 callback。

webRequest.onSendHeaders([filter, ]listener)​

  • filter WebRequestFilter（可选）
  • listener 函数 | null
    • details 对象
      • id 整数
      • url 字符串
      • method 字符串
      • webContentsId 整数（可选）
      • webContents WebContents（可选）
      • frame WebFrameMain（可选）
      • 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（可选）
      • 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。

必须使用 response 对象调用 callback。

webRequest.onResponseStarted([filter, ]listener)​

  • filter WebRequestFilter（可选）
  • listener 函数 | null
    • details 对象
      • id 整数
      • url 字符串
      • method 字符串
      • webContentsId 整数（可选）
      • webContents WebContents（可选）
      • frame WebFrameMain（可选）
      • 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（可选）
      • 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（可选）
      • 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（可选）
      • resourceType 字符串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
      • referrer 字符串
      • timestamp 双精度数
      • fromCache 布尔值
      • error 字符串 - 错误描述。

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