browser.webRequest

說明

使用 chrome.webRequest API 觀察及分析流量，並攔截、封鎖或修改傳輸中的要求。

權限

webRequest

您必須在擴充功能資訊清單中宣告 "webRequest" 權限，才能使用網頁要求 API，以及必要的主機權限。如要攔截子資源要求，擴充功能必須能存取要求的網址和發起端。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

webRequestBlocking

必須註冊封鎖事件處理常式。自 Manifest V3 起，這項功能僅適用於透過政策安裝的擴充功能。

webRequestAuthProvider

必須使用 onAuthRequired 方法。請參閱「處理驗證」。

概念和用途

要求的生命週期

網頁要求 API 定義了一組事件，這些事件會遵循網頁要求的生命週期。您可以使用這些事件來觀察及分析流量。某些同步事件可讓您攔截、封鎖或修改要求。

下圖說明成功要求的事件生命週期，後續則為事件定義：

從 webrequest API 的角度來看網頁要求的生命週期

onBeforeRequest (可選擇同步)
即將提出請求時觸發。這個事件會在建立任何 TCP 連線前傳送，可用於取消或重新導向要求。
onBeforeSendHeaders (可選擇同步)
在即將發出要求且初始標頭已準備就緒時觸發。這個事件旨在允許擴充功能新增、修改及刪除要求標頭 (*)。onBeforeSendHeaders 事件會傳遞給所有訂閱者，因此不同的訂閱者可能會嘗試修改要求；請參閱「實作詳細資料」一節，瞭解如何處理這項作業。這個事件可用於取消要求。
onSendHeaders
在所有擴充功能都有機會修改要求標頭後觸發，並顯示最終 (*) 版本。系統會在標頭傳送至網路前觸發事件。這項事件僅供參考，且會以非同步方式處理。但無法修改或取消要求。
onHeadersReceived (可選擇同步)
每次收到 HTTP(S) 回應標頭時觸發。由於重新導向和驗證要求，每個要求可能會發生多次。這個事件可讓擴充功能新增、修改及刪除回應標頭，例如傳入的 Content-Type 標頭。快取指令會在觸發這個事件前處理，因此修改 Cache-Control 等標頭不會影響瀏覽器的快取。此外，您也可以取消或重新導向要求。
onAuthRequired (可選擇同步)
當要求需要驗證使用者時，就會觸發這個事件。您可以同步處理這個事件，提供驗證憑證。請注意，擴充功能可能會提供無效的憑證。請注意，不要重複提供無效憑證，以免進入無限迴圈。這項功能也可用來取消要求。
onBeforeRedirect
在即將執行重新導向時觸發。重新導向可由 HTTP 回應代碼或擴充功能觸發。這類事件僅供參考，且會以非同步方式處理。您無法修改或取消要求。
onResponseStarted
收到回應主體的第一個位元組時觸發。如果是 HTTP 要求，這表示狀態行和回應標頭可用。這項事件僅供參考，且會以非同步方式處理。但無法修改或取消要求。
onCompleted
在要求處理成功時觸發。
onErrorOccurred
無法成功處理要求時觸發。

網頁要求 API 可保證，對於每個要求，系統都會觸發 onCompleted 或 onErrorOccurred 做為最終事件，但有一個例外狀況：如果要求重新導向至 data:// 網址，則 onBeforeRedirect 是最後回報的事件。

* 請注意，網頁要求 API 會向擴充功能提供網路堆疊的抽象概念。 在內部，一個網址要求可以分割成多個 HTTP 要求 (例如從大型檔案擷取個別位元組範圍)，也可以由網路堆疊處理，而不與網路通訊。因此，API 不會提供傳送至網路的最終 HTTP 標頭。舉例來說，擴充功能無法查看與快取相關的所有標頭。

目前不會向 onBeforeSendHeaders 事件提供下列標頭。這份清單不保證完整或穩定。

  • 授權
  • Cache-Control
  • 連線
  • Content-Length
  • 主機
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

自 Chrome 79 起，修改要求標頭會影響跨源資源共享 (CORS) 檢查。如果跨源要求的修改標頭不符合條件，系統會傳送 CORS 預檢，詢問伺服器是否可接受這類標頭。如果確實需要以違反 CORS 通訊協定的方式修改標頭，請在 opt_extraInfoSpec 中指定 'extraHeaders'。另一方面，修改回應標頭無法騙過 CORS 檢查。如要欺騙 CORS 通訊協定，您也必須為回應修改指定 'extraHeaders'。

自 Chrome 79 起，webRequest API 預設「不會」攔截 CORS 預檢要求和回應。如果要求網址的 opt_extraInfoSpec 中有指定 'extraHeaders' 的監聽器，擴充功能就會看到該要求網址的 CORS 預檢。onBeforeRequest 也可以從 Chrome 79 取得 'extraHeaders'。

從 Chrome 79 開始，系統「不會提供」下列要求標頭，且除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法修改或移除：

  • 來源

自 Chrome 72 起，如果您需要在跨源讀取封鎖 (CORB) 封鎖回應之前修改回應，則必須在 opt_extraInfoSpec 中指定 'extraHeaders'。

自 Chrome 72 起，系統「不會提供」下列要求標頭，且除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法修改或移除這些標頭：

  • Accept-Language
  • Accept-Encoding
  • 參照網址
  • Cookie

自 Chrome 72 起，系統「不會提供」Set-Cookie 回應標頭，且除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法修改或移除。

自 Chrome 89 起，除非在 opt_extraInfoSpec 中指定 'extraHeaders'，否則無法有效修改或移除 X-Frame-Options 回應標頭。

webRequest API 只會根據擴充功能的主機權限，公開擴充功能有權查看的要求。此外，只有下列配置可供存取：http://、https://、ftp://、file://、ws:// (Chrome 58 以上版本)、wss:// (Chrome 58 以上版本)、urn: (Chrome 91 以上版本) 或 chrome-extension://。此外，即使某些要求的網址使用上述其中一種配置，也會遭到隱藏。包括 chrome-extension://other_extension_id (其中 other_extension_id 不是處理要求的擴充功能 ID)、https://www.google.com/chrome，以及其他與瀏覽器核心功能相關的機密要求。此外，系統會對封鎖事件處理常式隱藏擴充功能中的同步 XMLHttpRequest，以免發生死結。請注意，對於某些支援的配置，由於對應通訊協定的性質，可用的事件集可能會受到限制。舉例來說，如果是檔案配置，則只能調度 onBeforeRequest、onResponseStarted、onCompleted 和 onErrorOccurred。

從 Chrome 58 開始，webRequest API 支援攔截 WebSocket 握手要求。由於交握是透過 HTTP 升級要求完成，因此其流程符合以 HTTP 為導向的 webRequest 模型。請注意，API 不會攔截：

  • 透過已建立的 WebSocket 連線傳送個別訊息。
  • WebSocket 正在關閉連線。

WebSocket 要求不支援重新導向。

自 Chrome 72 起，擴充功能必須同時具備要求網址和要求發起者的主機權限，才能攔截要求。

從 Chrome 96 開始，webRequest API 支援攔截透過 HTTP/3 握手要求的 WebTransport。由於交握是透過 HTTP CONNECT 要求完成，因此其流程符合以 HTTP 為導向的 webRequest 模型。請注意：

  • 工作階段建立後，擴充功能無法透過 webRequest API 觀察或介入工作階段。
  • 系統會忽略在 onBeforeSendHeaders 中修改 HTTP 要求標頭。
  • 透過 HTTP/3 傳輸的 WebTransport 不支援重新導向和驗證。

要求 ID

每個要求都有專屬 ID。這個 ID 在瀏覽器工作階段和擴充功能環境中是專屬的。在要求的生命週期內，這個 ID 會維持不變，可用於比對相同要求的事件。請注意，如果是 HTTP 重新導向或 HTTP 驗證，多個 HTTP 要求會對應至一個網頁要求。

註冊事件監聽器

如要為網頁要求註冊事件監聽器，請使用一般 addListener() 函式的變化版本。除了指定回呼函式外，您還必須指定篩選器引數，並可選擇指定額外資訊引數。

網頁要求 API 的 addListener() 有三個引數，定義如下：

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

以下是監聽 onBeforeRequest 事件的範例：

browser.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

每次呼叫 addListener() 時，都必須將回呼函式做為第一個參數。這個回呼函式會傳遞字典，其中包含目前網址要求的相關資訊。這本字典中的資訊取決於特定事件類型以及 opt_extraInfoSpec 的內容。

如果選用的 opt_extraInfoSpec 陣列包含 'blocking' 字串 (僅限特定事件)，回呼函式會同步處理。也就是說，在回呼函式傳回之前，要求會遭到封鎖。在這種情況下，回呼可以傳回 webRequest.BlockingResponse，決定要求的後續生命週期。視情況而定，這項回應可取消或重新導向要求 (onBeforeRequest)、取消要求或修改標頭 (onBeforeSendHeaders、onHeadersReceived)，以及取消要求或提供驗證憑證 (onAuthRequired)。

