WPF 应用中的 WebView2 入门

本文介绍如何设置开发工具并为Windows Presentation Foundation (WPF) 创建初始 WebView2 应用,并了解 WebView2 概念。

步骤 1 - 安装Visual Studio

本教程需要Microsoft Visual Studio,而不是Microsoft Visual Studio代码。

  1. 安装Visual Studio 2017 或更高版本。 可以接受默认值。

步骤 2 - 安装预览频道Microsoft Edge

  1. 在受支持的操作系统 (OS) 上下载任何Microsoft Edge预览体验成员 (预览) 频道 (Beta、Dev 或 Canary) :

    • Windows 7
    • Windows 8.1
    • Windows 10
    • Windows 11

    建议使用Microsoft Edge的 Canary 通道。 所需的最低版本为 82.0.488.0。

步骤 3 - 创建单窗口 WebView2 应用

"开始"菜单包含单个主窗口的基本桌面项目。

  1. 打开 Microsoft Visual Studio。

  2. 在打开面板中,单击 “新建项目”。 或者,在主Visual Studio窗口中,选择 FileNew > **** > Project

  3. WPF App搜索 。

    “新建项目”面板显示搜索结果的筛选结果WPF App

  4. 单击) 下方首先显示的 WPF 应用程序卡 (使用 .NET Core/5/6,或 WPF 应用 (.NET Framework) 卡 ( 如下所示,) 使用 .NET Framework,然后单击 “下一步”:

    下图中突出显示的卡片是 WPF 应用程序:.NET Core WPF 应用程序

    选中卡片“WPF 应用程序:.NET Core WPF 应用程序”的“创建新项目”面板。

    或者,下图中突出显示的卡片是 WPF 应用 (.NET Framework) :Windows Presentation Foundation客户端应用程序

    “创建新项目”面板,其中选择了卡片“WPF 应用 (.NET Framework) :Windows Presentation Foundation客户端应用程序”。

    将显示“ 配置新项目 WPF 应用程序”对话框。

    “配置新项目”WPF 应用程序对话框。

  5. 输入Project名称位置的值,然后单击 “下一步”。

    随即显示“ 其他信息 ”对话框,其中包含 “目标框架” 下拉列表:

    包含“目标框架”下拉列表的“其他信息”对话框。

  6. 选择 .NET Core 3.15.06.0 或更高版本 (不是 3.0) 。 然后,单击“下一步”****。

    将显示“ 配置新项目 ”对话框,用于 **WPF 应用 (.NET 框架) **:

    “配置新项目 WPF 应用 .NET Framework”对话框显示项目名称、位置和解决方案名称文本框。

  7. 输入Project名称位置的值。

  8. “框架” 下拉列表中,选择 .NET Framework 4.6.2 或更高版本。

  9. 单击 “创建” 按钮。

    Visual Studio创建项目。

步骤 4 - 安装 WebView2 SDK

使用NuGet将 WebView2 SDK 添加到项目。

  1. 解决方案资源管理器中,右键单击项目名称,然后选择 “管理NuGet包

    右键单击菜单上的“管理NuGet包”命令。

    _ (上面的图像应该显示 WPF 项目,而不是 WinForms 项目。) _

  2. 在左上角,单击“ 浏览” 选项卡。 在搜索栏中键入 Microsoft.Web.WebView2,然后单击 Microsoft.Web.WebView2 卡。

    NuGet包管理器对话框显示搜索结果,包括 Microsoft.Web.WebView2 卡。 对话框具有版本号和 “安装” 按钮。

    NuGet包管理器对话框显示 Microsoft.Web.WebView2 卡。

  3. 接受默认版本,然后单击 “安装 ”按钮。

  4. “预览更改 ”对话框中,单击 “确定”。

  5. 选择 “文件 > 保存全部 ”以保存项目。

  6. F5 生成并运行项目。

    项目运行,并显示一个空窗口。 这会验证 WebView2 是否已安装并正常工作,尽管 WebView2 尚无要显示的内容:

    空应用窗口。

步骤 5 - 创建单个 WebView2 控件

将 WebView2 控件添加到应用。

  1. 在文件中 MainWindow.xaml ,若要添加 WebView2 XAML 命名空间,请在标记中 <Window/> 插入以下行:

    xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
    
  2. 请确保其中 MainWindow.xaml 的代码类似于以下代码:

    <Window x:Class="WPF_Getting_Started.MainWindow"
          xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
          xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
          xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
          xmlns:local="clr-namespace:{YOUR PROJECT NAME}"
          xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"
          mc:Ignorable="d"
          Title="MainWindow"
          Height="450"
          Width="800"
    >
       <Grid>
    
       </Grid>
    </Window>
    
  3. 若要添加 WebView2 控件,请将 <Grid> 标记替换为以下代码。 该 Source 属性设置 WebView2 控件中显示的初始 URI。

    <DockPanel>
       <wv2:WebView2 Name="webView"
                      Source="https://www.microsoft.com"
       />
    </DockPanel>
    
  4. 选择 “文件 > 保存全部 ”以保存项目。

  5. F5 生成并运行项目。

  6. 确保 WebView2 控件显示 https://www.microsoft.com

    WebView2 控件,显示来自 microsoft.com 的网页内容。

步骤 6 - 导航

通过向应用添加地址栏,使用户能够更改 WebView2 控件显示的 URL。

  1. 在文件中 MainWindow.xaml ,通过复制并粘贴包含 WebView2 控件的 <DockPanel> 以下代码来添加地址栏。 将现有代码保留在新代码片段下方。

    <DockPanel DockPanel.Dock="Top">
        <Button x:Name="ButtonGo"
                  DockPanel.Dock="Right"
                  Click="ButtonGo_Click"
                  Content="Go"
        />
        <TextBox Name="addressBar"/>
    </DockPanel>
    
  2. 确保 <DockPanel> 文件的 MainWindow.xaml 节与以下代码匹配:

    <DockPanel>
        <DockPanel DockPanel.Dock="Top">
            <Button x:Name="ButtonGo" DockPanel.Dock="Right" Click="ButtonGo_Click" Content="Go"/>
            <TextBox Name = "addressBar"/>
        </DockPanel>
        <wv2:WebView2 Name = "webView"
                      Source = "https://www.microsoft.com"
        />
    </DockPanel>
    
  3. MainWindow.xaml.cs其中,若要添加 CoreWebView2 命名空间,请在文件顶部插入以下代码:

    using Microsoft.Web.WebView2.Core;
    
  4. 在文件中 MainWindow.xaml.cs,复制以下代码以创建 ButtonGo_Click 该方法。 此代码将 WebView2 控件导航到地址栏中输入的 URL。

    private void ButtonGo_Click(object sender, RoutedEventArgs e)
    {
        if (webView != null && webView.CoreWebView2 != null)
        {
            webView.CoreWebView2.Navigate(addressBar.Text);
        }
    }
    
  5. 直接在声明之后 Public MainWIndow 粘贴代码,如以下代码所示:

    namespace WpfApp1
    {
       /// <summary>
       /// Interaction logic for MainWindow.xaml
       /// </summary>
       public partial class MainWindow : Window
       {
          public MainWindow()
          {
                InitializeComponent();
          }
          void ButtonGo_Click(object sender, RoutedEventArgs e)
          {
                if (webView != null && webView.CoreWebView2 != null)
                {
                   webView.CoreWebView2.Navigate(addressBar.Text);
                }
          }
       }
    }
    
  6. 选择 “文件 > 保存全部 ”以保存项目。

  7. F5 生成并运行项目。

  8. 在地址栏中键入新 URL,然后选择 “Go”。 例如,键入 https://www.bing.com

  9. 确保 WebView2 控件打开输入的 URL。

    请确保在地址栏中输入完整的 URL。 应用生成 URL ArgumentException 未以或https://开头http://的 URL。

    示例应用在地址栏中显示包含 URL https://www.bing.com 的必应网站:

    应用显示必应网站。

步骤 7 - 导航事件

在网页导航期间,WebView2 控件会引发事件。 托管 WebView2 控件的应用侦听以下事件:

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

导航事件,从新文档到导航启动,通过导航完成。

上图显示了事件序列。 导航事件以新文档开头。

成功路径

成功的路径包括事件的完整序列:

  1. 导航开始。
  2. 源已更改,可能来自同一文档的输入。
  3. 内容加载。
  4. 历史记录更改。
  5. 导航已完成。

有关详细信息,请参阅 WebView2 应用的导航事件

故障路径

如果出现故障,则故障路径将直接从导航开始,到导航完成,跳过干预事件。

发生错误时,会引发以下事件,并且可能依赖于导航到错误网页:

  • SourceChanged
  • ContentLoading
  • HistoryChanged

重 定向

如果发生 HTTP 重定向,则一行中有多个 NavigationStarting 事件。

演示导航事件的示例

若要演示如何使用事件,请为此 NavigationStarting 注册处理程序,取消任何非 HTTPS 请求,如下所示。

  1. 在文件中 MainWindow.xaml.cs ,修改构造函数以匹配以下代码的上一部分。 在构造函数下方添加函数 EnsureHttps

    public MainWindow()
    {
        InitializeComponent();
        webView.NavigationStarting += EnsureHttps;
    }
    
    void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
    {
        String uri = args.Uri;
        if (!uri.StartsWith("https://"))
        {
            args.Cancel = true;
        }
    }
    

    在构造函数中, EnsureHttps 在 WebView2 控件上 NavigationStarting 注册为事件处理程序。

  2. 选择 “文件 > 保存全部 ”以保存项目。

  3. F5 生成并运行项目。

  4. 尝试打开 HTTP 站点。 确保 WebView2 控件保持不变。

  5. 尝试打开 HTTPS 站点。 使用 WebView2 控件可以打开 HTTPS 站点。

步骤 8 - 脚本

可以在运行时使用主机应用将 JavaScript 代码注入 WebView2 控件。 可以让 WebView2 运行任意 JavaScript 或添加初始化脚本。 注入的 JavaScript 适用于所有新的顶级文档和任何子帧,直到删除 JavaScript。

注入的 JavaScript 使用特定的计时运行:

  • 创建全局对象后运行它。
  • 在运行 HTML 文档中包含的任何其他脚本之前运行它。

例如,添加在用户导航到非 HTTPS 站点时发送警报的脚本,如下所示:

  1. 修改函数以 EnsureHttps 将脚本注入使用 ExecuteScriptAsync 方法的 Web 内容。

    void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
    {
       String uri = args.Uri;
       if (!uri.StartsWith("https://"))
       {
          webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
          args.Cancel = true;
       }
    }
    
  2. 选择 “文件 > 保存全部 ”以保存项目。

  3. F5 生成并运行项目。

  4. 导航到不使用 HTTPS 的网站时,请确保应用显示警报。

    显示 http:URL 不安全的消息,建议改为尝试 https:URL。

步骤 9 - 主机和 Web 内容之间的通信

主机和 Web 内容可以使用以下方式进行 postMessage通信:

  • WebView2 控件中的 Web 内容可以使用 window.chrome.webview.postMessage>a0>帖子消息发送给主机。 主机使用在主机上注册 WebMessageReceived 的任何消息来处理消息。

  • 在 WebView2 控件中使用或CoreWebView2.PostWebMessageAsJSONCoreWebView2.PostWebMessageAsString消息帖子到 Web 内容。 邮件由添加到 window.chrome.webview.addEventListener的处理程序捕获。

通信机制使用本机功能将消息从 Web 内容传递到主机。

在项目中,当 WebView2 控件导航到 URL 时,它会在地址栏中显示 URL,并向 WebView2 控件中显示的 URL 用户发出警报。

  1. MainWindow.xaml.cs其中,更新构造函数并创建一个 InitializeAsync 函数以匹配以下代码。 函 InitializeAsync 数等待 EnsureCoreWebView2Async,因为初始化是异步的 CoreWebView2

    public MainWindow()
    {
       InitializeComponent();
       webView.NavigationStarting += EnsureHttps;
       InitializeAsync();
    }
    
    async void InitializeAsync()
    {
       await webView.EnsureCoreWebView2Async(null);
    }
    
  2. 初始化 CoreWebView2 后,注册要响应WebMessageReceived的事件处理程序。 在 MainWindow.xaml.cs中,使用以下代码更新 InitializeAsync 和添加 UpdateAddressBar

    async void InitializeAsync()
    {
       await webView.EnsureCoreWebView2Async(null);
       webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
    }
    
    void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
    {
       String uri = args.TryGetWebMessageAsString();
       addressBar.Text = uri;
       webView.CoreWebView2.PostWebMessageAsString(uri);
    }
    
  3. 对于要发送和响应 Web 消息的 WebView2 控件,初始化后 CoreWebView2 ,主机将执行以下操作:

    1. 将脚本注入到注册处理程序以从主机打印消息的 Web 内容。
    2. 将脚本注入到将 URL 发布到主机的 Web 内容。
  4. MainWindow.xaml.cs其中,更新 InitializeAsync 以匹配以下代码:

    async void InitializeAsync()
    {
       await webView.EnsureCoreWebView2Async(null);
       webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
    
       await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
       await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
    }
    
  5. 选择 “文件 > 保存全部 ”以保存项目。

  6. F5 生成并运行项目。

  7. 打开新 URI 时,WebView2 控件会在地址栏中显示 URI。

    示例应用在地址栏和 Microsoft 网站中显示 URI, https://www.microsoft.com:

    示例应用在地址栏和 Microsoft 网站中显示 URI。

恭喜你,你构建了第一个 WebView2 应用!

另请参阅

developer.microsoft.com:

本地页面:

API 参考:

GitHub: