类：WebRequest

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

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

每个 API 接收一可选的 filter 和 listener,当 API 事件发生的时候使用 listener(details) 调用 listener, details 是一个用来描述请求的对象.将 null作为 listener传递将取消订阅事件.

filter 是一个拥有 urls 属性的对象,这是一个 url 模式数组,用来过滤掉不匹配指定 url 模式的请求.如果忽略 filter ,那么所有请求都将可以成功匹配.

所有事件的 listener 都有一个回调事件,当 listener 完成它的工作的时候,它将使用一个 response 对象来调用.

为请求添加User-Agent标头的示例:

const {session} = require('electron')
// 将所有请求的代理都修改为下列 url.
const filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io']
}
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({cancel: false, requestHeaders: details.requestHeaders})
})

实例方法

`webRequest.onBeforeRequest([filter, ]listener)`

用途:即将发起请求时,调用 listener

filter Object
listener Function
- urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
- details Object
  - id Integer
  - url String
  - method String
  - resourceType String
  - timestamp Double
  - uploadData UploadData[] - UploadData对象的数组
- callback Function 使用一个 response 对象来调用 callback
  - response Object
    - cancel Boolean (可选)
    - redirectURL String (可选) - 阻止原始请求被发送或完成,把它重定向到给定的URL。

`webRequest.onBeforeSendHeaders([filter, ]listener)`

用途:在发送 HTTP 请求的之前,一旦请求头可用,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function- 可能会发生在和服务器发起tcp连接之后,发送任何 http 数据之前.
details Object
- id Integer
- url String
- method String
- resourceType String
- timestamp Double
- requestHeaders Object
callback Function 使用一个 response 对象来调用 callback
- response Object
  - cancel Boolean (可选)
  - requestHeaders Object (可选) - 当提供时，将使用 headers 发出请求

`webRequest.onSendHeaders([filter, ]listener)`

用途:当请求被发送到服务器之前,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function
- details Object
  - id Integer
  - url String
  - method String
  - resourceType String
  - timestamp Double
  - requestHeaders Object

以前的 onBeforeSendHeaders 响应的修改在这个监听器触发时是可见的。

`webRequest.onHeadersReceived([filter, ]listener)`

用途:当接收到请求的HTTP响应头时,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function
details Object
- id String
- url String
- method String
- resourceType String
- timestamp Double
- statusLine String
- statusCode Integer
- responseHeaders Object
callback Function 使用一个 response 对象来调用 callback
- response Object
  - cancel Boolean
  - responseHeaders Object (可选) - 如果提供, 服务器将假定使用这些头来响应.
  - statusLine String (可选) - 应该在覆盖 responseHeaders更改标头状态时提供,否则将使用原始响应标头状态。

`webRequest.onResponseStarted([filter, ]listener)`

用途:当接收到响应主体的第一个字节时,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function
- details Object
  - id Integer
  - url String
  - method String
  - resourceType String
  - timestamp Double
  - responseHeaders Object
  - fromCache Boolean - 响应是否从磁盘缓存中获取
  - statusCode Integer
  - statusLine String

对于HTTP请求来说,这意味着状态线和响应头可用了.

`webRequest.onBeforeRedirect([filter, ]listener)`

用途:当服务器发起重定向即将发生时,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function
- details Object
  - id String
  - url String
  - method String
  - resourceType String
  - timestamp Double
  - redirectURL String
  - statusCode Integer
  - ip String (可选) - 请求的真实服务器ip actually sent to.
  - fromCache Boolean
  - responseHeaders Object

`webRequest.onCompleted([filter, ]listener)`

用途:当请求完成时,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function
- details Object
  - id Integer
  - url String
  - method String
  - resourceType String
  - timestamp Double
  - responseHeaders Object
  - fromCache Boolean
  - statusCode Integer
  - statusLine String

`webRequest.onErrorOccurred([filter, ]listener)`

用途:当发生错误时,调用 listener

urls String[] - URL模式数组,用于过滤与该数组不匹配的请求.
filter Object
listener Function
- details Object
  - id Integer
  - url String
  - method String
  - resourceType String
  - timestamp Double
  - fromCache Boolean
  - error String - 错误描述.

页面请求