類別：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 Function | 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 Function
  - response 物件
    - cancel 布林值 (可選)
    - redirectURL 字串 (可選) - 原始請求被阻止發送或完成，而是重新導向到給定的 URL。

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

uploadData 是 UploadData 物件的陣列。

callback 必須使用 response 物件呼叫。

有效 urls 的一些範例

'<all_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 Function | 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 Function
  - beforeSendResponse 物件
    - cancel 布林值 (可選)
    - requestHeaders Record<string, string | string[]> (可選) - 提供時，請求將使用這些標頭發出。

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

callback 必須使用 response 物件呼叫。

`webRequest.onSendHeaders([filter, ]listener)`

filter WebRequestFilter (可選)
listener Function | 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 Function | 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 Function
  - headersReceivedResponse 物件
    - cancel 布林值 (可選)
    - responseHeaders Record<string, string | string[]> (可選) - 提供時，伺服器會被假定已使用這些標頭回應。
    - statusLine 字串 (可選) - 應在覆寫 responseHeaders 以變更標頭狀態時提供，否則將使用原始回應標頭的狀態。

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

callback 必須使用 response 物件呼叫。

`webRequest.onResponseStarted([filter, ]listener)`

filter WebRequestFilter (可選)
listener Function | 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 Function | 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 Function | 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 Function | 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。