跳转至

客户端请求

类：ClientRequest

发起 HTTP/HTTPS 请求。

进程：主进程, Utility 进程
此类未从 'electron' 模块导出。它仅可作为 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[]>（可选）- 随请求发送的标头。
  • session Session（可选）- 与该请求关联的 Session 实例。
  • partition string（可选）- 与该请求关联的 partition 名称。默认为空字符串。session 选项优先于 partition。因此，如果显式指定了 session，则忽略 partition。
  • bypassCustomProtocolHandlers boolean（可选）- 设置为 true 时，不会调用为请求 URL 方案注册的自定义协议处理程序。这允许将拦截的请求转发到内置处理程序。绕过自定义协议时，webRequest 处理程序仍会被触发。默认为 false。
  • credentials string（可选）- 可以是 include、omit 或 same-origin。是否随此请求发送 credentials。如果设置为 include，将使用与该请求关联的会话中的凭据。如果设置为 omit，不会随请求发送凭据（发生 401 时也不会触发 'login' 事件）。如果设置为 same-origin，还必须指定 origin。这与同名 fetch 选项的行为一致。如果未指定此选项，将发送会话中的身份验证数据，并且不会发送 cookies（除非设置了 useSessionCookies）。
  • useSessionCookies boolean（可选）- 是否随此请求发送所提供会话中的 cookies。如果指定了 credentials，此选项无效。默认为 false。
  • protocol string（可选）- 可以是 http: 或 https:。以 'scheme:' 形式表示的协议方案。默认为 'http:'。
  • host string（可选）- 以主机名和端口号拼接形式 'hostname:port' 提供的服务器主机。
  • hostname string（可选）- 服务器主机名。
  • port Integer（可选）- 服务器监听端口号。
  • path string（可选）- 请求 URL 的路径部分。
  • redirect string（可选）- 可以是 follow、error 或 manual。此请求的重定向模式。当模式为 error 时，任何重定向都会中止。当模式为 manual 时，除非在 redirect 事件期间同步调用 request.followRedirect，否则重定向将被取消。默认为 follow。
  • origin string（可选）- 请求的源 URL。
  • referrerPolicy string（可选）- 可以是 ""、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 string（可选）- 可以是 default、no-store、reload、no-cache、force-cache 或 only-if-cached。
  • priority string（可选）- 可以是 throttled、idle、lowest、low、medium 或 highest。默认为 idle。
  • priorityIncremental boolean（可选）- 作为 HTTP 可扩展优先级（RFC 9218）一部分的增量加载标志。默认为 true。

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'

返回值：

事件：'login'

返回值：

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

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

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

  • username string
  • password string

```js @ts-type={request:Electron.ClientRequest} request.on('login', (authInfo, callback) => { callback('username', 'password') }) 

提供空凭据将取消请求，并在响应对象上报告身份验证错误：

```js @ts-type={request:Electron.ClientRequest}
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 Error - 提供有关故障的一些信息的错误对象。

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

事件：'close'

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

事件：'redirect'

返回值：

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

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

实例属性

request.chunkedEncoding

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

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

实例方法

request.setHeader(name, value)

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

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

某些标头被限制由应用设置。这些标头列于下方。有关受限标头的更多信息，请参阅 Chromium 的标头工具。

  • Content-Length
  • Host
  • Trailer 或 Te
  • 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 实现不同，不保证在调用 callback 之前 chunk 内容已刷新到网络上。

向请求体添加一块数据。首次写入操作可能会导致请求标头被发送到网络上。首次写入操作之后，不允许添加或移除自定义标头。

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

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

返回 this。

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

request.abort()

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

request.followRedirect()

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

request.getUploadProgress()

返回 Object：

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

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron