跳转到主内容

类: ClientRequest

类: ClientRequest

发起HTTP/HTTPS请求.

Process: Main, Utility
This class is not exported from the 'electron' module. 它只能作为 Electron API 中其他方法的返回值。

ClientRequest实现了Writable Stream接口, 因此是一个EventEmitter类型.

new ClientRequest(options)

  • options (Object | string) - 如果 options 是字符串,则为请求的 URL。 如果是对象,它应该通过以下属性完全指定HTTP请求:
    • method string (可选) - HTTP 请求方法。 默认为GET方法。
    • url string (可选) - 请求URL。 必须以绝对路径形式提供,并将协议指定为http或https。
    • headers Record<string, string | string[]> (optional) - Headers to be sent with the request.
    • session Object (可选) - 与请求相关联的Session实例.
    • partition string (可选) - 与请求相关联的partition名称. 默认为空字符串. session 选项取代了 partition。 因此, 如果session是显式指定的, 则partition将被忽略.
    • credentials string (可选) - 可以是 include, omitsame-origin。 是否在此请求中携带 credentials 。 如果设置为 include,将使用与请求相关的会话凭据。 如果设置为 omit,则不会随请求发送凭据(并且不会在 401响应的事件中触发 'login' 事件)。 如果设置为 same-origin,需要指定 origin属性。 这与同名的 fetch 选项的行为相同。 如果未指定此选项,则会发送来自会话的身份验证数据,同时不发送cookie(除非 设置了useSessionCookies)。
    • useSessionCookies boolean (可选) - 是否从提供的会话与请求一起发送cookie。 如果指定了 credentials ,则此选项没有效果。 默认值为 false.
    • protocol string (可选) - 可以是 http:https:。 协议方案的形式为“scheme:”。 默认为 'http:'。
    • host string (可选) - 作为连接提供的服务器主机,主机名和端口号'hostname:port'.
    • hostname string (可选) - 服务器主机名.
    • port Integer (可选) - 服务器侦听的端口号.
    • path string (可选) - 请求URL的路径部分.
    • redirect string (可选) - 可以是 followerrormanual。 当前请求的重定向模式。 当模式为 error 时,任何重定向都会被中止。 当模式为 manual 时,重定向会被取消,除非 request.followRedirectredirect 事件期间同步调用。 默认值为 follow.
    • origin string (可选) - 请求的源 URL。
    • referrerPolicy string (可选) - 可以为 "", no-referrer, no-referrer-when-downgrade, origin 或者 origin-when-cross-origin。 默认为strict-origin-when-cross-origin
    • cache string (可选) - 可以为 default, no-store, reload, no-cache 或者 force-cache

options 属性,如 protocol, host, hostname, portpath,在 URL 模块中会严格遵循 Node.js 的模式

例如,我们可以创建与github.com相同的请求如下:

const request = net.request({
method: 'GET',
protocol: 'https:',
hostname: 'github.com',
port: 443,
path: '/'
})

实例事件

事件: 'response'

返回:

事件: "login"

返回:

  • authInfo Object
    • isProxy boolean
    • scheme string
    • host string
    • port Integer
    • realm string
  • callback Function
    • username string (可选)
    • password string (可选)

当身份验证代理请求用户认证时触发

用户证书会调用 callback方法:

  • username string
  • password string
request.on('login', (authInfo, callback) => {
callback('username', 'password')
})

提供空的凭证将取消请求,并在响应对象上报告一个身份验证错误:

request.on('response', (response) => {
console.log(`STATUS: ${response.statusCode}`);
response.on('error', (error) => {
console.log(`ERROR: ${JSON.stringify(error)}`)
})
})
request.on('login', (authInfo, callback) => {
callback()
})

事件:'finish'

request 最终的 chunk 数据后写入 request 后触发

事件: 'abort'

request 被中止时触发。 如果 request 已经关闭, abort 事件将不会被触发。

Event: 'error'

返回:

  • error Error -提供失败信息的错误对象。

