WinUI 2 (UWP) 应用中的 WebView2 入门

项目
10/31/2023

在本教程中，你将：

设置开发工具以创建使用 WebView2 显示 Web 内容的 UWP 应用。
创建初始 WinUI 2 (UWP) 应用。
为项目安装 Microsoft.UI.Xaml 包 (WinUI 2) 。
添加显示网页内容的 WebView2 控件。
在此过程中了解 WebView2 概念。

使用 C# 空白应用 (通用 Windows) 项目模板，然后为此项目安装 Microsoft.UI.Xaml 包 (WinUI 2) 。安装该包会将 Microsoft.Web.WebView2 包 (WebView2 SDK) 作为依赖项安装。

Microsoft.UI.Xaml (WinUI 2) 包是 Windows UI 库的一部分。此包提供 Windows UI 功能，包括：

UWP XAML 控件。
密集控件样式。
Fluent 样式和材料。

平台

本文适用于 Windows 和 Xbox。

WinUI 2 仅支持 UWP。这些控件向后兼容。

另请参阅：

适用于 Xbox 的媒体应用示例

已完成的项目

此入门项目 (解决方案) 的已完成版本位于 WebView2Samples 存储库中。可以使用存储库中的已完成解决方案 (，也可以执行以下步骤，) 作为基线来添加更多 WebView2 代码和其他功能。

WebView2Samples 存储库中提供了本教程项目的已完成版本：

示例名称： WinUI2_Sample
存储库目录： WinUI2_GettingStarted
解决方案文件： MyUWPGetStartApp.sln

按以下顺序执行主要步骤部分。

关于 WinUI 和 WebView2

在 WinUI 2 (UWP) 应用中，WebView2 公开为 XAML 控件。将 XAML 控件作为命名控件嵌入应用中后，可以在 C# 文件中引用该 XAML 控件。

WinUI 中只公开一部分 WebView2 接口/函数：

WebView2 XAML 对象公开 CoreWebView2 接口以及最重要的功能。
等 CoreWebView2Controller 接口是隐藏的，因为 WinUI 负责后台的环境和窗口创建。

另请参阅下面的 XAML 限制。

步骤 1 - 安装 Visual Studio

本文介绍 Visual Studio 2022 Community Edition 的步骤和屏幕截图。需要 Microsoft Visual Studio 2019 版本 16.9 或更高版本。不支持 Visual Studio 2017。

如果尚未安装合适的 Microsoft Visual Studio 版本，请参阅在为 WebView2 设置开发环境中的安装 Visual Studio。按照该页中的步骤执行 Visual Studio 的基本默认安装，例如 Visual Studio 2022 Community Edition。

然后返回到此页，继续下面的操作。
如果 Visual Studio 未在代码编辑器中显示行号，则可能需要打开行号。为此，请选择“ 工具>”“选项>”“文本编辑器>”“所有语言>”“行号”。单击" 确定"。

步骤 2 - 安装适用于 .NET 桌面、C++ 桌面和 UWP 开发工具的工作负载

打开 Microsoft Visual Studio。此时会显示打开选项窗口：
在右下角，单击“ 不带代码的继续”。将打开 Visual Studio，为空：
选择 “工具>”“获取工具和功能”。 “Visual Studio 安装程序”窗口随即打开，然后打开“修改 - Visual Studio”窗口：

如果“修改 Visual Studio”窗口未打开，请在Visual Studio 安装程序窗口中单击“修改”按钮。

在“ 工作负载 ”选项卡上，滚动到并单击以下卡片以选择它们：确保每张卡片上都有复选标记：
- .NET 桌面开发
- 使用 C++ 进行桌面开发
- 通用 Windows 平台开发
在右侧的“安装详细信息”部分中，展开“通用 Windows 平台开发”，然后选择“C++ (v143) 通用 Windows 平台工具” ：

如果已安装所有这些组件，请单击“关闭”按钮，关闭Visual Studio 安装程序窗口，然后跳到以下步骤的下一个主要部分。
单击“ 修改” 按钮。

此时会显示 “用户帐户控制 ”窗口，询问“是否允许此应用对设备进行更改？ Visual Studio 安装程序。已验证发布者：Microsoft Corporation。文件来源：此计算机上的硬盘驱动器。显示更多详细信息 (按钮) ”。
单击“ 是 ”按钮。
此时会显示一个对话框，“在开始之前，请关闭 Visual Studio”：
单击“ 继续 ”按钮。

