跳转到主要内容

类：ClientRequest

类: ClientRequest​

发起 HTTP/HTTPS 请求。

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

ClientRequest 实现了 可写流 接口，因此是一个 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。是否随此请求发送 凭据。如果设置为 include，将使用与请求关联的会话中的凭据。如果设置为 omit，则不会随请求发送凭据（并且在发生 401 时不会触发 'login' 事件）。如果设置为 same-origin，则必须也指定 origin。这与同名的 fetch 选项的行为相匹配。如果未指定此选项，将发送会话中的身份验证数据，并且除非设置了 useSessionCookies，否则不会发送 cookie。
    • useSessionCookies boolean (可选) - 是否从提供的会话发送 cookie。如果指定了 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 严格遵循 Node.js 模型，如 URL 模块中所述。

例如，我们可以使用以下方式创建到 '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 的最后一个数据块写入 request 对象后发出。

事件: 'abort'​

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

事件: 'error'​

返回

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

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

事件: 'close'​

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

事件: 'redirect'​

返回

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

当服务器返回重定向响应（例如 301 永久移动）时发出。调用 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。

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

request.abort()​

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

request.followRedirect()​

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

request.getUploadProgress()​

返回 Object

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

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