說明
使用 chrome.webRequest API 觀察及分析流量，以及攔截、封鎖或修改傳輸中的要求。
權限
webRequest您必須在擴充功能資訊清單中宣告 "webRequest" 權限，才能使用網路要求 API 和必要的主機權限。如要攔截子資源要求，該擴充功能必須同時存取要求的網址及其啟動者。例如：
{
"name": "My extension",
...
"permissions": [
"webRequest"
],
"host_permissions": [
"*://*.google.com/*"
],
...
}
webRequestBlocking
必須註冊封鎖事件處理常式。自 Manifest V3 起，這項功能僅適用於政策已安裝的擴充功能。
webRequestAuthProvider
必須啟用才能使用 onAuthRequired 方法。請參閱處理驗證。
概念和用法
要求的生命週期
Web 要求 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
- 主機
- 如果修改自修訂
- 如果-無相符結果
- 如果範圍
- 部分資料
- 普拉格馬文
- Proxy 授權
- Proxy 連線
- 傳輸編碼
自 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'，否則無法修改或移除要求標頭：
- 接受語言
- 接受編碼
- 參照網址
- 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 不是處理要求、https://www.google.com/chrome，以及其他對瀏覽器功能核心敏感要求核心的擴充功能 ID。此外，也會隱藏擴充功能中的同步 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 在瀏覽器工作階段和擴充功能的情境中是不重複的。在要求的生命週期中，變數會保持不變，且可用來比對相同要求的事件。請注意，在 HTTP 重新導向或 HTTP 驗證的情況下，多個 HTTP 要求會對應至一個網路要求。
註冊事件監聽器
如要為網路要求註冊事件監聽器，請使用一般 addListener() 函式的變化版本。除了指定回呼函式之外，您還必須指定篩選器引數，並指定選用的額外資訊引數。
網路要求 API addListener() 的三個引數如下：
var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];
以下為監聽 onBeforeRequest 事件的範例：
chrome.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" 權限的政策擴充功能不需要此權限。
如要同步提供憑證，請按照下列步驟操作：
chrome.webRequest.onAuthRequired.addListener((details) => {
return {
authCredentials: {
username: 'guest',
password: 'guest'
}
};
},
{ urls: ['https://httpbin.org/basic-auth/guest/guest'] },
['blocking']
);
如要以非同步的方式提供憑證，請按照下列步驟操作：
chrome.webRequest.onAuthRequired.addListener((details, callback) => {
callback({
authCredentials: {
username: 'guest',
password: 'guest'
}
});
},
{ urls: ['https://httpbin.org/basic-auth/guest/guest'] },
['asyncBlocking']
);
實作詳情
開發使用網路要求 API 的擴充功能時，請務必瞭解以下幾個實作細節：
web_accessible_resources
當擴充功能使用 webRequest API 將公開資源要求重新導向至不可透過網路存取的資源時，該擴充功能會遭到封鎖，且會導致錯誤發生。即使擁有重新導向的擴充功能擁有無法存取網路的資源，上述方法也依然有效。如要宣告與宣告式 WebRequest API 搭配使用的資源，您必須宣告 "web_accessible_resources" 陣列並填入資訊清單中，如這裡所述。
衝突解決
在目前的網路要求 API 實作中，如果至少有一項擴充功能要求取消要求，系統就會將要求視為取消。如果擴充功能取消要求，所有擴充功能都會收到 onErrorOccurred 事件通知。一次只能透過一個擴充功能重新導向要求或修改標頭。如有多個擴充功能嘗試修改要求，系統會優先安裝最新安裝的擴充功能，並忽略所有其他擴充功能。如果擴充功能對修改或重新導向的指示遭到忽略，擴充功能就不會收到通知。
快取
Chrome 使用兩種快取：磁碟快取和非常快速的記憶體內快取。記憶體內快取的生命週期會附加至轉譯程序的生命週期，大致會對應分頁標籤。網路要求 API 不會顯示從記憶體內快取回應的要求。如果要求處理常式變更了其行為 (例如根據要求封鎖的行為)，簡單的頁面重新整理可能無法遵循這個變更行為。為確保行為變更順利完成，請呼叫 handlerBehaviorChanged() 來清除記憶體內的快取。但請勿頻繁這麼做；清除快取是一項非常昂貴的作業。註冊或取消註冊事件監聽器後，不必呼叫 handlerBehaviorChanged()。
時間戳記
網路要求事件的 timestamp 屬性只保證內部保持一致。比較一個事件與其他事件後，您就能取得這些事件之間的正確偏移值，但如果將該事件與擴充功能中的目前時間 (例如透過 (new Date()).getTime()) 比較，可能會產生非預期的結果。
處理錯誤
如果嘗試註冊的事件含有無效引數，系統會擲回 JavaScript 錯誤，且不會註冊事件處理常式。如果在處理事件時擲回錯誤，或是事件處理常式傳回無效封鎖回應，則系統會將錯誤訊息記錄在擴充功能的主控台中，並忽略該要求的處理常式。
示例
以下範例說明如何封鎖所有對 www.evil.com 的要求：
chrome.webRequest.onBeforeRequest.addListener(
function(details) {
return {cancel: details.url.indexOf("://www.evil.com/") != -1};
},
{urls: ["<all_urls>"]},
["blocking"]
);
這個函式使用了封鎖事件處理常式，因此需要 "webRequest" 以及資訊清單檔案中的 "webRequestBlocking" 權限。
下列範例可更有效率地達成相同目標，因為非以 www.evil.com 為目標的要求不需要傳遞至擴充功能：
chrome.webRequest.onBeforeRequest.addListener(
function(details) { return {cancel: true}; },
{urls: ["*://www.evil.com/*"]},
["blocking"]
);
以下範例說明如何刪除所有要求中的 User-Agent 標頭：
chrome.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"]
);
如要試用 chrome.webRequest API，請從 chrome-extension-samples 存放區安裝 webRequest 範例。
類型
BlockingResponse
針對已套用「blocking」 extraInfoSpec 的事件處理常式傳回值。允許事件處理常式修改網路要求。
屬性
-
authCredentials
物件選用
僅做為 onAuthRequired 事件的回應。如果設定了，就會使用提供的憑證發出要求。
-
密碼
字串
-
使用者名稱
字串
-
-
cancel
布林值 (選用)
如果為 true，則要求會被取消。這樣就無法傳送要求。這可做為 onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 和 onAuthRequired 事件的回應。
-
redirectUrl
字串 選用
只能用於 onBeforeRequest 和 onHeadersReceived 事件的回應。如有設定，原始要求就無法傳送/完成，而會重新導向至指定網址。允許重新導向至非 HTTP 配置，例如
data:。重新導向動作發起的重新導向會使用原始要求方法進行重新導向，但有一個例外：如果重新導向是在 onHeadersReceived 階段啟動，則系統會使用 GET 方法發出重新導向。如果網址含有ws://和wss://配置，系統會忽略重新導向。 -
requestHeaders
HttpHeaders 選用
只能用於 onBeforeSendHeaders 事件的回應。如有設定，要求就會改為使用這些要求標頭發出。
-
responseHeaders
HttpHeaders 選用
只能用於 onHeadersReceived 事件的回應。如果設定，系統會假設伺服器改為使用這些回應標頭進行回應。只有在需要修改標頭以限制衝突次數時，才傳回
responseHeaders(只有一個擴充功能可以為每個要求修改responseHeaders)。
FormDataItem
包含表單資料中傳送的資料。針對網址編碼的格式，如果資料是 utf-8 字串，則會儲存為字串，否則會以 ArrayBuffer 形式儲存。如果是表單資料，則為 ArrayBuffer。如果表單資料代表上傳檔案，這裡提供的檔案名稱會是字串 (如有提供名稱)。
列舉
ArrayBuffer
字串
HttpHeaders
HTTP 標頭陣列。每個標頭都會表示為包含 name、value 或 binaryValue 鍵的字典。
類型
物件 []
屬性
-
binaryValue
number[] 選填
HTTP 標頭值 (如果無法以 UTF-8 表示)，請儲存為個別位元組值 (0..255)。
-
名稱
字串
HTTP 標頭名稱。
-
值
字串 選用
HTTP 標頭的值 (可透過 UTF-8 表示)。
IgnoredActionType
列舉
"redirect"
"request_headers"
"response_headers"
OnAuthRequiredOptions
列舉
"responseHeaders"
指定應在事件中加入回應標頭。
"blocking"
指定在回呼函式傳回之前，要求將遭到封鎖。
"asyncBlocking"
用於指定回呼函式以非同步方式處理。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnBeforeRedirectOptions
列舉
"responseHeaders"
指定應在事件中加入回應標頭。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnBeforeRequestOptions
列舉
"blocking"
指定在回呼函式傳回之前，要求將遭到封鎖。
"requestBody"
指出要求主體應包含在事件中。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnBeforeSendHeadersOptions
列舉
"requestHeaders"
指定要求標頭應包含在事件中。
"blocking"
指定在回呼函式傳回之前，要求將遭到封鎖。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnCompletedOptions
列舉
"responseHeaders"
指定應在事件中加入回應標頭。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnErrorOccurredOptions
值
"extraHeaders"
OnHeadersReceivedOptions
列舉
"blocking"
指定在回呼函式傳回之前，要求將遭到封鎖。
"responseHeaders"
指定應在事件中加入回應標頭。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnResponseStartedOptions
列舉
"responseHeaders"
指定應在事件中加入回應標頭。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
OnSendHeadersOptions
列舉
"requestHeaders"
指定要求標頭應包含在事件中。
"extraHeaders"
指出標頭可能違反跨源資源共享 (CORS)。
RequestFilter
這個物件會描述要套用至 webRequest 事件的篩選器。
屬性
-
tabId
數字 選填
-
種類
ResourceType[] 選用
要求類型清單。無法符合任一類型的請求會遭到篩除。
-
urls
string[]
網址或網址模式清單。無法與任一網址比對成功的請求會遭到篩除。
-
windowId
數字 選填
ResourceType
列舉
"main_frame"
將資源指定為主頁框。
"sub_frame"
將資源指定為子框架。
"stylesheet"
將資源指定為樣式表。
"script"
將資源指定為指令碼。
"image"
將資源指定為圖片。
"font"
將資源指定為字型。
"object"
將資源指定為物件。
"xmlhttprequest"
將資源指定為 XMLHttpRequest。
"ping"
將資源指定為連線偵測 (ping)。
"csp_report"
將資源指定為內容安全政策 (CSP) 報表。
"media"
將資源指定為媒體物件。
"websocket"
將資源指定為 WebSocket。
"webbundle"
將資源指定為 WebBundle。
"other"
將資源指定為不包含在所列類型中的類型。
UploadData
包含透過網址要求上傳的資料。
屬性
-
位元組
任何選填
包含資料副本的 ArrayBuffer。
-
檔案
字串 選用
包含檔案路徑和名稱的字串。
屬性
MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES
每 10 分鐘的持續間隔，可呼叫 handlerBehaviorChanged 的次數上限。handlerBehaviorChanged 是一種很昂貴的函式呼叫，不常被呼叫。
值
20
方法
handlerBehaviorChanged()
chrome.webRequest.handlerBehaviorChanged(
callback?: function,
)
當 webRequest 處理常式的行為發生變更時，就必須呼叫此項目，以免快取作業造成錯誤處理。這個函式呼叫成本高昂，別經常呼叫這個程式庫。
參數
-
回呼
函式選用
callback參數如下所示：()=>void
傳回
-
Promise<void>
Chrome 116 以上版本Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
onActionIgnored
chrome.webRequest.onActionIgnored.addListener(
callback: function,
)
當擴充功能提議對網路要求進行的修改遭到忽略時觸發。如果與其他擴充功能發生衝突，就會發生這種情形。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>void
-
詳細資料
物件
-
已忽略的建議動作。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
-
onAuthRequired
chrome.webRequest.onAuthRequired.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnAuthRequiredOptions[],
)
收到驗證失敗時觸發。事件監聽器有三個選項：可以提供驗證憑證、取消要求並顯示錯誤頁面，或者不對驗證採取任何行動。如果提供錯誤的使用者憑證，系統可能會針對相同要求多次呼叫這個憑證。請注意，你必須在 extraInfoSpec 參數中指定 'blocking' 或 'asyncBlocking' 模式的其中一種。
參數
-
回呼
功能
callback參數如下所示：(details: object,asyncCallback?: function)=>BlockingResponse|undefined
-
詳細資料
物件
-
挑戰者
物件
要求驗證的伺服器。
-
主辦方
字串
-
通訊埠
號碼
-
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
isProxy
boolean
True 代表 Proxy-Authenticate，則為「false」，WWW-Authenticate 為「false」。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
領域
字串 選用
伺服器提供的驗證領域 (如果有的話)。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
responseHeaders
HttpHeaders 選用
連同此回應一起收到的 HTTP 回應標頭。
-
架構
字串
驗證配置，例如 Basic 或摘要。
-
statusCode
號碼
Chrome 43 以上版本伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行或是 HTTP/0.9 回應 (即缺少狀態行的回應) 或空白字串 (如果沒有標頭)。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
asyncCallback
函式選用
Chrome 58 以上版本asyncCallback參數如下所示：(response: BlockingResponse)=>void
-
則回應
-
-
returns
BlockingResponse|未定義
如果「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回此類型的物件。
-
-
過濾器
-
extraInfoSpec
onBeforeRedirect
chrome.webRequest.onBeforeRedirect.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRedirectOptions[],
)
伺服器啟動的重新導向即將開始時觸發。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
fromCache
boolean
指出這個回應是否已從磁碟快取中擷取。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
ip
字串 選用
實際傳送要求的伺服器 IP 位址。請注意，這個位址可能是常值 IPv6 位址。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
redirectUrl
字串
新的網址。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
responseHeaders
HttpHeaders 選用
隨這個重新導向一同收到的 HTTP 回應標頭。
-
statusCode
號碼
伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行或是 HTTP/0.9 回應 (即缺少狀態行的回應) 或空白字串 (如果沒有標頭)。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
-
過濾器
-
extraInfoSpec
onBeforeRequest
chrome.webRequest.onBeforeRequest.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeRequestOptions[],
)
即將發生要求時觸發。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>BlockingResponse|undefined
-
詳細資料
物件
-
documentId
字串 選用
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestBody
物件選用
包含 HTTP 要求主體資料。只有在 extraInfoSpec 包含「requestBody」時，才會提供此值。
-
錯誤
字串 選用
取得要求主體資料時發生錯誤。
-
formData
物件選用
如果要求方法為 POST，且主體是採用 UTF8 編碼的鍵/值組合序列，並編碼為 multipart/form-data，或 application/x-www-form-urlencoded，則會出現這個字典，每個鍵都包含該鍵的所有值清單。如果資料屬於其他媒體類型，或資料格式錯誤，就不會顯示字典。這個字典的值範例如下：{'key': ['value1', 'value2']}。
-
原始
UploadData[] 選用
如果要求方法為 PUT 或 POST，而且主體尚未在 formData 中剖析，那麼這個陣列會包含未剖析的要求主體元素。
-
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
returns
BlockingResponse|未定義
如果「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回此類型的物件。
-
-
過濾器
-
extraInfoSpec
onBeforeSendHeaders
chrome.webRequest.onBeforeSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnBeforeSendHeadersOptions[],
)
在有要求標頭可用後，在傳送 HTTP 要求前觸發。這類情況可能會在系統建立 TCP 連線至伺服器後，但傳送任何 HTTP 資料之前。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>BlockingResponse|undefined
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestHeaders
HttpHeaders 選用
將與此要求一併傳送的 HTTP 要求標頭。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
returns
BlockingResponse|未定義
如果「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回此類型的物件。
-
-
過濾器
-
extraInfoSpec
onCompleted
chrome.webRequest.onCompleted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnCompletedOptions[],
)
要求完成時觸發。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
fromCache
boolean
指出這個回應是否已從磁碟快取中擷取。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
ip
字串 選用
實際傳送要求的伺服器 IP 位址。請注意，這個位址可能是常值 IPv6 位址。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
responseHeaders
HttpHeaders 選用
連同此回應一起收到的 HTTP 回應標頭。
-
statusCode
號碼
伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行或是 HTTP/0.9 回應 (即缺少狀態行的回應) 或空白字串 (如果沒有標頭)。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
-
過濾器
-
extraInfoSpec
OnCompletedOptions[] 選用
onErrorOccurred
chrome.webRequest.onErrorOccurred.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnErrorOccurredOptions[],
)
發生錯誤時觸發。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。如果要求是影格導覽，則不會顯示此值。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
錯誤
字串
錯誤說明。這個字串「不保證」在各版本之間仍能回溯相容。您不得根據內容剖析及採取行動。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
fromCache
boolean
指出這個回應是否已從磁碟快取中擷取。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
ip
字串 選用
實際傳送要求的伺服器 IP 位址。請注意，這個位址可能是常值 IPv6 位址。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
-
過濾器
-
extraInfoSpec
onHeadersReceived
chrome.webRequest.onHeadersReceived.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnHeadersReceivedOptions[],
)
系統收到要求的 HTTP 回應標頭時觸發。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>BlockingResponse|undefined
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
responseHeaders
HttpHeaders 選用
系統收到包含此回應的 HTTP 回應標頭。
-
statusCode
號碼
Chrome 43 以上版本伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行，或是 HTTP/0.9 回應的「HTTP/0.9 200 OK」字串 (例如缺少狀態行的回應)。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
returns
BlockingResponse|未定義
如果「extraInfoSpec」參數中指定「blocking」，事件監聽器應傳回此類型的物件。
-
-
過濾器
-
extraInfoSpec
onResponseStarted
chrome.webRequest.onResponseStarted.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnResponseStartedOptions[],
)
接收回應主體的第一個位元組時觸發。針對 HTTP 要求，這表示可用狀態行和回應標頭。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
fromCache
boolean
指出這個回應是否已從磁碟快取中擷取。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
ip
字串 選用
實際傳送要求的伺服器 IP 位址。請注意，這個位址可能是常值 IPv6 位址。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
responseHeaders
HttpHeaders 選用
連同此回應一起收到的 HTTP 回應標頭。
-
statusCode
號碼
伺服器傳回的標準 HTTP 狀態碼。
-
statusLine
字串
回應的 HTTP 狀態行或是 HTTP/0.9 回應 (即缺少狀態行的回應) 或空白字串 (如果沒有標頭)。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
-
過濾器
-
extraInfoSpec
onSendHeaders
chrome.webRequest.onSendHeaders.addListener(
callback: function,
filter: RequestFilter,
extraInfoSpec?: OnSendHeadersOptions[],
)
在將要求傳送至伺服器前觸發 (在 onSendHeaders 觸發時可查看先前 onBeforeSendHeaders 回呼的修改)。
參數
-
回呼
功能
callback參數如下所示：(details: object)=>void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本提出要求的文件 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
值 0 表示要求會在主頁框中執行；正值代表要求發生時子頁框的 ID。如果載入 (子) 畫面的文件 (
type為main_frame或sub_frame)，frameId會指出這個頁框的 ID，而不是外框的 ID。分頁中的影格 ID 不得重複。 -
frameTypeChrome 106 以上版本
要求發生的位置類型。
-
發起人
字串 選用
Chrome 63 以上版本發出要求的來源。這項操作不會透過重新導向改變。如果這是不透明起點，系統會使用「null」字串。
-
method
字串
標準 HTTP 方法。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。
-
parentFrameId
號碼
包裝傳送要求的影格 ID。如果沒有上層頁框，請設為 -1。
-
requestHeaders
HttpHeaders 選用
已透過此要求傳出的 HTTP 要求標頭。
-
requestId
字串
要求的 ID。瀏覽器工作階段中的要求 ID 不得重複。因此，這些事件可以用來連結同一個要求的不同事件。
-
tabId
號碼
發出要求的分頁 ID。如果要求與分頁無關，請設為 -1。
-
timeStamp
號碼
這個信號的觸發時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
類型
要求資源的使用情況。
-
url
字串
-
-
-
過濾器
-
extraInfoSpec
OnSendHeadersOptions[] 選用