WebView2 应用的导航事件

  • 项目

当 WebView2 应用的用户转到其他网页、URL 或文件路径时，这是一个 导航。 每个导航都会触发一系列与导航相关的事件。 WebView2 应用的本机部分侦听并处理这些导航事件。

当对 WebView2 实例中显示的内容执行特定异步操作时，导航事件将运行。 例如，当 WebView2 用户导航到新网站时，本机内容通过侦听 事件来侦听 NavigationStarting 更改。 导航操作完成后， NavigationCompleted 运行。

支持的平台：Win32、Windows 窗体、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每次成功导航到新文档时，该值都会更改。

具有不同导航 ID 的导航事件可能会重叠。 例如，启动导航事件时，必须等待相关 NavigationStarting 事件。 事件 NavigationStarting 由 NavigationId 对象上的 NavigationStartingEventArgs 属性标识。 如果随后启动另一个导航，将看到以下序列：

  1. 第 NavigationStarting 一个导航的事件。
  2. 第 NavigationStarting 二个导航的事件。
  3. 第 NavigationCompleted 一个导航的事件。
  4. 第二个导航的所有其余适当导航事件。

在错误情况下，可能会有也可能没有 ContentLoading 事件，具体取决于导航是否继续到错误页。

如果发生 HTTP 重定向，则行中存在多个 NavigationStarting 事件，其中后面的事件参数具有 IsRedirect 属性集;但是，导航 ID 保持不变。

同一文档导航事件（例如导航到同一文档中的片段）不会导致 NavigationStarting 触发事件，也不会导致导航 ID 更改。

若要监视或取消 WebView2 实例中帧内的导航事件，请使用等效的帧相关 API 和事件。 请参阅 在 WebView2 应用中使用帧。

有关显示如何处理导航事件的示例代码，请参阅：

  • 了解导航事件 ，请参阅 WinUI 2 中的 WebView2 入门 (UWP) 应用 - 本文中没有示例代码;请参阅其他框架的文章。
  • 步骤 6 -WinUI 3 (Windows 应用 SDK) 应用中 WebView2 入门中的导航事件。
  • 步骤 8 -WPF 应用中 WebView2 入门中的导航事件。
  • 步骤 8 -WinForms 应用中 WebView2 入门中的导航事件。
  • 步骤 14 -Win32 应用中 WebView2 入门中的导航事件。

WebView2 示例应用 还演示了处理导航事件。

另请参阅