如果選用的 opt_extraInfoSpec 陣列改為包含 'asyncBlocking' 字串 (僅適用於 onAuthRequired)，擴充功能可以非同步產生 webRequest.BlockingResponse。

webRequest.RequestFilter filter 可讓您限制觸發事件的要求，限制維度包括：

網址
網址模式，例如 *://www.google.com/foo*bar。
類型
要求類型，例如 main_frame (為頂層框架載入的文件)、sub_frame (為內嵌框架載入的文件) 和 image (網站上的圖片)。詳情請參閱 webRequest.RequestFilter。
分頁 ID
分頁 ID。
視窗 ID
視窗的 ID。

視事件類型而定，您可以在 opt_extraInfoSpec 中指定字串，要求提供要求的其他資訊。只有在明確要求時，才會使用這個方法提供要求的詳細資料。

處理驗證

如要處理 HTTP 驗證要求，請在資訊清單檔案中加入 "webRequestAuthProvider" 權限：

{
  "permissions": [
    "webRequest",
    "webRequestAuthProvider"
  ]
}

請注意，如果政策安裝的擴充功能具有 "webRequestBlocking" 權限，則不需要這項權限。

如要同步提供憑證，請按照下列步驟操作：

browser.webRequest.onAuthRequired.addListener((details) => {
    return {
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    };
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['blocking']
);

如要以非同步方式提供憑證，請按照下列步驟操作：

browser.webRequest.onAuthRequired.addListener((details, callback) => {
    callback({
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    });
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['asyncBlocking']
);

實作詳情

開發使用 Web Request API 的擴充功能時，請務必瞭解幾項導入細節：

web_accessible_resources

如果擴充功能使用 webRequest API，將公開資源要求重新導向至無法透過網路存取的資源，系統會封鎖該要求並傳回錯誤。即使無法透過網路存取的資源是由重新導向擴充功能所擁有，上述情況仍適用。如要宣告與 declarativeWebRequest API 搭配使用的資源，請按照這裡的說明，在資訊清單中宣告並填入 "web_accessible_resources" 陣列。

衝突解決

在目前的網頁要求 API 實作中，如果至少有一個擴充功能指示取消要求，系統就會視為取消要求。如果擴充功能取消要求，所有擴充功能都會收到 onErrorOccurred 事件通知。一次只能有一個擴充功能重新導向要求或修改標頭。如果有多個擴充功能嘗試修改要求，系統會採用最近安裝的擴充功能，並忽略其他擴充功能。如果修改或重新導向指令遭到忽略，擴充功能不會收到通知。

快取

Chrome 採用兩種快取：磁碟快取和速度極快的記憶體內快取。記憶體內快取的生命週期與轉譯程序的生命週期相關，大致對應至分頁。Web Request API 無法偵測到從記憶體快取回應的要求。如果要求處理常式變更行為 (例如，根據要求封鎖的行為)，簡單的頁面重新整理可能不會遵循這項變更行為。為確保行為變更順利完成，請呼叫 handlerBehaviorChanged() 來清除記憶體內快取。但請勿經常執行，因為清除快取是非常耗費資源的操作。註冊或取消註冊事件監聽器後，您不需要呼叫 handlerBehaviorChanged()。

時間戳記

網頁要求事件的 timestamp 屬性只能保證內部一致。比較兩個事件可得出正確的時間差，但如果與擴充功能中的目前時間比較 (例如透過 (new Date()).getTime())，可能會產生非預期的結果。

錯誤處理

如果嘗試以無效的引數註冊事件，系統會擲回 JavaScript 錯誤，且不會註冊事件處理常式。如果處理事件時擲回錯誤，或事件處理常式傳回無效的封鎖回應，系統會將錯誤訊息記錄到擴充功能的控制台，並忽略該要求的處理常式。

範例

以下範例說明如何封鎖所有傳送至 www.evil.com 的要求：

browser.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

由於這個函式使用封鎖事件處理常式，因此需要在資訊清單檔案中加入 "webRequest" 和 "webRequestBlocking" 權限。

以下範例能以更有效率的方式達到相同目標，因為未指定 www.evil.com 的要求不需要傳遞至擴充功能：

browser.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

以下範例說明如何從所有要求中刪除 User-Agent 標頭：

browser.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

如要試用 browser.webRequest API，請從 chrome-extension-samples 存放區安裝 webRequest 範例。

類型

BlockingResponse

為已套用「blocking」extraInfoSpec 的事件處理常式傳回值。允許事件處理常式修改網路要求。

屬性

  • authCredentials

    物件 選填

    僅用於回應 onAuthRequired 事件。如果設定，系統會使用提供的憑證提出要求。

    • 密碼

      字串

    • 使用者名稱

      字串

  • 取消

    布林值 選填

    如果為 true，系統會取消要求。這會導致系統無法傳送要求。這可用於回應 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件。

  • redirectUrl

    字串 選填

    僅用於回應 onBeforeRequest 和 onHeadersReceived 事件。如果設定這項政策，系統會阻止傳送/完成原始要求，並改為重新導向至指定網址。允許重新導向至非 HTTP 配置，例如 data:。由重新導向動作啟動的重新導向會使用原始要求方法，但有一個例外：如果重新導向是在 onHeadersReceived 階段啟動，則會使用 GET 方法發出重新導向。系統會忽略從 ws:// 和 wss:// 配置網址重新導向。

  • requestHeaders

    HttpHeaders 選填

    僅用於回應 onBeforeSendHeaders 事件。如果設定，系統會改用這些要求標頭提出要求。

  • responseHeaders

    HttpHeaders 選填

    僅用於回應 onHeadersReceived 事件。如果設定，系統會假設伺服器改為使用這些回應標頭回應。只有在您確實想修改標頭，以限制衝突數量時，才傳回 responseHeaders (每個要求只能有一個擴充功能修改 responseHeaders)。

FormDataItem

Chrome 66 以上版本 瀏覽器 (自 Chrome 148 起)

包含表單資料中傳遞的資料。如果是網址編碼表單，當資料為 UTF-8 字串時，會儲存為字串，否則會儲存為 ArrayBuffer。如果是表單資料，則為 ArrayBuffer。如果表單資料代表上傳檔案，則為包含檔案名稱的字串 (如有提供檔案名稱)。

列舉

ArrayBuffer

字串

HttpHeaders

HTTP 標頭陣列。每個標頭都以字典表示，其中包含 name 鍵，以及 value 或 binaryValue。

類型

object[]

屬性

  • binaryValue

    number[] 選填

    如果 HTTP 標頭的值無法以 UTF-8 表示，則會儲存為個別位元組值 (0..255)。

  • 名稱

    字串

    HTTP 標頭的名稱。

  • 值

    字串 選填

    HTTP 標頭的值 (如果能以 UTF-8 表示)。

IgnoredActionType

Chrome 70 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"redirect"

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"responseHeaders"
指定事件應包含回應標頭。

"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。

"asyncBlocking"
指定以非同步方式處理回呼函式。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS)。

OnBeforeRedirectOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"responseHeaders"
指定事件應包含回應標頭。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS)。

OnBeforeRequestOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。

"requestBody"
指定事件應包含要求主體。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS)。

OnBeforeSendHeadersOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"requestHeaders"
指定事件應包含要求標頭。

"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。

OnCompletedOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"responseHeaders"
指定事件應包含回應標頭。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS)。

OnErrorOccurredOptions

Chrome 79 以上版本 Chrome 148 以上版本中的 browser.*

值

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"blocking"
指定在回呼函式傳回前，要求會遭到封鎖。

"responseHeaders"
指定事件應包含回應標頭。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS)。

"securityInfo"
指定事件應包含 SecurityInfo。

"securityInfoRawDer"
指定事件應包含含有憑證原始位元組的 SecurityInfo。

OnResponseStartedOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"responseHeaders"
指定事件應包含回應標頭。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS)。

OnSendHeadersOptions

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"requestHeaders"
指定事件應包含要求標頭。

"extraHeaders"
指定標頭可違反跨源資源共享 (CORS) 政策。

RequestFilter

描述要套用至 webRequest 事件的篩選條件物件。

屬性

  • tabId

    數字 選填

  • 類型

    ResourceType[] 選填

    要求類型清單。系統會篩除不符合任何類型的要求。

  • 網址

    string[]

    網址或網址模式清單。系統會篩除不符合任何網址的要求。

  • windowId

    數字 選填

ResourceType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"main_frame"
將資源指定為主頁框。

"sub_frame"
將資源指定為子框架。

"stylesheet"
將資源指定為樣式表。

"script"
將資源指定為指令碼。

"image"
將資源指定為圖片。

"font"
將資源指定為字型。

"object"
將資源指定為物件。

