類別：WebRequest

類別：WebRequest

在請求的生命週期的各個階段攔截和修改請求的內容。

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

WebRequest 類別的實例是透過使用 Session 的 webRequest 屬性來存取的。

WebRequest 的方法接受一個可選的 filter 和一個 listener。當 API 的事件發生時，將使用 listener(details) 呼叫 listener。details 物件描述了該請求。

⚠️ 只會使用最後附加的 listener。將 null 作為 listener 傳遞將會取消訂閱該事件。

filter 物件具有 urls 屬性，該屬性是一個 URL 模式陣列，它將用於篩選出不符合 URL 模式的請求。如果省略 filter，則所有請求都將被匹配。

對於某些事件，listener 會連同 callback 一起傳遞，當 listener 完成其工作時，應使用 response 物件呼叫該 callback。

一個為請求添加 User-Agent 標頭的範例

const { session } = require('electron')

// Modify the user agent for all requests to the following urls.
const filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io/*']
}

session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({ requestHeaders: details.requestHeaders })
})

實例方法

以下方法在 WebRequest 的實例上可用

webRequest.onBeforeRequest([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • uploadData UploadData[]
  • callback 函式
    • response 物件
      • cancel 布林值（可選）
      • redirectURL 字串（可選） - 原始請求將被阻止發送或完成，而是重新導向到給定的 URL。

當即將發生請求時，將使用 listener(details, callback) 呼叫 listener。

uploadData 是一個 UploadData 物件的陣列。

必須使用 response 物件呼叫 callback。

一些有效的 urls 範例

'http://foo:1234/'
'http://foo.com/'
'http://foo:1234/bar'
'*://*/*'
'*://example.com/*'
'*://example.com/foo/*'
'http://*.foo:1234/'
'file://foo:1234/bar'
'http://foo:*/'
'*://www.foo.com/'

webRequest.onBeforeSendHeaders([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • uploadData UploadData[]（可選）
    • requestHeaders Record<string, string>
  • callback 函式
    • beforeSendResponse 物件
      • cancel 布林值（可選）
      • requestHeaders Record<string, string | string[]>（可選） - 如果提供，則將使用這些標頭發出請求。

在發送 HTTP 請求之前，一旦請求標頭可用，將使用 listener(details, callback) 呼叫 listener。這可能發生在與伺服器建立 TCP 連線之後，但在發送任何 http 資料之前。

必須使用 response 物件呼叫 callback。

webRequest.onSendHeaders([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • requestHeaders Record<string, string>

在即將向伺服器發送請求之前，將使用 listener(details) 呼叫 listener，此時先前 onBeforeSendHeaders 回應的修改是可見的。

webRequest.onHeadersReceived([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • statusLine 字串
    • statusCode 整數
    • responseHeaders Record<string, string[]>（可選）
  • callback 函式
    • headersReceivedResponse 物件
      • cancel 布林值（可選）
      • responseHeaders Record<string, string | string[]>（可選） - 如果提供，則假設伺服器已使用這些標頭回覆。
      • statusLine 字串（可選） - 應在覆蓋 responseHeaders 以變更標頭狀態時提供，否則將使用原始回應標頭的狀態。

當接收到請求的 HTTP 回應標頭時，將使用 listener(details, callback) 呼叫 listener。

必須使用 response 物件呼叫 callback。

webRequest.onResponseStarted([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • responseHeaders Record<string, string[]>（可選）
    • fromCache 布林值 - 指示回應是否從磁碟快取中擷取。
    • statusCode 整數
    • statusLine 字串

當接收到回應主體的第一個位元組時，將使用 listener(details) 呼叫 listener。對於 HTTP 請求，這表示狀態行和回應標頭可用。

webRequest.onBeforeRedirect([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • redirectURL 字串
    • statusCode 整數
    • statusLine 字串
    • ip 字串（可選） - 請求實際傳送到的伺服器 IP 位址。
    • fromCache 布林值
    • responseHeaders Record<string, string[]>（可選）

當即將發生伺服器啟動的重新導向時，將使用 listener(details) 呼叫 listener。

webRequest.onCompleted([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • responseHeaders Record<string, string[]>（可選）
    • fromCache 布林值
    • statusCode 整數
    • statusLine 字串
    • error 字串

當請求完成時，將使用 listener(details) 呼叫 listener。

webRequest.onErrorOccurred([filter, ]listener)

• filter WebRequestFilter（可選）
• listener 函式 | null
  • details 物件
    • id 整數
    • url 字串
    • method 字串
    • webContentsId 整數（可選）
    • webContents WebContents（可選）
    • frame WebFrameMain | null（可選） - 請求框架。如果在框架導航或被銷毀後存取，則可能為 null。
    • resourceType 字串 - 可以是 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other。
    • referrer 字串
    • timestamp 雙精度浮點數
    • fromCache 布林值
    • error 字串 - 錯誤描述。

當發生錯誤時，將使用 listener(details) 呼叫 listener。