Visual Studio 下载、验证和安装所选包：

此屏幕截图显示了 2022 Visual Studio Professional，但本文实际上是使用 Visual Studio Community 2022 更新的。

安装可能需要几分钟时间。此时会显示 Visual Studio，解决方案资源管理器为空。
按 Alt+Tab 切换到Visual Studio 安装程序窗口，然后关闭Visual Studio 安装程序窗口。

步骤 3 - 创建 UWP 应用

如果 Visual Studio 处于打开状态，请选择“ 文件>新建>项目”。此时会打开 “创建新项目 ”对话框。

或者，如果 Visual Studio 已关闭，请将其打开，然后在 Visual Studio 的启动屏幕中，单击“创建新项目”卡：
在顶部的“搜索模板”文本框中，输入“C# 空白应用 (通用 Windows) ”，然后选择“C# 空白应用 (通用 Windows) 卡：
单击“ 下一步 ”按钮。

对于空白应用 (通用 Windows) ，将显示“配置新项目”对话框：
在“ 项目名称 ”文本框中，输入项目名称，例如 MyUWPGetStartApp。
在“ 位置 ”文本框中，输入路径，例如 C:\Users\myusername\Documents\MyWebView2Projects。
单击“创建”按钮。

此时将显示 “新建 Windows 项目 ”对话框：
接受默认值，然后单击“ 确定 ”按钮。
如果显示 “开发人员模式 ”窗口部分，请在该部分中单击“ 开”。如果尚未将计算机设置为开发人员模式，则会打开 “使用开发人员功能 ”对话框，以确认打开开发人员模式。
- 单击“ 是 ”打开计算机的开发人员模式，然后关闭 “设置” 窗口。
Visual Studio 显示新创建的解决方案和项目：

步骤 4 - 生成并运行空项目

添加 WebView2 代码之前，请确认项目是否正常工作，并查看空应用的外观，如下所示：

生成并运行空项目。为此，请选择“ 调试>开始调试 ” (F5) 。应用窗口随即打开，暂时显示网格，然后显示应用的内容：

这是一个基线 WinUI 2 (UWP) 应用，目前没有 WebView2。
关闭应用。

接下来，设置此新的 WinUI 2 (UWP) 项目来托管 WebView2 控件并使用 WebView2 API。

步骤 5 - 安装 WinUI 2 SDK (Microsoft.UI.Xaml)

接下来，安装此项目的 Microsoft.UI.Xaml 包。 Microsoft.UI.Xaml 为 WinUI 2。

在解决方案资源管理器中，右键单击项目 (而不是其上方) 的解决方案节点，然后选择“管理 NuGet 包”。

“NuGet 包管理器”面板在 Visual Studio 中打开。
在 NuGet 包管理器中，单击“ 浏览 ”选项卡。
清除“包括预发行检查”框。
在“搜索”框中，输入 Microsoft.UI.Xaml，然后选择搜索框下方的 Microsoft.UI.Xaml 卡：

对于版本 2.8.0 或更高版本，在底部的 “依赖项 ”部分中列出了 Microsoft.Web.WebView2 。

对于HoloLens 2开发，Microsoft.Web.WebView2 包的版本必须为 1.0.1722.45 或更高版本，这可能高于默认值。 HoloLens 2 上的 WebView2 处于预览状态，在正式发布之前可能会更改。 WebView2 仅在运行Windows 11更新HoloLens 2设备上受支持。有关详细信息，请参阅更新HoloLens 2。
在中间面板中的 “版本 ”下拉列表中，确保选择了 “最新稳定 ”版本 2.8.0 或更高版本。
单击“ 安装 ”按钮。

此时将显示 “预览更改 ”对话框：
单击“ 确定” 按钮。
此时会显示 “接受许可证 ”对话框：
单击“ 我接受 ”按钮。在 Visual Studio 中 readme.txt ，显示文件，指出已安装 WinUI 包：

自述文件列出了一些类似于我们将添加的代码行。
(Ctrl+Shift+S) 选择“文件>保存所有”。

现在，你已为项目安装了 Microsoft.UI.Xaml 包，即 WinUI 2。 WinUI 2 SDK (Microsoft.UI.Xaml) 包含 WebView2 SDK，因此无需单独安装用于 WebView2 SDK 的 NuGet 包。