"xmlhttprequest"
將資源指定為 XMLHttpRequest。

"ping"
將資源指定為連線偵測 (ping)。

"csp_report"
將資源指定為內容安全政策 (CSP) 報表。

"media"
將資源指定為媒體物件。

"websocket"
將資源指定為 WebSocket。

"webbundle"
將資源指定為 WebBundle。

"other"
將資源指定為未列出的類型。

SecurityInfo

Chrome 144 以上版本 Chrome 148 以上版本支援 browser.*

屬性

  • 憑證

    object[]

    憑證清單

    • 指紋

      物件

      憑證的指紋。

      • sha256

        字串

        憑證的 sha256 指紋。

    • rawDER

      ArrayBuffer 選用

      DER 編碼伺服器憑證的原始位元組

  • 州

    字串

    連線狀態。安全、不安全、損毀。

UploadData

包含在網址要求中上傳的資料。

屬性

  • 位元組

    任意 選填

    含有資料副本的 ArrayBuffer。

  • 檔案

    字串 選填

    包含檔案路徑和名稱的字串。

屬性

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

每 10 分鐘持續間隔內，可呼叫 handlerBehaviorChanged 的次數上限。handlerBehaviorChanged 是耗費大量資源的函式呼叫，不應經常呼叫。

值

20

方法

handlerBehaviorChanged()

browser.webRequest.handlerBehaviorChanged(): Promise<void>

當 webRequest 處理常式的行為變更時，必須呼叫這個方法，以免因快取而導致處理不正確。這個函式呼叫的成本很高。請勿頻繁呼叫。

傳回

  • 承諾<void>

    Chrome 116 以上版本 Chrome 148 以上版本支援 browser.*

事件

onActionIgnored

Chrome 70 以上版本 瀏覽器。*自 Chrome 148 起 
browser.webRequest.onActionIgnored.addListener(
  callback: function,
)

當擴充功能對網路要求提出的修改建議遭到忽略時，就會觸發這個事件。如果與其他擴充功能發生衝突，就會發生這種情況。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • 已忽略的建議動作。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

onAuthRequired

browser.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

收到驗證失敗時觸發。監聽器有三個選項：提供驗證憑證、取消要求並顯示錯誤頁面，或不對驗證要求採取任何動作。如果提供的使用者憑證不正確，系統可能會針對同一要求多次呼叫這個方法。請注意，extraInfoSpec 參數只能指定 'blocking' 或 'asyncBlocking' 模式。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object, asyncCallback?: function) => BlockingResponse | undefined

    • 詳細資料

      物件

      • 挑戰者

        物件

        要求驗證的伺服器。

        • 主機

          字串

        • 通訊埠

          數字

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • isProxy

        布林值

        Proxy-Authenticate 為 True，WWW-Authenticate 為 False。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • 領域

        字串 選填

        伺服器提供的驗證領域 (如有)。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • responseHeaders

        HttpHeaders 選填

        與這項回應一併收到的 HTTP 回應標頭。

      • 架構

        字串

        驗證配置，例如 Basic 或 Digest。

      • statusCode

        數字

        Chrome 43 以上版本 瀏覽器。*自 Chrome 148 起

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • asyncCallback

      函式 選填

      Chrome 58 以上版本 瀏覽器 (自 Chrome 148 起)

      asyncCallback 參數如下： 

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | undefined

      如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] 選用

onBeforeRedirect

browser.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

伺服器即將啟動重新導向時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • fromCache

        布林值

        指出這項回應是否從磁碟快取擷取。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • ip

        字串 選填

        實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • redirectUrl

        字串

        新網址。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • responseHeaders

        HttpHeaders 選填

        與這個重新導向一併收到的 HTTP 回應標頭。

      • statusCode

        數字

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] 選用

onBeforeRequest

browser.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

即將提出要求時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => BlockingResponse | undefined

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • documentLifecycle

        extensionTypes.DocumentLifecycle 選用

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • frameType

        extensionTypes.FrameType 選用

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestBody

        物件 選填

        包含 HTTP 要求主體資料。只有在 extraInfoSpec 包含「requestBody」時才會提供。

        • 錯誤

          字串 選填

          取得要求主體資料時發生錯誤。

        • formData

          物件 選填

          如果要求方法是 POST，且主體是以 UTF8 編碼的鍵/值組合序列 (編碼為 multipart/form-data 或 application/x-www-form-urlencoded)，則會顯示這個字典，且每個鍵都會包含該鍵的所有值清單。如果資料屬於其他媒體類型，或格式不正確，則不會顯示字典。這個字典的值範例為 {'key': ['value1', 'value2']}。

        • raw

          UploadData[] 選用

          如果要求方法是 PUT 或 POST，且主體尚未在 formData 中剖析，則未剖析的要求主體元素會包含在這個陣列中。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • returns

      BlockingResponse | undefined

      如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] 選用

