chrome.webNavigation

refresh date: 2026-09-25 robots: noindex

說明

使用 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())，可能會產生非預期的結果。

Frame ID

分頁中的頁框可透過頁框 ID 識別。主頁框的 ID 一律為 0，子頁框的 ID 則為正數。在頁框中建構文件後，文件的頁框 ID 在文件生命週期內會保持不變。自 Chrome 49 起，這個 ID 在頁框的生命週期內 (跨多個導覽) 也會保持不變。

由於 Chrome 採用多程序架構，分頁可能會使用不同的程序來轉譯網頁的來源和目的地。因此，如果在新程序中進行導覽，您可能會同時收到新舊網頁的事件，直到新導覽提交為止 (即針對新主頁框傳送 onCommitted 事件)。換句話說，可能有多個待處理的 webNavigation 事件序列，且具有相同的 frameId。序列可透過 processId 鍵區分。

另請注意，在暫時載入期間，程序可能會切換多次。當負載重新導向至其他網站時，就會發生這種情況。在這種情況下，您會收到重複的 onBeforeNavigate 和 onErrorOccurred 事件，直到收到最終的 onCommitted 事件為止。

另一個與擴充功能相關的問題概念是頁框的生命週期。框架會託管文件 (與已提交的網址相關聯)。文件可能會變更 (例如透過導覽)，但 frameId 不會變更，因此很難將特定文件中發生的事件與 frameId 建立關聯。我們將推出 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

Chrome 44 以上版本

列舉

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 以上版本

導覽原因。使用的轉換類型與 History API 中定義的相同。這些轉換類型與 History API 中定義的類型相同，但 "start_page" 會取代 "auto_toplevel" (為了回溯相容性)。

列舉

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

方法

getAllFrames()

Promise 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
): Promise<object[] | undefined>

擷取指定分頁中所有頁框的資訊。

參數

  • 詳細資料

    物件

    要擷取所有頁框的分頁資訊。

    • tabId

      數字

      分頁 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (details?: object[]) => void

    • 詳細資料

      object[] 選填

      指定分頁中的頁框清單，如果指定的分頁 ID 無效，則為空值。

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 以上版本

        文件所處的生命週期。

      • errorOccurred

        布林值

        如果這個頁框中的最後一次導覽因錯誤而中斷 (即觸發 onErrorOccurred 事件)，則為 True。

      • frameId

        數字

        影格的 ID。0 表示這是主頁框；正值表示子頁框的 ID。

      • frameType

        FrameType

        Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        執行這個頁框轉譯器的程序 ID。

      • 網址

        字串

        目前與這個頁框相關聯的網址。

傳回

  • Promise<object[] | undefined>

    Chrome 93 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getFrame()

Promise 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
): Promise<object | undefined>

擷取指定頁框的資訊。框架是指網頁的 <iframe> 或 <frame>，並以分頁 ID 和框架 ID 識別。

參數

  • 詳細資料

    物件

    要擷取資訊的影格相關資訊。

    • documentId

      字串 選填

      Chrome 106 以上版本

      文件的 UUID。如果提供 frameId 和/或 tabId，系統會驗證這些 ID 是否與指定文件 ID 找到的文件相符。

    • frameId

      數字 選填

      指定分頁中的頁框 ID。

    • processId

      數字 選填

      自 Chrome 49 起淘汰

      現在，系統會根據分頁 ID 和頁框 ID 識別頁框，不再需要程序 ID，因此會忽略程序 ID。

      執行這個分頁轉譯器的程序 ID。

    • tabId

      數字 選填

      影格所在分頁的 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (details?: object) => void

    • 詳細資料

      物件 選填

      所要求頁框的相關資訊。如果指定的頁框 ID 和/或分頁 ID 無效，則為空值。

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 以上版本

        文件所處的生命週期。

      • errorOccurred

        布林值

        如果這個頁框中的最後一次導覽因錯誤而中斷 (即觸發 onErrorOccurred 事件)，則為 True。

      • frameType

        FrameType

        Chrome 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

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • Chrome 106 以上版本

        文件所處的生命週期。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。特定分頁和程序的頁框 ID 都是不重複的。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        自 Chrome 50 起淘汰

        系統不會再為這個事件設定 processId，因為在 onCommit 之前，無法得知要轉譯結果文件的程序。

        值為 -1。

      • tabId

        數字

        即將進行導覽的分頁 ID。

      • timeStamp

        數字

        瀏覽器即將開始導覽的時間，以從 Epoch 紀元時間算起的毫秒數表示。

      • 網址

        字串

  • 篩選器

    物件 選填

onCommitted

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

在導覽提交時觸發。文件 (和參照的資源，例如圖片和子框架) 可能仍在下載中，但瀏覽器已從伺服器收到部分文件，並決定切換至新文件。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所處的生命週期。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        Chrome 74 以上版本

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        執行這個頁框轉譯器的程序 ID。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        導覽提交時間，以自 Epoch 紀元時間起的毫秒為單位。

      • transitionQualifiers

        TransitionQualifier[]

        轉換限定詞清單。

      • transitionType

        TransitionType

        導覽原因。

      • 網址

        字串

  • 篩選器

    物件 選填

onCompleted

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

當文件 (包括其參照的資源) 完全載入並初始化時，就會觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所處的生命週期。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        Chrome 74 以上版本

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        執行這個頁框轉譯器的程序 ID。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        文件完成載入的時間，以自 Epoch 紀元時間起的毫秒為單位。

      • 網址

        字串

  • 篩選器

    物件 選填

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

建立新視窗或在現有視窗中建立新分頁，以便託管導覽時，系統會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • sourceFrameId

        數字

        觸發導覽的頁框 ID，其中包含 sourceTabId。0 表示主頁框。

      • sourceProcessId

        數字

        執行來源頁框轉譯器的程序 ID。

      • sourceTabId

        數字

        觸發導覽的分頁 ID。

      • tabId

        數字

        開啟網址的分頁 ID

      • timeStamp

        數字

        瀏覽器即將建立新檢視畫面的時間，以從 Epoch 紀元時間算起的毫秒數表示。

      • 網址

        字串

        要在新視窗中開啟的網址。

  • 篩選器

    物件 選填

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

在網頁的 DOM 完全建構完成時觸發，但參照的資源可能尚未載入完畢。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所處的生命週期。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        Chrome 74 以上版本

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        執行這個頁框轉譯器的程序 ID。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        網頁 DOM 完全建構完成的時間，以毫秒為單位 (自 Epoch 起算)。

      • 網址

        字串

  • 篩選器

    物件 選填

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

發生錯誤且導覽中斷時觸發。如果發生網路錯誤，或使用者取消導覽，就可能發生這種情況。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所處的生命週期。

      • 錯誤

        字串

        錯誤說明。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        Chrome 74 以上版本

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        自 Chrome 50 起淘汰

        這個事件不再設定 processId。

        值為 -1。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        錯誤發生時間，以從 Epoch 紀元時間算起的毫秒數表示。

      • 網址

        字串

  • 篩選器

    物件 選填

onHistoryStateUpdated

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

頁框的歷史記錄更新為新網址時觸發。該相框日後的所有活動都會使用更新後的網址。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所處的生命週期。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        Chrome 74 以上版本

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        執行這個頁框轉譯器的程序 ID。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        導覽提交時間，以自 Epoch 紀元時間起的毫秒為單位。

      • transitionQualifiers

        TransitionQualifier[]

        轉換限定詞清單。

      • transitionType

        TransitionType

        導覽原因。

      • 網址

        字串

  • 篩選器

    物件 選填

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

影格的參考片段更新時觸發。該相框日後的所有活動都會使用更新後的網址。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所處的生命週期。

      • frameId

        數字

        0 表示導覽發生在分頁內容視窗中；正值表示導覽發生在子框架中。分頁中的頁框 ID 不得重複。

      • Chrome 106 以上版本

        發生導覽的頁框類型。

      • parentDocumentId

        字串 選填

        Chrome 106 以上版本

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

      • parentFrameId

        數字

        Chrome 74 以上版本

        父項頁框的 ID，如果是主頁框，則為 -1。

      • processId

        數字

        執行這個頁框轉譯器的程序 ID。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        導覽提交時間，以自 Epoch 紀元時間起的毫秒為單位。

      • transitionQualifiers

        TransitionQualifier[]

        轉換限定詞清單。

      • transitionType

        TransitionType

        導覽原因。

      • 網址

        字串

  • 篩選器

    物件 選填

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

當分頁內容被其他分頁 (通常是先前預先轉譯的分頁) 取代時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • replacedTabId

        數字

        遭取代的分頁 ID。

      • tabId

        數字

        取代舊分頁的分頁 ID。

      • timeStamp

        數字

        替換時間，以 Epoch 紀元時間起算的毫秒數表示。