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 使用者介面中的實際分頁，例如預先算繪的分頁。您無法透過分頁標籤 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 以上版本

導覽原因。系統會使用與 History 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 以上版本

    只有資訊清單 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 以上版本

    只有資訊清單 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

        數字

        導覽觸發所在頁框的 ID，其中包含 sourceTabId。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 紀元時間起算的毫秒數表示。