webRequest

為 HTTP 請求的各個階段新增事件監聽器，包括 ws:// 和 wss:// 上的 WebSocket 請求。事件監聽器會接收有關請求的詳細資訊，並可以修改或取消請求。

每個事件在請求的特定階段觸發。事件順序如下：

Order of requests is onBeforeRequest, onBeforeSendHeader, onSendHeaders, onHeadersReceived, onResponseStarted, and onCompleted. The onHeadersReceived can cause an onBeforeRedirect and an onAuthRequired. Events caused by onHeadersReceived start at the beginning onBeforeRequest. Events caused by onAuthRequired start at onBeforeSendHeader.

但是，擴充套件程式並非一定會觀察到所有這些事件。例如，當重定向目標不匹配事件 filter.urls 時，onBeforeRedirect 可能不會緊接著 onBeforeRequest 觸發。這可能是因為過濾器中的 URL 定義得很窄，或者擴充套件程式無法觀察到重定向目標，例如當它重定向到 data: URL 時。

onErrorOccurred 可以在請求期間的任何時間觸發。另外請注意，事件順序有時可能與此不同。例如，在 Firefox 中，對於 HSTS 升級，onBeforeRedirect 事件會在 onBeforeRequest 之後立即觸發。如果 Firefox 跟蹤保護阻止了某個請求，也會觸發 onErrorOccurred。

所有事件——除了 onErrorOccurred——都可以接受三個引數給 addListener()：

監聽器本身
一個 filter 物件，因此您只能接收到特定 URL 或特定型別資源的請求通知。
一個可選的 extraInfoSpec 物件。您可以使用它來傳遞其他事件特定的指令。

監聽器函式會接收一個包含請求資訊的 details 物件。其中包括一個請求 ID，該 ID 用於使附加元件能夠關聯與單個請求相關的事件。它在瀏覽器會話和附加元件的上下文中是唯一的。在整個請求過程中，即使在重定向和身份驗證交換過程中，它也會保持不變。

要為給定主機使用 webRequest API，擴充套件程式必須具有 "webRequest" API 許可權以及該主機的主機許可權。要使用 "blocking" 功能，擴充套件程式還必須擁有 "webRequestBlocking" API 許可權。

要攔截由頁面載入的資源（如影像、指令碼或樣式表），擴充套件程式必須同時擁有該資源的許可權以及請求該資源的主頁面的主機許可權。例如，如果一個位於 https://mdn.club.tw 的頁面從 https://mdn.mozillademos.org 載入影像，那麼擴充套件程式必須同時擁有這兩個主機許可權才能攔截影像請求。

修改請求

在某些事件中，您可以修改請求。具體來說，您可以：

在以下情況下取消請求：
在以下情況下重定向請求：
- onBeforeRequest
- onHeadersReceived
在以下情況下修改請求頭：
- onBeforeSendHeaders
在以下情況下修改響應頭：
- onHeadersReceived
在以下情況下提供身份驗證憑據：
- onAuthRequired

要執行此操作，您需要向事件的 addListener() 的 extraInfoSpec 引數中傳遞一個值為 "blocking" 的選項。這將使監聽器變為同步。

在監聽器中，您可以返回一個 BlockingResponse 物件，該物件指示您需要進行的修改：例如，您想要傳送的已修改的請求頭。

webRequest.BlockingResponse: 當事件監聽器在其 extraInfoSpec 引數中設定了 "blocking" 時，會返回此型別的物件。透過在 BlockingResponse 中設定特定屬性，監聽器可以修改網路請求。
webRequest.CertificateInfo: 描述單個 X.509 證書的物件。
webRequest.HttpHeaders: HTTP 頭的陣列。每個頭表示為一個物件，具有兩個屬性：name 和 value 或 binaryValue。
webRequest.RequestFilter: 描述應用於 webRequest 事件的過濾器的物件。
webRequest.ResourceType: 表示 Web 請求中獲取的特定型別的資源。
webRequest.SecurityInfo: 描述特定 Web 請求安全屬性的物件。
webRequest.StreamFilter: 一個用於在接收 HTTP 響應時進行監視和修改的物件。
webRequest.UploadData: 包含 URL 請求中上傳的資料。

屬性

webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES: 在 10 分鐘內可以呼叫 handlerBehaviorChanged() 的最大次數。

方法

webRequest.handlerBehaviorChanged(): 此方法可用於確保在頁面位於瀏覽器記憶體快取中時正確應用事件監聽器。
webRequest.filterResponseData(): 返回給定請求的 webRequest.StreamFilter 物件。
webRequest.getSecurityInfo(): 獲取與給定請求關聯的 TLS 連線的詳細資訊。

事件

webRequest.onBeforeRequest: 當請求即將發起，並且在頭可用之前觸發。如果您想取消或重定向請求，這是一個很好的監聽時機。
webRequest.onBeforeSendHeaders: 在傳送任何 HTTP 資料之前，但在 HTTP 頭可用之後觸發。如果您想修改 HTTP 請求頭，這是一個很好的監聽時機。
webRequest.onSendHeaders: 在傳送頭之前觸發。如果在 onBeforeSendHeaders 中修改了頭，您在這裡會看到修改後的版本。
webRequest.onHeadersReceived: 當請求的 HTTP 響應頭接收到時觸發。您可以使用此事件來修改 HTTP 響應頭。
webRequest.onAuthRequired: 當伺服器要求客戶端提供身份驗證憑據時觸發。監聽器可以什麼都不做，取消請求，或提供身份驗證憑據。
webRequest.onResponseStarted: 當接收到響應體的第一個位元組時觸發。對於 HTTP 請求，這意味著狀態行和響應頭都可用。
webRequest.onBeforeRedirect: 當伺服器發起的重定向即將發生時觸發。
webRequest.onCompleted: 請求完成時觸發。
webRequest.onErrorOccurred: 發生錯誤時觸發。