本頁面由 Cloud Translation API 翻譯而成。

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 屬性僅保證與「內部」保持一致。比較一個事件與其他事件後，您就能取得這些事件之間的正確偏移值，但如果能將這些事件與擴充功能中的目前時間 (例如透過 (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 範例。

類型

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 以上版本

Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

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 以上版本

Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

活動

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