步骤 6 - 在 XAML 代码中实例化 WebView2 控件

现在可以向项目添加 WebView2 代码了。首先，为 WebView2 控件添加命名空间引用，如下所示：

在“解决方案资源管理器”中，展开项目，然后双击“MainPage.xaml”。

MainPage.xaml 在设计器中打开，其下方有一个代码编辑器：
在代码编辑器中，在 <Page> 元素的 start 标记 <Page内，在其他 xmlns: 属性下面添加以下属性：
```
xmlns:controls="using:Microsoft.UI.Xaml.Controls"
```
将 WebView2 控件添加到 XAML 网格，如下所示：
在 MainPage.xaml 文件中，在 <Grid> 元素 (（该元素尚未包含其他元素) ）中，通过添加以下元素来添加 WebView2 控件：
```
<controls:WebView2 x:Name="WebView2" Source="https://bing.com"/>
```
按 Ctrl+S 保存文件。

MainPage.xaml在代码编辑器中的文件上方，可能会显示 WebView2 控件内容的预览，或者它可能保持空白 (白色) ，直到你首次生成应用：

下一步，生成并运行应用后，波浪下划线会消失。

步骤 7 - 生成并运行包含 WebView2 控件的项目

单击“ 调试>启动调试 ” (F5) 。 (如果为HoloLens 2生成，请参阅使用 Visual Studio 部署和调试) 。应用窗口随即打开，简要显示 WebView2 WebUI 网格：
片刻后，应用窗口在 WebUI 2 的 WebView2 控件中显示必应网站：
在 Visual Studio 中，选择“ 调试>停止调试” 以关闭应用窗口。

恭喜，你构建了第一个 WebView2 应用！

现在，可以更改 WebView2 控件的内容以添加自己的内容。

接下来，了解对 WebView2 应用至关重要的导航事件。应用最初导航到 https://bing.com。

在新窗口或选项卡中，阅读 WebView2 应用的导航事件，然后返回到此页面。

WinUI 2 (UWP) 上的 WebView2 的特殊注意事项

WebView2 WinUI 2 (UWP) 控件正在开发中。

自动填充 UI

UWP 应用的 WebView2 尚未实现自动填充 UI。

另请参阅：

WebView2 功能和 API 概述中的自动填充。

打印为 PDF

打印到 PDF 要求应用有权访问 UWP 中的可写位置，例如本地文件夹。有关 UWP 可访问路径的完整列表，请参阅文件访问权限。

另请参阅：

WebView2 功能和 API 概述中的打印。

默认打印

对 UWP 应用的 WebView2 禁用默认打印。但是，可以通过调用 CapturePreview来捕获和打印当前视区。

另请参阅：

WebView2 功能和 API 概述中的图像捕获。

SmartScreen

WebView2 将应用程序中导航到的 URL 发送到 SmartScreen 服务，以确保客户保持安全。如果要禁用此导航，可以通过环境变量执行此操作：

Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

必须在创建之前 CoreWebView2 设置此环境变量，这在最初设置 WebView2.Source 属性或最初调用 WebView2.EnsureCoreWebView2Async 方法时发生。

下载文件

UWP 中 WebView2 的当前下载行为存在几个已知限制。

另存为

通过 “另存为” 保存文件是正常工作的，并且已为 UWP 应用的 WebView2 启用。文件将保存在用户选择的文件夹中。

文件下载到哪个文件夹

如果主机不更改 ResultFilePath 已下载文件的，则下载的文件将下载到文件夹中具有应用包名称 Downloads 的子文件夹中。

如果主机更改 ResultFilePath 已下载文件的，则仅当应用默认有权访问该文件路径时，才会下载该文件。如果要使用默认情况下应用无权访问的文件位置，则必须设置相应的功能。请参阅 UWP 文档中的应用功能声明。

下载中心

禁用从下载中心打开文件和文件夹。单击文件或文件夹图标不会打开相应的文件/文件夹。

另请参阅：

WebView2 功能和 API 概述中的下载内容。

XAML 限制

XAML 岛支持需要额外的工作，并可能考虑在未来的版本。

设置 DefaultBackgroundColor

在 WinUI 2 上 DefaultBackgroundColor ，不会直接公开属性。可以通过设置环境变量来设置默认背景色，如下所示：

