类: ClientRequest

执行 HTTP/HTTPS 请求。

进程: 主进程, 实用程序进程
此类未从 'electron' 模块导出。它仅作为 Electron API 中其他方法的返回值提供。

ClientRequest 实现了可写流接口，因此是一个事件发射器。

`new ClientRequest(options)`

options (对象 | 字符串) - 如果 options 是字符串，则将其解释为请求 URL。如果它是对象，则预期通过以下属性完全指定 HTTP 请求
- method 字符串 (可选) - HTTP 请求方法。默认为 GET 方法。
- url 字符串 (可选) - 请求 URL。必须以绝对形式提供，并指定 http 或 https 协议方案。
- headers Record<string, string | string[]> (可选) - 要与请求一起发送的标头。
- session 会话 (可选) - 与请求关联的 Session 实例。
- partition 字符串 (可选) - 与请求关联的 partition 的名称。默认为空字符串。session 选项优先于 partition。因此，如果显式指定了 session，则会忽略 partition。
- credentials 字符串 (可选) - 可以是 include、omit 或 same-origin。是否向此请求发送凭据。如果设置为 include，则将使用与请求关联的会话中的凭据。如果设置为 omit，则不会将凭据与请求一起发送（并且在发生 401 的情况下不会触发 'login' 事件）。如果设置为 same-origin，则还必须指定 origin。这与同名 fetch 选项的行为匹配。如果未指定此选项，则将发送会话中的身份验证数据，并且不会发送 cookie（除非设置了 useSessionCookies）。
- useSessionCookies 布尔值 (可选) - 是否从提供的会话向此请求发送 cookie。如果指定了 credentials，则此选项无效。默认为 false。
- protocol 字符串 (可选) - 可以是 http: 或 https:。以 'scheme:' 形式表示的协议方案。默认为 'http:'。
- host 字符串 (可选) - 作为主机名和端口号 'hostname 的串联提供的服务器主机:port'.
- hostname 字符串 (可选) - 服务器主机名。
- port 整数 (可选) - 服务器的侦听端口号。
- path 字符串 (可选) - 请求 URL 的路径部分。
- redirect 字符串 (可选) - 可以是 follow、error 或 manual。此请求的重定向模式。当模式为 error 时，将中止任何重定向。当模式为 manual 时，除非在 redirect 事件期间同步调用 request.followRedirect，否则重定向将被取消。默认为 follow。
- origin 字符串 (可选) - 请求的源 URL。
- referrerPolicy 字符串 (可选) - 可以是 ""、no-referrer、no-referrer-when-downgrade、origin、origin-when-cross-origin、unsafe-url、same-origin、strict-origin 或 strict-origin-when-cross-origin。默认为 strict-origin-when-cross-origin。
- cache 字符串 (可选) - 可以是 default、no-store、reload、no-cache、force-cache 或 only-if-cached。

options 属性（如 protocol、host、hostname、port 和 path）严格遵循 URL 模块中描述的 Node.js 模型。

例如，我们可以创建与 'github.com' 相同的请求，如下所示

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

实例事件

事件: 'response'

response IncomingMessage - 表示 HTTP 响应消息的对象。

authInfo 对象
- isProxy 布尔值
- scheme 字符串
- host 字符串
- port 整数
- realm 字符串
callback 函数
- username 字符串 (可选)
- password 字符串 (可选)

当进行身份验证的代理请求用户凭据时发出。

预期 callback 函数将使用用户凭据回调

username 字符串
password 字符串

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 的最后一个数据块写入 request 对象之后发出。

事件: 'abort'

当 request 被中止时发出。如果 request 已经关闭，则不会触发 abort 事件。

事件: 'error'

error 错误 - 提供有关失败的一些信息的错误对象。

当 net 模块无法发出网络请求时发出。通常，当 request 对象发出 error 事件时，随后会紧随一个 close 事件，并且不会提供响应对象。

事件: 'close'

在 HTTP 请求响应事务中作为最后一个事件发出。close 事件表示 request 或 response 对象上不会再发出任何事件。

事件: 'redirect'

statusCode 整数
method 字符串
redirectUrl 字符串
responseHeaders Record<string, string[]>

当服务器返回重定向响应（例如 301 已永久移动）时发出。调用 request.followRedirect 将继续进行重定向。如果处理了此事件，则必须同步调用 request.followRedirect，否则请求将被取消。

实例属性

`request.chunkedEncoding`

一个 boolean，指定请求是否使用 HTTP 分块传输编码。默认为 false。该属性可读写，但只能在第一次写入操作之前设置，因为 HTTP 标头尚未放在电线上。尝试在第一次写入之后设置 chunkedEncoding 属性将抛出错误。

如果需要发送大型请求主体，强烈建议使用分块编码，因为数据将以小块的形式流式传输，而不是在 Electron 进程内存中进行内部缓冲。

实例方法

`request.setHeader(name, value)`

name 字符串 - 额外的 HTTP 标头名称。
value 字符串 - 额外的 HTTP 标头值。

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

应用程序限制了某些标头，不允许设置。这些标头列在下面。有关受限标头的更多信息，请参阅 Chromium 的标头实用程序。

Content-Length
Host
Trailer 或 Te
升级
Cookie2
保持活动
传输编码

此外，将 Connection 头设置为 upgrade 值也是不允许的。

`request.getHeader(name)`

name 字符串 - 指定额外的头名称。

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

`request.removeHeader(name)`

name 字符串 - 指定额外的头名称。

删除之前设置的额外头名称。此方法只能在第一次写入之前调用。尝试在第一次写入之后调用它会导致错误。

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

chunk (字符串 | 缓冲区) - 请求主体数据的块。如果它是一个字符串，它将使用指定的编码转换为缓冲区。
encoding 字符串 (可选) - 用于将字符串块转换为缓冲区对象。默认为 'utf-8'。
callback 函数 (可选) - 在写入操作结束时调用。

callback 本质上是为保持与 Node.js API 的一致性而引入的虚拟函数。它在 chunk 内容传递给 Chromium 网络层后的下一个刻度中异步调用。与 Node.js 实现相反，它不能保证 chunk 内容在调用 callback 之前已在网络上刷新。

将数据块添加到请求主体。第一次写入操作可能会导致请求头在网络上发出。在第一次写入操作之后，不允许添加或删除自定义头。

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

chunk (字符串 | 缓冲区) (可选)
encoding 字符串 (可选)
callback 函数 (可选)

返回值 this。

发送请求数据的最后一个块。后续写入或结束操作将不被允许。finish 事件将在结束操作之后立即发出。

`request.abort()`

取消正在进行的 HTTP 事务。如果请求已经发出 close 事件，则中止操作将没有影响。否则正在进行的事件将发出 abort 和 close 事件。此外，如果存在正在进行的响应对象，它将发出 aborted 事件。

`request.followRedirect()`

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

`request.getUploadProgress()`

返回值 Object

active 布尔值 - 请求当前是否处于活动状态。如果为 false，则不会设置其他属性
started 布尔值 - 上传是否已开始。如果为 false，则 current 和 total 都将设置为 0。
current 整数 - 到目前为止已上传的字节数
total 整数 - 将要上传到此请求的字节数

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