chrome.webNavigation

說明

使用 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 屬性的 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 範例。

類型

TransitionQualifier

Chrome 44 以上版本

列舉

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 以上版本

導航的原因。系統會使用您在 history API 中定義的轉換類型。這些轉換類型與 history API 中定義的轉換類型相同，但以 "start_page" 取代 "auto_toplevel" (是為了回溯相容性)。

列舉

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"start_page"

"keyword_generated"

方法

getAllFrames()

Promise

chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

擷取特定分頁所有影格的相關資訊。

參數

• 詳細資料

  物件

  用於擷取所有影格的分頁相關資訊。

  • tabId

    號碼

    分頁的 ID。

• 回呼

  函式選用

  callback 參數如下所示：

  (details?: object[])=>void

  • 詳細資料

    object[] optional

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

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • errorOccurred

      boolean

      如果這個頁框中的最後一個導覽因發生錯誤而中斷 (也就是引發的 onErrorEventsrred 事件)，則為 True。

    • frameId

      號碼

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

    • frameType

      FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      執行這個影格轉譯器的程序 ID。

    • url

      字串

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

傳回

• Promise<object[]|undefined>

  Chrome 93 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getFrame()

Promise

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。

    • documentLifecycle

      DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • errorOccurred

      boolean

      如果這個頁框中的最後一個導覽因發生錯誤而中斷 (也就是引發的 onErrorEventsrred 事件)，則為 True。

    • frameType

      FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • url

      字串

      目前與這個頁框相關聯的網址 (如果由 frameId 識別的框架在指定分頁的某個時間點存在，則此為目前相關聯的網址)。即使網址與特定的 frameId 相關聯，並不表示對應的頁框仍然存在。

傳回

• Promise<object|undefined>

  Chrome 93 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onBeforeNavigate

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

導覽即將開始時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。特定分頁和程序的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      自 Chrome 50 版起已淘汰的項目

      這個事件不再設定 processId，因為在 onCommit 之前才會確認產生結果文件的程序。

      -1 的值。

    • tabId

      號碼

      即將發生導覽的分頁 ID。

    • timeStamp

      號碼

      瀏覽器結束導覽的時間 (以 Epoch 紀元時間起算，以毫秒為單位)。

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onCommitted

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

執行導覽時觸發。文件 (及其參照的資源，例如圖片和子頁框) 可能仍在下載，但是伺服器至少收到了文件的一部分，瀏覽器決定切換至新的文件。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      Chrome 74 以上版本

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      執行這個影格轉譯器的程序 ID。

    • tabId

      號碼

      發生導覽的分頁 ID。

    • timeStamp

      號碼

      導覽作業完成的時間，以 Epoch 紀元時間起算的毫秒為單位。

    • transitionQualifiers

      TransitionQualifier[]

      轉換限定詞清單。

    • transitionType

      TransitionType

      導航的原因。

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onCompleted

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      Chrome 74 以上版本

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      執行這個影格轉譯器的程序 ID。

    • tabId

      號碼

      發生導覽的分頁 ID。

    • timeStamp

      號碼

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

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onCreatedNavigationTarget

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

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

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • sourceFrameId

      號碼

      含有 sourceTabId 畫面，會在其中觸發導覽的頁框 ID。0 表示主頁框。

    • sourceProcessId

      號碼

      執行來源影格轉譯器的程序 ID。

    • sourceTabId

      號碼

      觸發導覽的分頁 ID。

    • tabId

      號碼

      開啟該網址的分頁 ID

    • timeStamp

      號碼

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

    • url

      字串

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

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onDOMContentLoaded

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

網頁的 DOM 完整建構時觸發，但參照的資源可能無法完成載入。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      Chrome 74 以上版本

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      執行這個影格轉譯器的程序 ID。

    • tabId

      號碼

      發生導覽的分頁 ID。

    • timeStamp

      號碼

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

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onErrorOccurred

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

當發生錯誤且導覽中止時，就會觸發。這可能是因為網路錯誤或使用者中止瀏覽。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • 錯誤

      字串

      錯誤說明。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      Chrome 74 以上版本

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      自 Chrome 50 版起已淘汰的項目

      這個事件的 processId 已不再設定，

      -1 的值。

    • tabId

      號碼

      發生導覽的分頁 ID。

    • timeStamp

      號碼

      發生錯誤的時間 (以 Epoch 紀元時間起算的毫秒為單位)。

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onHistoryStateUpdated

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

影格歷史記錄更新為新網址時觸發。該影格未來的所有事件都會使用更新的網址。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      Chrome 74 以上版本

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      執行這個影格轉譯器的程序 ID。

    • tabId

      號碼

      發生導覽的分頁 ID。

    • timeStamp

      號碼

      導覽作業完成的時間，以 Epoch 紀元時間起算的毫秒為單位。

    • transitionQualifiers

      TransitionQualifier[]

      轉換限定詞清單。

    • transitionType

      TransitionType

      導航的原因。

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onReferenceFragmentUpdated

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

影格的參照片段更新時觸發。該影格未來的所有事件都會使用更新的網址。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • documentId

      字串

      Chrome 106 以上版本

      已載入文件的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 以上版本

      文件的生命週期。

    • frameId

      號碼

      0 表示導覽會在分頁內容視窗中進行，正值代表子頁框中的導覽。分頁中的影格 ID 不得重複。

    • frameType

      extensionTypes.FrameType

      Chrome 106 以上版本

      導覽所在的頁框類型。

    • parentDocumentId

      字串 選用

      Chrome 106 以上版本

      擁有這個頁框的上層文件 UUID。如果沒有父項，就無法設定這個屬性。

    • parentFrameId

      號碼

      Chrome 74 以上版本

      上層頁框的 ID；如果這是主頁框，則為 -1。

    • processId

      號碼

      執行這個影格轉譯器的程序 ID。

    • tabId

      號碼

      發生導覽的分頁 ID。

    • timeStamp

      號碼

      導覽作業完成的時間，以 Epoch 紀元時間起算的毫秒為單位。

    • transitionQualifiers

      TransitionQualifier[]

      轉換限定詞清單。

    • transitionType

      TransitionType

      導航的原因。

    • url

      字串

• 篩選器

  物件選用

  • url

    events.UrlFilter[]

    重新導向的網址必須符合的條件。系統會忽略這個事件的 UrlFilter 的「配置」和「通訊埠」欄位。

onTabReplaced

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

當分頁內容替換為其他 (通常是先前預先算繪) 的分頁時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

  (details: object)=>void

  • 詳細資料

    物件

    • replacedTabId

      號碼

      遭取代分頁的 ID。

    • tabId

      號碼

      取代舊分頁的分頁 ID。

    • timeStamp

      號碼

      取代模式發生的時間 (以 Epoch 紀元時間起算的毫秒為單位)。