类：WebRequest

类：WebRequest

在一个请求生命周期的不同阶段，截取和修改其内容。

Process: Main
此类不从 'electron' 模块导出. 它只能作为 Electron API 中其他方法的返回值。

使用 Session 的 WebRequest 属性访问 WebRequest 类的实例。

WebRequest 下的所有方法接收 filter 和 listener 两个参数。 当 API 中有事件被触发时, listener(details) 会被调用， details 中包含了请求的详细信息。

⚠️ 仅最后附加的 listener 会被使用。 设置 null 值到 listener 将取消事件订阅。

filter 对象具有一个 url 属性, 它是一个 url 模式数组, 用于筛选出与 url 模式不匹配的请求。 如果省略 filter, 则所有请求都将匹配。

对于某些事件, listener 是通过 callback 传递的, 当 listener 完成其工作时, 应使用 response 对象进行调用。

为 requests 添加 User-Agent 头的示例：

  1. const { session } = require('electron')
  3. // Modify the user agent for all requests to the following urls.
  4. const filter = {
  5.   urls: ['https://*.github.com/*', '*://electron.github.io/*']
  6. }
  8. session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  9.   details.requestHeaders['User-Agent'] = 'MyAgent'
  10.   callback({ requestHeaders: details.requestHeaders })
  11. })

实例方法

以下事件会在Session实例触发。

webRequest.onBeforeRequest([filter, ]listener)

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain (可选)
      • 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)。

uploadData 是UploadData对象的一个数组。

必须使用 response 对象调用callback。

一些有效 urls 的例子：

  1. 'http://foo:1234/'
  2. 'http://foo.com/'
  3. 'http://foo:1234/bar'
  4. '*://*/*'
  5. '*://example.com/*'
  6. '*://example.com/foo/*'
  7. 'http://*.foo:1234/'
  8. 'file://foo:1234/bar'
  9. 'http://foo:*/'
  10. '*://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 (可选)
      • 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 将以 listener(details, callback) 的形式被调用。 这可能发生在对服务器进行 TCP 连接之后，但在发送任何HTTP数据之前。

callback 必须使用 response 对象调用。

webRequest.onSendHeaders([filter, ]listener)

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain (可选)
      • resourceType string - 可以是 mainFrame， subFrame，stylesheet，script，image，font，object，xhr，ping，cspReport，media，webSocket 或 other。
      • referrer string
      • timestamp Double
      • requestHeaders Record<string, string>

在请求发送到服务器之前，listener将以listener(details)的形式被调用，在该侦听器被出发前，上一个对 onBeforeSendHeaders 响应的修改是可见的。

webRequest.onHeadersReceived([filter, ]listener)

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain (可选)
      • 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[]> (optional) - 当提供，服务器认为使用这些头响应。
        • statusLine string (可选) - 当重写 responseHeaders 时应提供改变标头状态，否则将使用原始响应标头的状态。

当HTTP请求接收到报头后，会通过调用 listener(details, callback)方法来触发listener。

callback 必须使用 response 对象调用。

webRequest.onResponseStarted([filter, ]listener)

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain (可选)
      • 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 请求而言，这意味着此时 HTTP 状态行和回应头已经可以读取了。

webRequest.onBeforeRedirect([filter, ]listener)

  • filter WebRequestFilter (可选)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (可选)
      • webContents WebContents (可选)
      • frame WebFrameMain (可选)
      • 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 (可选)
      • 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 (可选)
      • 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。