WebView2 應用程式的導覽事件

  • 發行項

當 WebView2 應用程式的使用者移至不同的網頁、URL 或檔案路徑時，這是一個 導覽。 每個導覽都會引發一連串的導覽相關事件。 WebView2 應用程式的原生部分會接聽這些導覽事件並加以處理。

導覽事件會在 WebView2 實例中顯示的內容發生特定非同步動作時執行。 例如，當 WebView2 使用者流覽至新的網站時，原生內容會接聽事件來接 NavigationStarting 聽變更。 當導覽動作完成時，會 NavigationCompleted 執行 。

支援的平臺：Win32、Windows Forms、WinUI、WPF。

標準事件序列

以下是巡覽每個步驟期間所引發的一般事件順序：

WebView2 導覽事件

順序 事件 描述 API 參考概觀
1 NavigationStarting WebView2 會開始巡覽，而導覽會產生網路要求。 主機可能會在事件期間不允許要求。 封鎖不想要的導覽
2 SourceChanged WebView2 的來源會變更為新的 URL。 事件可能是因為導覽動作不會造成網路要求，例如片段 導覽。 導覽歷程記錄
3 ContentLoading WebView2 會開始載入新頁面的內容。 導覽事件
4 HistoryChanged 導覽會更新 WebView2 的歷程記錄。 導覽歷程記錄
5 BasicAuthenticationRequested 當 WebView 遇到基本 HTTP 驗證要求時引發。 請參閱 WebView2 應用程式的基本驗證。 驗證
6 DOMContentLoaded WebView2 已完成剖析 DOM 內容，但尚未完成載入頁面上的所有影像、腳本和其他內容。 導覽事件
7 NavigationCompleted WebView2 會完成載入新頁面上的內容。 導覽事件

上圖顯示在個別 eventArgs 物件上具有相同 NavigationId 屬性的導覽事件。

使用每個導覽事件物件的 屬性， NavigationId 追蹤每個新檔的 eventArgs 導覽事件。 每個導覽都牽涉到一連串的流覽事件。 NavigationId每次成功流覽至新檔完成時，值就會變更。

具有不同導覽識別碼的流覽事件可能會重迭。 例如，當您啟動導覽事件時，您必須等候相關 NavigationStarting 事件。 事件 NavigationStarting 是由 NavigationId 物件上的 NavigationStartingEventArgs 屬性所識別。 如果您接著啟動另一個導覽，您會看到下列順序：

  1. 第 NavigationStarting 一次導覽的事件。
  2. 第 NavigationStarting 二個導覽的事件。
  3. 第 NavigationCompleted 一次導覽的事件。
  4. 第二次流覽的其餘適當導覽事件。

在錯誤情況下，可能會有或可能不會 ContentLoading 發生事件，視導覽是否繼續到錯誤頁面而定。

如果發生 HTTP 重新導向，則一個資料列中有多個 NavigationStarting 事件，其中稍後的事件引數會 IsRedirect 設定 屬性;不過，導覽識別碼會維持不變。

相同檔流覽事件，例如流覽至相同檔中的片段，不會引發 NavigationStarting 事件，也不會導致流覽識別碼變更。

若要監視或取消 WebView2 實例中框架內的導覽事件，請使用對等的畫面相關 API 和事件。 請參閱在 WebView2 應用程式中使用畫面。

如需示範如何處理導覽事件的範例程式碼，請參閱：

  • 瞭解 在 WinUI 2 中開始使用 WebView2 (UWP) 應用程式 中的導覽事件 - 文章中沒有範例程式碼;請參閱其他架構的文章。
  • 步驟 6 -在 WinUI 3 中開始使用 WebView2 中的導覽事件 (Windows 應用程式 SDK) 應用程式。
  • 步驟 8 -在 WPF 應用程式中開始使用 WebView2 中的流覽事件。
  • 步驟 8 -在 WinForms 應用程式中開始使用 WebView2 中的流覽事件。
  • 步驟 14 -在 Win32 應用程式中開始使用 WebView2 中的流覽事件。

WebView2 範例應用程式 也會示範如何處理導覽事件。

另請參閱