跳至主要內容

類別：ClientRequest

類別：ClientRequest​

發出 HTTP/HTTPS 請求。

進程：主，工具
此類別並未從 'electron' 模組匯出。它僅作為 Electron API 中其他方法的傳回值提供。

ClientRequest 實作 Writable Stream 介面，因此是一個 EventEmitter。

new ClientRequest(options)​

  • options (物件 | 字串) - 如果 options 是字串，它會被解讀為請求 URL。如果它是一個物件，它應該透過以下屬性完全指定 HTTP 請求
    • method 字串 (選用) - HTTP 請求方法。預設為 GET 方法。
    • url 字串 (選用) - 請求 URL。必須以絕對形式提供，並將協定方案指定為 http 或 https。
    • headers Record<string, string | string[]> (選用) - 要與請求一起傳送的標頭。
    • session 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'​

傳回

事件：'login'​

傳回

  • authInfo 物件
    • isProxy 布林值
    • scheme 字串
    • host 字串
    • port 整數
    • realm 字串
  • callback 函式
    • username 字串 (選用)
    • password 字串 (選用)

當驗證 Proxy 要求使用者憑證時發出。

預期會使用使用者憑證來呼叫 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 Moved Permanently) 時發出。呼叫 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
  • 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 網路層後，它會在下一個刻度以非同步方式呼叫。與 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 boolean - 請求目前是否處於活動狀態。如果此值為 false，則不會設定其他屬性
  • started boolean - 是否已開始上傳。如果此值為 false，則 current 和 total 都將設定為 0。
  • current Integer - 到目前為止已上傳的位元組數
  • total Integer - 此請求將上傳的位元組數

您可以將此方法與 POST 請求結合使用，以取得檔案上傳或其他資料傳輸的進度。