net网络模块没有发出网络请求时会触发。 通常情况下,当 request请求对象发出一个 error错误事件时,一个 close关闭事件会随之发生,并且不会提供响应对象。

事件: 'close'

作为HTTP 的 request-response 中的最后一个事件发出。 close事件表明,在requestresponse 对象中不会发出更多的事件。

事件: 'redirect'

返回:

  • statusCode Integer
  • method string
  • redirectUrl string
  • responseHeaders Record<string, string[]>

当服务器返回重定向响应时触发(例如,301 页面永久性移走)。 调用 request.followRirect 将继续重定向。 如果该事件被处理,request.followRedirect 必须同步调用,否则请求将被取消。

实例属性

request.chunkedEncoding

一个boolean类型的值,指定请求是否将使用 HTTP 分块传输编码。 默认值为 false. 该属性是可读写的, 但它只能在第一次写入操作之前设置,因为还没有写入 HTTP 头。 在第一写入后如果设置chunkedEncoding属性将引发错误。

如果 request 的 body 是一个大的数据时,强烈建议使用块编码。因为数据将以小块的方式进行传输, 而不是在 Electron 进程内存中内部缓冲。

实例方法

request.setHeader(name, value)

  • name string - 额外的 HTTP 头名称.
  • value string - 额外的 HTTP 头部值。

添加一个额外的 HTTP 头。 头名称将按原样发布,不会转为小写。 它只能在第一次写入之前调用。 在第一次写入后调用此方法将引发错误。 如果传入的值不是 string,将调用它的 toString() 方法获取最终值。

某些头部受应用程序设置的限制。 这些头部如下所列。 有关受限头部的更多信息,可以在 Chromium的头部工具 中找到。

  • Content-Length
  • Host
  • TrailerTe
  • Upgrade
  • Cookie2
  • Keep-Alive
  • Transfer-Encoding

此外,也不允许将 Connection 头部设置为 upgrade

request.getHeader(name)

  • name string - 指定一个额外的头名称.

返回 string - 以前设置的额外头部名称的值。

request.removeHeader(name)

  • name string - 指定一个额外的头名称.

移除先前设置的额外头部名称。 此方法只能在首次写入前调用。 尝试在第一次写入后调用将抛出一个错误。

request.write(chunk[, encoding][, callback])

  • chunk (string | Buffer) - 请求主体的数据块。 如果是字符串,则使用指定的编码将其转换为Buffer。
  • encoding string (可选) - 用于将字符串块转换为Buffer对象。 默认为“utf-8”。
  • callback Function (可选)-在写操作结束后调用。

callback 实质上是为了保持与 Node.js API 的相似性而引入的虚拟函数。 在将 chunk 内容传递到 Chromium 网络层之后, 在下一个 tick 中异步调用。 与 Node.js 实现相反, 不保证 chunk 内容在调用 callback 之前已经被刷新。

向请求正文中添加一个数据块。 第一次写操作可能导致在线路上发出请求头。 在第一次写入操作后, 不允许添加或删除自定义标头。

request.end([chunk][, encoding][, callback])

  • chunk (string | Buffer) (可选)
  • encoding string (可选)
  • callback Function (可选)

返回 this.

发送请求数据的剩下部分。 不允许进行后续的写入或结束操作。 finish 事件在结束操作后发出。

request.abort()

取消正在进行的 HTTP 事务。 如果请求已发出 close 事件, 则中止操作将不起作用。 否则正在进行的事件将发出 abortclose 事件。 此外, 如果有一个正在进行的响应对象, 它将发出 aborted 事件。

request.followRedirect()

继续任何待处理的重定向。 只能在 'redirect' 事件期间调用。

request.getUploadProgress()

返回 Object:

  • active boolean - 请求当前是否处于活动状态。 如果为 false,将不会设置其他属性。
  • started boolean - 上传是否已经开始。 如果值为false,currenttotal 将被设置为 0。
  • current Integer - 到目前为止已上传的字节数
  • total Integer - 本次请求总共要上传的字节数

您可以使用此方法获取使用 POST 请求的文件上传或其他数据传输的进度