browser.webNavigation

說明

使用 chrome.webNavigation API 接收導航要求狀態通知。

權限

webNavigation

所有 browser.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 屬性的 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 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 以上版本 瀏覽器。*自 Chrome 148 起

列舉

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

導覽原因。使用的轉換類型與 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()

browser.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

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

參數

• 詳細資料

  物件

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

  • tabId

    數字

    分頁 ID。

傳回

• Promise<object[] | undefined>

  Chrome 93 以上版本 Chrome 148 起為 browser.*

getFrame()

browser.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

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

參數

• 詳細資料

  物件

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

  • documentId

    字串 選填

    Chrome 106 以上版本 Chrome 148 起為 browser.*

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

  • frameId

    數字 選填

    指定分頁中的頁框 ID。

  • processId

    數字 選填

    自 Chrome 49 起淘汰

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

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

  • tabId

    數字 選填

    影格所在分頁的 ID。

傳回

• Promise<object | undefined>

  Chrome 93 以上版本 Chrome 148 起為 browser.*

事件

onBeforeNavigate

browser.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

在即將導覽時觸發。

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

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

    • processId

      數字

      自 Chrome 50 起淘汰

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

      值為 -1。

    • tabId

      數字

      即將進行導覽的分頁 ID。

    • timeStamp

      數字

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

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onCommitted

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

      Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

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

    • processId

      數字

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

    • tabId

      數字

      發生導覽的分頁 ID。

    • timeStamp

      數字

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

    • transitionQualifiers

      TransitionQualifier[]

      轉換限定詞清單。

    • transitionType

      TransitionType

      導覽原因。

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onCompleted

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

      Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

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

    • processId

      數字

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

    • tabId

      數字

      發生導覽的分頁 ID。

    • timeStamp

      數字

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

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onCreatedNavigationTarget

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • sourceFrameId

      數字

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

    • sourceProcessId

      數字

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

    • sourceTabId

      數字

      觸發導覽的分頁 ID。

    • tabId

      數字

      開啟網址的分頁 ID

    • timeStamp

      數字

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

    • 網址

      字串

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

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onDOMContentLoaded

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

      Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

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

    • processId

      數字

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

    • tabId

      數字

      發生導覽的分頁 ID。

    • timeStamp

      數字

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

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onErrorOccurred

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • 錯誤

      字串

      錯誤說明。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

      Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

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

    • processId

      數字

      自 Chrome 50 起淘汰

      這個事件不再設定 processId。

      值為 -1。

    • tabId

      數字

      發生導覽的分頁 ID。

    • timeStamp

      數字

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

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onHistoryStateUpdated

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

      Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

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

    • processId

      數字

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

    • tabId

      數字

      發生導覽的分頁 ID。

    • timeStamp

      數字

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

    • transitionQualifiers

      TransitionQualifier[]

      轉換限定詞清單。

    • transitionType

      TransitionType

      導覽原因。

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onReferenceFragmentUpdated

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      文件所處的生命週期。

    • frameId

      數字

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本 Chrome 148 起為 browser.*

      發生導覽的頁框類型。

    • parentDocumentId

      字串 選填

      Chrome 106 以上版本 Chrome 148 起為 browser.*

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

    • parentFrameId

      數字

      Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

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

    • processId

      數字

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

    • tabId

      數字

      發生導覽的分頁 ID。

    • timeStamp

      數字

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

    • transitionQualifiers

      TransitionQualifier[]

      轉換限定詞清單。

    • transitionType

      TransitionType

      導覽原因。

    • 網址

      字串

• 篩選器

  物件 選填

  • 網址

    events.UrlFilter[]

    瀏覽網址必須符合的條件。

onTabReplaced

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

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

參數

• callback

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • replacedTabId

      數字

      遭取代的分頁 ID。

    • tabId

      數字

      取代舊分頁的分頁 ID。

    • timeStamp

      數字

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