onBeforeSendHeaders

browser.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

在傳送 HTTP 要求前，一旦要求標頭可用，就會觸發。這可能發生在與伺服器建立 TCP 連線後，但尚未傳送任何 HTTP 資料前。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => BlockingResponse | undefined

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestHeaders

        HttpHeaders 選填

        要與這項要求一併傳送的 HTTP 要求標頭。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • returns

      BlockingResponse | undefined

      如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] 選用

onCompleted

browser.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

要求完成時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • fromCache

        布林值

        指出這項回應是否從磁碟快取擷取。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • ip

        字串 選填

        實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • responseHeaders

        HttpHeaders 選填

        與這項回應一併收到的 HTTP 回應標頭。

      • statusCode

        數字

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] 選用

onErrorOccurred

browser.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

發生錯誤時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。如果要求是導覽頁框，則不會顯示這個值。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • 錯誤

        字串

        錯誤說明。我們不保證這個字串在不同版本之間能維持回溯相容性。請勿剖析內容並據此採取行動。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • fromCache

        布林值

        指出這項回應是否從磁碟快取擷取。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • ip

        字串 選填

        實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] 選用

onHeadersReceived

browser.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

收到要求的 HTTP 回應標頭時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => BlockingResponse | undefined

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • responseHeaders

        HttpHeaders 選填

        與這項回應一併收到的 HTTP 回應標頭。

      • securityInfo

        SecurityInfo 選填

        Chrome 144 以上版本 Chrome 148 以上版本支援 browser.*

        基礎連線所用 TLS/QUIC 連線的相關資訊。只有在 extraInfoSpec 參數中指定 securityInfo 時，系統才會提供這項資訊。

      • statusCode

        數字

        Chrome 43 以上版本 瀏覽器。*自 Chrome 148 起

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

    • returns

      BlockingResponse | undefined

      如果在「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回這種類型的物件。

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] 選用

onResponseStarted

browser.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

收到回應主體的第一個位元組時觸發。如果是 HTTP 要求，這表示狀態行和回應標頭可用。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • fromCache

        布林值

        指出這項回應是否從磁碟快取擷取。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • ip

        字串 選填

        實際接收要求的伺服器 IP 位址。請注意，這可能是 IPv6 位址。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • responseHeaders

        HttpHeaders 選填

        與這項回應一併收到的 HTTP 回應標頭。

      • statusCode

        數字

        伺服器傳回的標準 HTTP 狀態碼。

      • statusLine

        字串

        回應的 HTTP 狀態行，或 HTTP/0.9 回應 (即缺少狀態行的回應) 的「HTTP/0.9 200 OK」字串，如果沒有標頭，則為空字串。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] 選用

onSendHeaders

browser.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

在要求傳送至伺服器前觸發 (在 onSendHeaders 觸發時，可看到先前 onBeforeSendHeaders 回呼的修改)。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        提出要求的文件 UUID。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        文件所處的生命週期。

      • frameId

        數字

        值為 0 表示要求發生在主頁框中；正值表示要求發生在子頁框中，且值為子頁框的 ID。如果載入 (子) 框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出這個框架的 ID，而非外部框架的 ID。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本 Chrome 148 起為 browser.*

        發生要求的頁框類型。

      • initiator

        字串 選填

        Chrome 63 以上版本 Chrome 148 以上版本的瀏覽器

        發出要求的來源。這項設定不會因重新導向而變更。如果是不透明來源，則會使用「null」字串。

      • 方法

        字串

        標準 HTTP 方法。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本 Chrome 148 起為 browser.*

        擁有這個頁框的上層文件 UUID。如果沒有父項，則不會設定。

      • parentFrameId

        數字

        包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

      • requestHeaders

        HttpHeaders 選填

        與這項要求一併傳送的 HTTP 要求標頭。

      • requestId

        字串

        要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。因此，這些 ID 可用於連結同一要求的不同事件。

      • tabId

        數字

        要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

      • timeStamp

        數字

        觸發這個信號的時間，以 Epoch 時間起算的毫秒數表示。

      • 類型

        ResourceType

        要求資源的使用方式。

      • 網址

        字串

  • 篩選器

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] 選用