Web Request

类：WebRequest¶

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

进程：主进程
此类不从 'electron' 模块导出，只能作为 Electron API 中其他方法的返回值使用。

WebRequest 类的实例可通过 Session 的 webRequest 属性访问。

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

⚠️ 只会使用最后附加的 listener。将 listener 设为 null 将取消订阅该事件。

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 Function | null
• details Object
  • id Integer
  • url string
  • method string
  • webContentsId Integer（可选）
  • webContents WebContents（可选）
  • frame WebFrameMain | null（可选）- 发起请求的 frame。如果在该 frame 发生导航后或被销毁后访问，则可能为 null。
  • initiatorOrigin string（可选）- 发起请求的来源（例如 https://example.com；对于不透明来源，则为 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 将在请求即将发送到服务器之前以 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 | null（可选）- 发出请求的 frame。 如果在该 frame 已导航或销毁后访问，则可能为 null。
  • initiatorOrigin string（可选）- 发起请求的来源（例如 https://example.com；对于不透明来源则为 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 将以 listener(details) 的形式被调用。对于 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（可选）- 发出请求的 frame。 如果在该 frame 已导航或销毁后访问，则可能为 null。
  • initiatorOrigin string（可选）- 发起请求的来源（例如 https://example.com；对于不透明来源则为 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（可选）- 发起请求的 frame。如果在该 frame 已导航或已被销毁后访问，则可能为 null。
  • initiatorOrigin string（可选）- 发起请求的源（origin）（例如 https://example.com，对于不透明源则为 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。