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 後隨時觸發。

如果瀏覽方式從「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 屬性僅保證為內部 保持一致比較事件與另一個事件可確保兩者之間的位移正確無誤 比較兩者與目前時間之間的差距 (例如透過 (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 API 的 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

Chrome 44 以上版本

列舉

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 以上版本

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

列舉

"連結"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"已產生"

"start_page"

"form_submit"

"重新載入"

"關鍵字"

「"keyword_generated"」

方法

getAllFrames()

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

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

參數

  • 詳細資料

    物件

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

    • tabId

      數字

      分頁的 ID。

  • 回呼

    函式 選用

    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

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

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

      • processId

        數字

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

      • 網址

        字串

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

傳回

  • Promise<object[] |未定義>

    Chrome 93 以上版本

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

getFrame()

Promise 
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。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 以上版本

        文件所在的生命週期。

      • errorOccurred

        布林值

        如果此影格中的最後一個導覽因為發生錯誤 (即引發 onErrorOccurred 事件) 中斷，則為 True。

      • frameType

        FrameType

        Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

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

      • 網址

        字串

        目前與這個頁框相關聯的網址 (如果 frameId 識別的頁框存在於指定分頁的某個時間點存在)。網址已與指定的 frameId 建立關聯，並不表示相應的影格仍然存在。

傳回

  • Promise&lt;object |未定義>

    Chrome 93 以上版本

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

活動

onBeforeNavigate

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

在即將進行導覽時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

        0 表示瀏覽在分頁內容視窗中發生；正值表示子頁框中的導覽動作。特定分頁和程序的影格 ID 不得重複。

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

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

      • processId

        數字

        自 Chrome 50 版起已淘汰

        系統不會再為這個事件設定 processId，因為在 onCommit 前，算繪產生的文件的程序都不會得知。

        -1 的值。

      • tabId

        數字

        即將發生導覽的分頁 ID。

      • timeStamp

        數字

        瀏覽器開始導航的時間 (從 Epoch 紀元時間起算，以毫秒為單位)。

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onCommitted

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

在執行導覽時觸發。系統可能仍在下載文件 (及其參照的資源，例如圖片和子頁框)，但至少已從伺服器收到文件的部分內容，瀏覽器也決定要改用新的文件。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        Chrome 74 以上版本

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

      • processId

        數字

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

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        進行導航的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。

      • transitionQualifiers

        TransitionQualifier[]

        轉換限定詞清單。

      • transitionType

        TransitionType

        導覽的原因。

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onCompleted

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        Chrome 74 以上版本

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

      • processId

        數字

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

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

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

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

      要瀏覽的網址必須符合的條件。《schemes》和「ports」系統會忽略這個事件的 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 紀元時間起算，以毫秒為單位)。

      • 網址

        字串

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

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onDOMContentLoaded

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        Chrome 74 以上版本

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

      • processId

        數字

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

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

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

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onErrorOccurred

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • 錯誤

        字串

        錯誤說明。

      • frameId

        數字

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

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        Chrome 74 以上版本

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

      • processId

        數字

        自 Chrome 50 版起已淘汰

        這個事件已停止設定 processId。

        -1 的值。

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

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

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onHistoryStateUpdated

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

影格記錄更新為新網址時觸發。該頁框的所有未來事件都將使用更新後的網址。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        Chrome 74 以上版本

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

      • processId

        數字

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

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        進行導航的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。

      • transitionQualifiers

        TransitionQualifier[]

        轉換限定詞清單。

      • transitionType

        TransitionType

        導覽的原因。

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onReferenceFragmentUpdated

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • documentId

        字串

        Chrome 106 以上版本

        載入文件的 UUID。

      • Chrome 106 以上版本

        文件所在的生命週期。

      • frameId

        數字

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

      • Chrome 106 以上版本

        導覽發生的影格類型。

      • parentDocumentId

        string optional

        Chrome 106 以上版本

        擁有此影格的父項文件 UUID。如果沒有父項，則不會設定這個屬性。

      • parentFrameId

        數字

        Chrome 74 以上版本

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

      • processId

        數字

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

      • tabId

        數字

        發生導覽的分頁 ID。

      • timeStamp

        數字

        進行導航的時間 (自 Epoch 紀元時間起算，以毫秒為單位)。

      • transitionQualifiers

        TransitionQualifier[]

        轉換限定詞清單。

      • transitionType

        TransitionType

        導覽的原因。

      • 網址

        字串

  • 篩選器

    物件 optional

    • 網址

      events.UrlFilter[]

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

onTabReplaced

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • replacedTabId

        數字

        被取代的分頁 ID。

      • tabId

        數字

        取代舊分頁的 ID。

      • timeStamp

        數字

        執行取代作業的時間，以 Epoch 紀元時間起算的毫秒數為單位。