說明
使用 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 後隨時觸發。
如果瀏覽方式從「Back Forward Cache」還原頁面，就會發生 onDOMContentLoaded 事件
都不會觸發事件不會觸發，因為內容在網頁載入完成時就已經完成載入
初次造訪。
如果使用 Chrome 免安裝應用程式或即時網頁功能觸發導覽，
頁面切換至目前的分頁。此時，會觸發 onTabReplaced 事件。
與 webRequest 事件的關係
webRequest API 事件與 webNavigation API)。系統可能仍會收到 WebRequest 事件的影格 開始新的導覽，或導覽只會在網路資源已就緒後才會執行 已完全載入。
一般來說，webNavigation 事件與顯示的導覽狀態密切相關 UI 中的 WebRequest 事件會對應至網路堆疊的狀態， 對使用者來說，結果通常不透明。
分頁 ID
並非所有瀏覽過的分頁都會對應到 Chrome 使用者介面中的實際分頁，例如
預先算繪的結果這類分頁無法透過 tabs API 存取，也無法索取資訊
，請呼叫 webNavigation.getFrame() 或 webNavigation.getAllFrames()。產生這類分頁後
onTabReplaced 事件進行替換，接著即可透過這些 API 存取這些事件。
時間戳記
請特別注意，作業系統在處理不同的 Chrome 時，存在一些技術障礙
處理程序可能會導致瀏覽器本身與擴充功能程序之間的時鐘出現偏差。沒錯
表示只保證 WebNavigation 事件 timeStamp 屬性的 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「onCommitted」事件發生了transitionType和transitionQualifiers
資源。轉換類型與 history API 中用於說明
瀏覽器前往這個特定網址。此外，您也可使用多種轉換限定詞
然後進一步定義導覽。
可用的轉換限定詞如下：
| 轉換限定詞 | 說明 |
|---|---|
| 「client_redirect」 | 在網頁瀏覽期間，發生網頁 JavaScript 或中繼重新整理標記造成的一或多個重新導向。 |
| 「server_redirect」 | 從伺服器傳送的 HTTP 標頭造成一或多個重新導向發生在瀏覽期間。 |
| 「forward_back」 | 使用者利用 [向前] 或 [上一頁] 按鈕開始導覽。 |
| "from_address_bar" | 使用者透過網址列啟動導航 (又稱為網址列)。 |
範例
如要試用這個 API，請安裝 chrome-extension-samples 提供的 webNavigation API 範例 Cloud Storage 也提供目錄同步處理功能
類型
TransitionQualifier
列舉
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
導覽的原因。系統會使用記錄 API 中定義的相同轉換類型。這些轉換類型與 history API 中定義的轉換類型相同，但請以 "start_page" 取代 "auto_toplevel" (為回溯相容性)。
列舉
"連結"
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"已產生"
"start_page"
"form_submit"
"重新載入"
"關鍵字"
「"keyword_generated"」
方法
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
擷取特定分頁所有頁框的相關資訊。
參數
-
詳細資料
物件
要擷取所有影格的分頁相關資訊。
-
tabId
數字
分頁的 ID。
-
-
回呼
函式 選用
callback參數如下所示：(details?: object[]) => void
-
詳細資料
object[] 選用
指定分頁中的頁框清單；如果指定的分頁 ID 無效，則為空值。
-
documentId
字串
Chrome 106 以上版本載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件所在的生命週期。
-
errorOccurred
布林值
如果此影格中的最後一個導覽因為發生錯誤 (即引發 onErrorOccurred 事件) 中斷，則為 True。
-
frameId
數字
影格的 ID。0 表示這是主要影格；正值代表子頁框的 ID。
-
frameTypeChrome 106 以上版本
導覽發生的影格類型。
-
parentDocumentId
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
為這個影格執行轉譯器的程序 ID。
-
網址
字串
目前與這個頁框相關聯的網址。
-
-
傳回
-
Promise<object[] |未定義>
Chrome 93 以上版本Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
getFrame()
chrome.webNavigation.getFrame(
details: object,
callback?: function,
)
擷取指定影格的相關資訊。頁框是指 <iframe>或 <頁框>並以分頁 ID 和頁框 ID 識別。
參數
-
詳細資料
物件
要擷取相關資訊的影格相關資訊。
-
documentId
string optional
Chrome 106 以上版本文件的 UUID。如果提供了 frameId 和/或 tabId，系統會驗證這些資訊，確保與提供的文件 ID 相符的文件相符。
-
frameId
編號 選填
指定分頁標籤中的影格 ID。
-
processId
編號 選填
自 Chrome 49 起已淘汰影格現在會以分頁 ID 和影格 ID 做為唯一識別。不再需要程序 ID，因此系統會予以忽略。
為這個分頁執行轉譯器的程序 ID。
-
tabId
編號 選填
顯示影格的分頁 ID。
-
-
回呼
函式 選用
callback參數如下所示：(details?: object) => void
-
詳細資料
物件 optional
所要求頁框的相關資訊；如果指定的影格 ID 和/或分頁 ID 無效，則為空值。
-
documentId
字串
Chrome 106 以上版本載入文件的 UUID。
-
documentLifecycleChrome 106 以上版本
文件所在的生命週期。
-
errorOccurred
布林值
如果此影格中的最後一個導覽因為發生錯誤 (即引發 onErrorOccurred 事件) 中斷，則為 True。
-
frameTypeChrome 106 以上版本
導覽發生的影格類型。
-
parentDocumentId
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
上層頁框的 ID；如果這是主要頁框，則為
-1。 -
網址
字串
目前與這個頁框相關聯的網址 (如果 frameId 識別的頁框存在於指定分頁的某個時間點存在)。網址已與指定的 frameId 建立關聯，並不表示相應的影格仍然存在。
-
-
傳回
-
Promise<object |未定義>
Chrome 93 以上版本Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
活動
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
在即將進行導覽時觸發。
參數
-
函式
callback參數如下所示：(details: object) => void
-
物件
-
Chrome 106 以上版本
文件所在的生命週期。
-
數字
0 表示瀏覽在分頁內容視窗中發生；正值表示子頁框中的導覽動作。特定分頁和程序的影格 ID 不得重複。
-
Chrome 106 以上版本
導覽發生的影格類型。
-
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
數字
上層頁框的 ID；如果這是主要頁框，則為
-1。 -
數字
自 Chrome 50 版起已淘汰系統不會再為這個事件設定 processId，因為在 onCommit 前，算繪產生的文件的程序都不會得知。
-1 的值。
-
數字
即將發生導覽的分頁 ID。
-
數字
瀏覽器開始導航的時間 (從 Epoch 紀元時間起算，以毫秒為單位)。
-
字串
-
-
-
物件 optional
-
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
Chrome 74 以上版本上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
為這個影格執行轉譯器的程序 ID。
-
tabId
數字
發生導覽的分頁 ID。
-
timeStamp
數字
進行導航的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
transitionQualifiers
轉換限定詞清單。
-
transitionType
導覽的原因。
-
網址
字串
-
-
-
篩選器
物件 optional
-
網址
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
Chrome 74 以上版本上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
為這個影格執行轉譯器的程序 ID。
-
tabId
數字
發生導覽的分頁 ID。
-
timeStamp
數字
文件載入完成的時間 (從 Epoch 紀元時間起算，以毫秒為單位)。
-
網址
字串
-
-
-
篩選器
物件 optional
-
網址
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 UrlFilter 欄位。
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
建立新視窗或現有視窗中的新分頁來代管導覽時觸發。
參數
-
函式
callback參數如下所示：(details: object) => void
-
物件
-
數字
含有 sourceTabId 的頁框 ID，且該影格會觸發導覽。0 表示主要頁框。
-
數字
為來源影格執行轉譯器的程序 ID。
-
數字
觸發導覽的分頁 ID。
-
數字
開啟網址的分頁 ID
-
數字
瀏覽器即將建立新檢視畫面的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
字串
要在新視窗中開啟的網址。
-
-
-
物件 optional
-
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
Chrome 74 以上版本上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
為這個影格執行轉譯器的程序 ID。
-
tabId
數字
發生導覽的分頁 ID。
-
timeStamp
數字
網頁 DOM 建構完成的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
網址
字串
-
-
-
篩選器
物件 optional
-
網址
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
Chrome 74 以上版本上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
自 Chrome 50 版起已淘汰這個事件已停止設定 processId。
-1 的值。
-
tabId
數字
發生導覽的分頁 ID。
-
timeStamp
數字
錯誤發生的時間，以 Epoch 紀元時間起算的毫秒數表示。
-
網址
字串
-
-
-
篩選器
物件 optional
-
網址
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
Chrome 74 以上版本上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
為這個影格執行轉譯器的程序 ID。
-
tabId
數字
發生導覽的分頁 ID。
-
timeStamp
數字
進行導航的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
transitionQualifiers
轉換限定詞清單。
-
transitionType
導覽的原因。
-
網址
字串
-
-
-
篩選器
物件 optional
-
網址
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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
string optional
Chrome 106 以上版本擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。
-
parentFrameId
數字
Chrome 74 以上版本上層頁框的 ID；如果這是主要頁框，則為
-1。 -
processId
數字
為這個影格執行轉譯器的程序 ID。
-
tabId
數字
發生導覽的分頁 ID。
-
timeStamp
數字
進行導航的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。
-
transitionQualifiers
轉換限定詞清單。
-
transitionType
導覽的原因。
-
網址
字串
-
-
-
篩選器
物件 optional
-
網址
要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 UrlFilter 欄位。
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
當分頁標籤內容替換為其他 (通常是先前預先算繪) 的分頁時觸發。
參數
-
回呼
函式
callback參數如下所示：(details: object) => void
-
詳細資料
物件
-
replacedTabId
數字
被取代的分頁 ID。
-
tabId
數字
取代舊分頁的 ID。
-
timeStamp
數字
執行取代作業的時間，以 Epoch 紀元時間起算的毫秒數為單位。
-
-