跳到主要内容

类：WebRequest

类：WebRequest​

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

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

可通过 Session 的 webRequest 属性访问 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 Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 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 (可选)
        • redirectURL string (可选) - 原始请求被阻止发送或完成，而是重定向到给定的 URL。

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

uploadData 是 UploadData 对象数组。

必须使用 response 对象调用 callback。

一些有效的 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 Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket 或 other。
      • referrer string
      • timestamp Double
      • uploadData UploadData[] (可选)
      • requestHeaders Record<string, string>
    • callback Function
      • beforeSendResponse Object
        • cancel boolean (可选)
        • requestHeaders Record<string, string | string[]> (可选) - 提供此属性时，将使用这些标头发出请求。

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

必须使用 response 对象调用 callback。

webRequest.onSendHeaders([filter, ]listener)​

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket 或 other。
      • referrer string
      • timestamp Double
      • requestHeaders Record<string, string>

在请求即将发送到服务器之前，将使用 listener(details) 调用 listener，此时前一个 onBeforeSendHeaders 响应的修改是可见的。

webRequest.onHeadersReceived([filter, ]listener)​

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 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[]> (可选)
    • callback Function
      • headersReceivedResponse Object
        • cancel boolean (可选)
        • responseHeaders Record<string, string | string[]> (可选) - 提供此属性时，假定服务器已使用这些标头响应。
        • statusLine string (可选) - 覆盖 responseHeaders 以更改标头状态时应提供此属性，否则将使用原始响应标头的状态。

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

必须使用 response 对象调用 callback。

webRequest.onResponseStarted([filter, ]listener)​

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket 或 other。
      • referrer string
      • timestamp Double
      • responseHeaders Record<string, string[]> (可选)
      • fromCache boolean - 指示响应是否从磁盘缓存中获取。
      • statusCode Integer
      • statusLine string

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

webRequest.onBeforeRedirect([filter, ]listener)​

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 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 (可选) - 请求实际发送到的服务器 IP 地址。
      • fromCache boolean
      • responseHeaders Record<string, string[]> (可选)

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

webRequest.onCompleted([filter, ]listener)​

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket 或 other。
      • referrer string
      • timestamp Double
      • responseHeaders Record<string, string[]> (可选)
      • fromCache boolean
      • statusCode Integer
      • statusLine string
      • error string

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

webRequest.onErrorOccurred([filter, ]listener)​

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain | null (可选) - 请求帧。如果在帧已导航或已被销毁后访问，则可能为 null。
      • resourceType string - 可以是 mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket 或 other。
      • referrer string
      • timestamp Double
      • fromCache boolean
      • error string - 错误描述。

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