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 後不會再觸發任何事件。

如果導覽框架包含子框架，系統會在任何子項的 onBeforeNavigate 之前觸發其 onCommitted；而會在所有子項的 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 使用者介面中的實際分頁，例如預先算繪的分頁。你無法透過 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 事件為止)。換句話說，您可能會有多個待處理的 webNavigation 事件序列，且這些事件序列具有相同的 frameId。您可以使用 processId 鍵區分序列。

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

擴充功能還有一個問題，就是影格的生命週期。框架會代管與已提交網址相關聯的文件。文件可能會變更 (例如透過導覽)，但 frameId 不會變更，因此很難將特定文件中發生的事件與 frameId 建立關聯。我們將推出 documentId 的概念，這是每個文件的專屬 ID。如果框架導覽並開啟新文件，ID 就會變更。這個欄位不會變更，因此可用來判斷網頁何時會變更生命週期狀態 (預先算繪/有效/已快取)。

轉場類型和限定詞

webNavigation API 的 onCommitted 事件具有 transitionType 和 transitionQualifiers 屬性。轉場效果類型與歷史記錄 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 以上版本

導覽原因。系統會使用與歷史記錄 API 中定義的相同轉換類型。這些轉換類型與歷史記錄 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 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

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

    • 詳細資料

      object 選填

      所要求影格的相關資訊。如果指定的影格 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 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

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 以上版本已淘汰這項功能

        由於要等到 onCommit 才會知道要算繪結果文件的程序，因此這個事件不再設定 processId。

        值為 -1。

      • tabId

        數字

        即將發生導覽的索引標籤 ID。

      • timeStamp

        數字

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

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

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

        導覽原因。

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

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 紀元時間起的毫秒為單位。

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

onCreatedNavigationTarget

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

建立新視窗或現有視窗中的新分頁，以代管導覽時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • sourceFrameId

        數字

        觸發導覽的來源 TabId 框架 ID。0 表示主要框架。

      • sourceProcessId

        數字

        執行來源影格的算繪器程序 ID。

      • sourceTabId

        數字

        觸發導覽的索引標籤 ID。

      • tabId

        數字

        開啟網址的分頁 ID

      • timeStamp

        數字

        瀏覽器即將建立新的檢視畫面的時間，以 Epoch 時間 (毫秒) 為單位。

      • 網址

        字串

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

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

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 紀元時間算起的毫秒數表示。

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

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 紀元時間算起的毫秒數表示。

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

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

        導覽原因。

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

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

        導覽原因。

      • 網址

        字串

  • 篩選器

    object 選填

    • 網址

      events.UrlFilter[]

      網址必須符合的條件。系統會忽略這個事件的 UrlFilter「schemes」和「ports」欄位。

onTabReplaced

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

當分頁的內容替換為其他分頁 (通常是先前預先算繪的分頁) 時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (details: object) => void

    • 詳細資料

      物件

      • replacedTabId

        數字

        已取代的分頁 ID。

      • tabId

        數字

        取代舊分頁的分頁 ID。

      • timeStamp

        數字

        更換時間，以 Epoch 紀元時間起算的毫秒為單位。