Environment.SetEnvironmentVariable("WEBVIEW2_DEFAULT_BACKGROUND_COLOR", "FF000000");

另请参阅：

.NET： WebView2.DefaultBackgroundColor 属性
Win32： ICoreWebView2Controller2：:D efaultBackgroundColor 属性 (get，put )

设置透明度

在 WinUI 2 上，通过将颜色设置为 00FFFFFF来实现透明度。

CSS 游标

在 WinUI 2 (UWP) 上，CSS 游标具有以下限制。

图像 URL

CSS 游标不能是图像 URL，例如 cursor: url(https://contoso.com/cursor.png), pointer;。请参阅 CSS - 从 URL 加载的游标不起作用。

预定义 CSS 游标

在 WinUI 2 (UWP) 上，不支持某些预定义 CSS 游标。可以使用 CSS 游标将游标更改为某些预定义游标，例如 cursor: wait; 或 cursor: crosshair;，但不能更改为其他游标，例如 cursor: progress 或 cursor: none。

关键字	是否支持？
常规
自动	✔️
默认	✔️
无	❌
链接 & 状态
context-menu	✔️
帮助	✔️
指针	✔️
progress	❌
等	✔️
Selection
细胞	❌
十字线	✔️
text	✔️
vertical-text	❌
拖放 &
别名	❌
复制	❌
move	✔️
no-drop	✔️
不允许	✔️
抓住	❌
抓住	❌
调整 & 滚动大小
all-scroll	✔️
col-resize	❌
row-resize	❌
n-resize	✔️
e-resize	✔️
s-resize	✔️
w-resize	✔️
ne-resize	✔️
nw-resize	✔️
se-resize	✔️
sw-resize	✔️
ew-resize	✔️
ns-resize	✔️
nesw-resize	✔️
nwse-resize	✔️
缩放
放大缩小字体功能放大缩小字体功能	❌
放大缩小字体功能	❌

另请参阅：

CSS 游标 - 值部分描述上述关键字 (keyword) 值。

Microsoft Edge 开发人员工具

在 WinUI 2 上，Microsoft Edge DevTools 无法在应用商店签名的 WebView2 WinUI 2 (UWP) 应用中启动。但是，可以使用远程调试来解决此问题。请参阅远程调试 WebView2 WinUI 2 (UWP) 应用。

API 限制

以下类在 WinUI 2 中不可访问：

CoreWebView2EnvironmentOptions
CoreWebView2ControllerOptions

另请参阅

WebView2 API 参考
WinUI 2 (UWP) 示例应用 - 下载、更新、生成和运行 WinUI 2 WebView2 示例的步骤。
管理用户数据文件夹
WebView2 的示例代码 - 存储库指南 WebView2Samples 。
WebView2 应用开发最佳做法

GitHub：

WebView2Samples 存储库
WebView2 UWP 示例应用 - WinUI 2 (UWP) WebView2 示例。
输入特定于 WinUI 的功能请求或 bug 的问题 - microsoft-ui-xaml 存储库。
与其他一些教程不同，WebView2Samples 存储库中没有此入门教程的完整版本。
Microsoft.UI.Xaml NuGet 包
适用于 Xbox 的媒体应用示例

WinUI 2 (UWP) 应用中的 WebView2 入门

平台

已完成的项目

关于 WinUI 和 WebView2

步骤 1 - 安装 Visual Studio

步骤 2 - 安装适用于 .NET 桌面、C++ 桌面和 UWP 开发工具的工作负载

步骤 3 - 创建 UWP 应用

步骤 4 - 生成并运行空项目

步骤 5 - 安装 WinUI 2 SDK (Microsoft.UI.Xaml)

步骤 6 - 在 XAML 代码中实例化 WebView2 控件

步骤 7 - 生成并运行包含 WebView2 控件的项目

了解导航事件

WinUI 2 (UWP) 上的 WebView2 的特殊注意事项

自动填充 UI

打印为 PDF

默认打印

SmartScreen

下载文件

另存为

文件下载到哪个文件夹

下载中心

XAML 限制

设置 DefaultBackgroundColor

设置透明度

CSS 游标

图像 URL

预定义 CSS 游标

Microsoft Edge 开发人员工具

API 限制

另请参阅

其他资源