說明
使用 chrome.webNavigation
API 接收傳輸中導航要求的狀態通知。
權限
webNavigation
資訊清單
所有 chrome.webNavigation
方法和事件都必須在擴充功能資訊清單中宣告「webNavigation」權限。例如:
{
"name": "My extension",
...
"permissions": [
"webNavigation"
],
...
}
事件順序
針對成功完成的導覽,事件會以下列順序觸發:
onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted
過程中發生的任何錯誤都會導致 onErrorOccurred
事件。如果是特定導覽,在 onErrorOccurred
之後就不會再觸發任何事件。
如果導覽影格包含子頁框,其 onCommitted
會在其任何子項的 onBeforeNavigate
之前觸發;而 onCompleted
則會在其所有子項的 onCompleted
後觸發。
如果變更影格的參照片段,會觸發 onReferenceFragmentUpdated
事件。這個事件可能會在 onDOMContentLoaded
後隨時觸發,即使在 onCompleted
之後也一樣。
如果使用 History API 修改影格狀態 (例如使用 history.pushState()
,就會觸發 onHistoryStateUpdated
事件)。onDOMContentLoaded
後隨時能觸發這個事件。
如果瀏覽頁面從往返快取還原網頁,onDOMContentLoaded
事件就不會觸發。網頁首次造訪時,內容已經完成載入,因此不會觸發事件。
如果您是透過 Chrome 免安裝或即時網頁功能觸發瀏覽,系統會將完全載入的網頁切換為目前的分頁。在這種情況下,會觸發 onTabReplaced
事件。
與 webRequest 事件的關係
webRequest API 的事件與 WebNavigation API 事件之間沒有定義順序。系統可能會針對已啟動新導覽的頁框接收 webRequest 事件,或只有在網路資源完整載入後才開始導覽作業。
一般來說,WebNavigation 事件與 UI 中顯示的導覽狀態密切相關,而 webRequest 事件會對應網路堆疊的狀態,後者通常不會向使用者顯示。
分頁 ID
並非所有導覽分頁都會對應到 Chrome UI 中的實際分頁,例如已預先轉譯的分頁。您無法透過 tabs API 存取這類分頁,也無法透過 webNavigation.getFrame
或 webNavigation.getAllFrames
要求有關分頁的資訊。替換這類分頁後,系統會觸發 onTabReplaced
事件,並透過這些 API 存取事件。
時間戳記
請注意,在作業系統處理不同的 Chrome 程序時,如果發生一些技術性問題,可能會導致瀏覽器和擴充功能程序之間的時鐘產生偏差。這表示 WebNavigation 事件的 timeStamp
屬性僅保證與「內部」保持一致。比較一個事件與其他事件後,您就能取得這些事件之間的正確偏移值,但如果能將這些事件與擴充功能中的目前時間 (例如透過 (new Date()).getTime()
) 比較,可能會產生非預期的結果。
頁框 ID
分頁內的頁框可以使用頁框 ID 來識別。主影格的影格 ID 一律為 0,子項影格的 ID 則為正數。文件在影格中建構後,其影格 ID 在文件的生命週期中會保持不變。從 Chrome 49 版開始,這個 ID 在影格生命週期內也是固定不變 (跨多個瀏覽)。
由於 Chrome 的多程序特性,分頁可能會使用不同的程序轉譯網頁的來源和目的地。因此,如果在新程序中進行導覽,您可能會收到來自新頁面和舊頁面的事件,直到使用新的導覽功能為止 (也就是針對新主要頁框傳送 onCommitted
事件)。換句話說,有可能具有相同 frameId
的 WebNavigation 事件有多個待處理序列。序列可由 processId
鍵區分。
另請注意,在臨時負載期間,系統可能會多次切換此程序。當負載重新導向至其他網站時,就會發生這種情況。在這種情況下,您會收到重複的 onBeforeNavigate
和 onErrorOccurred
事件,直到收到最終的 onCommitted
事件為止。
另一個與擴充功能相關的問題,是影格的生命週期。頁框代管文件 (與已提交的網址相關聯)。文件可能會變更 (例如透過導覽),但 frameId 不會。因此,很難將特定文件中發生的情況與 frameIds 建立關聯。我們推出了 documentId 概念,這是每份文件都有專屬 ID。如果瀏覽頁框並開啟新文件,ID 就會發生變化。這個欄位有助於判斷頁面在預先算繪/啟用/快取之間變更生命週期狀態的時機,因為此欄位保持不變。
轉換類型和限定詞
WebNavigation API 的 onCommitted
事件包含 transitionType
和 transitionQualifiers
屬性。轉換類型與 history API 中使用的相同,用於說明瀏覽器如何瀏覽這個特定網址。此外,也可以傳回幾個轉換限定詞,以進一步定義導覽。
以下是可用的轉換限定詞:
轉換條件 | 說明 |
---|---|
"client_redirect" | 使用者瀏覽期間,網頁上由 JavaScript 或中繼重新整理標記造成的一或多個重新導向。 |
"server_redirect" | 瀏覽期間,從伺服器傳送的 HTTP 標頭造成一或多個重新導向。 |
「forward_back」 | 使用者使用「往前」或「返回」按鈕啟動導覽。 |
「from_address_bar」 | 使用者是從網址列 (即網址列) 啟動瀏覽作業。 |
示例
如要試用這個 API,請從 chrome-extension-samples 存放區安裝 webNavigation API 範例。
類型
TransitionQualifier
列舉
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
導航的原因。系統會使用您在 history API 中定義的轉換類型。這些轉換類型與 history API 中定義的轉換類型相同,但以 "start_page"
取代 "auto_toplevel"
(是為了回溯相容性)。
列舉
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"start_page"
"keyword_generated"
方法
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
擷取特定分頁所有影格的相關資訊。
參數
-
詳細資料
物件
用於擷取所有影格的分頁相關資訊。
-
tabId
號碼
分頁的 ID。
-
-
回呼
函式選用
callback
參數如下所示:(details?: object[]) => void
-
詳細資料
object[] optional
指定分頁中的頁框清單。如果指定的分頁 ID 無效,則為 null。
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
errorOccurred
boolean
如果這個頁框中的最後一個導覽因發生錯誤而中斷 (也就是引發的 onErrorEventsrred 事件),則為 True。
-
frameId
號碼
影格的 ID。0 表示這是主要頁框;正值代表子頁框的 ID。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
執行這個影格轉譯器的程序 ID。
-
網址
字串
目前與這個頁框相關聯的網址。
-
-
傳回
-
Promise<object[] | undefined>
Chrome 93 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
)
擷取指定影格的相關資訊。頁框是指網頁的 <iframe> 或 <frame>,以分頁 ID 和頁框 ID 辨識。
參數
-
詳細資料
物件
要擷取相關資訊的影格相關資訊。
-
documentId
字串 選用
Chrome 106 以上版本文件的 UUID。如果提供 frameId 和/或 tabId,系統會驗證兩者,確保與提供的文件 ID 所找到的文件相符。
-
frameId
數字 選填
指定分頁中的影格 ID。
-
processId
數字 選填
自 Chrome 49 版起已淘汰的項目系統現在會依分頁 ID 和影格 ID 明確識別頁框;不再需要使用程序 ID,因此予以忽略。
為這個分頁執行轉譯器的程序 ID。
-
tabId
數字 選填
頁框所屬分頁的 ID。
-
-
回呼
函式選用
callback
參數如下所示:(details?: object) => void
-
詳細資料
物件選用
要求影格的相關資訊。如果指定的影格 ID 和/或分頁 ID 無效,則為空值。
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
errorOccurred
boolean
如果這個頁框中的最後一個導覽因發生錯誤而中斷 (也就是引發的 onErrorEventsrred 事件),則為 True。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
上層頁框的 ID;如果這是主頁框,則為
-1
。 -
網址
字串
目前與這個頁框相關聯的網址 (如果由 frameId 識別的框架在指定分頁的某個時間點存在,則此為目前相關聯的網址)。即使網址與特定的 frameId 相關聯,並不表示對應的頁框仍然存在。
-
-
傳回
-
Promise<object | undefined>
Chrome 93 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
導覽即將開始時觸發。
參數
-
功能
callback
參數如下所示:(details: object) => void
-
物件
-
Chrome 106 以上版本
文件的生命週期。
-
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。特定分頁和程序的影格 ID 不得重複。
-
Chrome 106 以上版本
導覽所在的頁框類型。
-
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
號碼
上層頁框的 ID;如果這是主頁框,則為
-1
。 -
號碼
自 Chrome 50 版起已淘汰的項目這個事件不再設定 processId,因為在 onCommit 之前才會確認產生結果文件的程序。
-1 的值。
-
號碼
即將發生導覽的分頁 ID。
-
號碼
瀏覽器結束導覽的時間 (以 Epoch 紀元時間起算,以毫秒為單位)。
-
字串
-
-
-
物件選用
-
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
執行導覽時觸發。文件 (及其參照的資源,例如圖片和子頁框) 可能仍在下載,但是伺服器至少收到了文件的一部分,瀏覽器決定切換至新的文件。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
Chrome 74 以上版本上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
執行這個影格轉譯器的程序 ID。
-
tabId
號碼
發生導覽的分頁 ID。
-
timeStamp
號碼
導覽作業完成的時間,以 Epoch 紀元時間起算的毫秒為單位。
-
transitionQualifiers
轉換限定詞清單。
-
transitionType
導航的原因。
-
網址
字串
-
-
-
篩選器
物件選用
-
網址
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
文件 (包括其參照的資源) 完全載入並初始化時觸發。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
Chrome 74 以上版本上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
執行這個影格轉譯器的程序 ID。
-
tabId
號碼
發生導覽的分頁 ID。
-
timeStamp
號碼
文件完成載入的時間 (以 Epoch 紀元時間起算的毫秒為單位)。
-
網址
字串
-
-
-
篩選器
物件選用
-
網址
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
為代管導覽而建立新的視窗或現有視窗中的新分頁時觸發。
參數
-
功能
callback
參數如下所示:(details: object) => void
-
物件
-
號碼
含有 sourceTabId 畫面,會在其中觸發導覽的頁框 ID。0 表示主頁框。
-
號碼
執行來源影格轉譯器的程序 ID。
-
號碼
觸發導覽的分頁 ID。
-
號碼
開啟該網址的分頁 ID
-
號碼
瀏覽器即將建立新檢視畫面的時間 (自 Epoch 紀元時間起算,以毫秒為單位)。
-
字串
要在新視窗中開啟的網址。
-
-
-
物件選用
-
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
網頁的 DOM 完整建構時觸發,但參照的資源可能無法完成載入。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
Chrome 74 以上版本上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
執行這個影格轉譯器的程序 ID。
-
tabId
號碼
發生導覽的分頁 ID。
-
timeStamp
號碼
網頁 DOM 完全建構的時間 (以 Epoch 紀元時間起算,以毫秒為單位)。
-
網址
字串
-
-
-
篩選器
物件選用
-
網址
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
當發生錯誤且導覽中止時,就會觸發。這可能是因為網路錯誤或使用者中止瀏覽。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
錯誤
字串
錯誤說明。
-
frameId
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
Chrome 74 以上版本上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
自 Chrome 50 版起已淘汰的項目這個事件的 processId 已不再設定,
-1 的值。
-
tabId
號碼
發生導覽的分頁 ID。
-
timeStamp
號碼
發生錯誤的時間 (以 Epoch 紀元時間起算的毫秒為單位)。
-
網址
字串
-
-
-
篩選器
物件選用
-
網址
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
影格歷史記錄更新為新網址時觸發。該影格未來的所有事件都會使用更新的網址。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
Chrome 74 以上版本上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
執行這個影格轉譯器的程序 ID。
-
tabId
號碼
發生導覽的分頁 ID。
-
timeStamp
號碼
導覽作業完成的時間,以 Epoch 紀元時間起算的毫秒為單位。
-
transitionQualifiers
轉換限定詞清單。
-
transitionType
導航的原因。
-
網址
字串
-
-
-
篩選器
物件選用
-
網址
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
影格的參照片段更新時觸發。該影格未來的所有事件都會使用更新的網址。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
documentId
字串
Chrome 106 以上版本已載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件的生命週期。
-
frameId
號碼
0 表示導覽會在分頁內容視窗中進行,正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。
-
frameTypeChrome 106 以上版本
導覽所在的頁框類型。
-
parentDocumentId
字串 選用
Chrome 106 以上版本擁有這個頁框的上層文件 UUID。如果沒有父項,就無法設定這個屬性。
-
parentFrameId
號碼
Chrome 74 以上版本上層頁框的 ID;如果這是主頁框,則為
-1
。 -
processId
號碼
執行這個影格轉譯器的程序 ID。
-
tabId
號碼
發生導覽的分頁 ID。
-
timeStamp
號碼
導覽作業完成的時間,以 Epoch 紀元時間起算的毫秒為單位。
-
transitionQualifiers
轉換限定詞清單。
-
transitionType
導航的原因。
-
網址
字串
-
-
-
篩選器
物件選用
-
網址
重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
當分頁內容替換為其他 (通常是先前預先算繪) 的分頁時觸發。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
replacedTabId
號碼
遭取代分頁的 ID。
-
tabId
號碼
取代舊分頁的分頁 ID。
-
timeStamp
號碼
取代模式發生的時間 (以 Epoch 紀元時間起算的毫秒為單位)。
-
-