概述和发行说明：Windows UI 库 3 - Project Reunion 0.8 预览版（2021 年 5 月）

Windows UI 库 (WinUI) 3 是用于构建新式 Windows 应用的原生用户体验 (UX) 框架。 它独立于 Windows 操作系统，作为 Project Reunion（现称为 Windows 应用 SDK）的一部分提供。 0.8 预览版提供 Visual Studio 中的 WinUI 3 模板，可帮助你开始使用基于 WinUI 3 的用户界面构建应用。

WinUI 3 - Project Reunion 0.8 预览版是 WinUI 3 的预发行版本，其中包括 bug 修复、常规改进和实验性的功能，其中一些功能将会稳定化，并在 2021 年 6 月用于 Windows App SDK 0.8 稳定版。

重要

此预览版用于早期评估以及从开发人员社区收集反馈。 它不应该用于生产应用。

如果想使用 Project Reunion 和 WinUI 3 交付生产应用，请参阅概述和发行说明：WinUI 3 - Project Reunion 0.5。

请使用 WinUI GitHub 存储库提供反馈、报告问题并提出建议。

注意

Project Reunion 是 Windows 应用 SDK 的曾用代号。 指代使用此代码名称的旧版本时，本文档仍使用“Project Reunion”。

安装 WinUI 3 - Project Reunion 0.8 预览版

此版本的 WinUI 3 作为 Project Reunion 0.8 预览版的一部分提供。 若要安装，请参阅：

安装 Windows 应用 SDK 的预览和试验通道工具

由于 WinUI 作为 Project Reunion 的一部分提供，你需下载 Project Reunion Visual Studio 扩展 (VSIX) 以开始操作，该扩展中包含一组开发人员工具和组件。 有关 Project Reunion 包的详细信息，请参阅部署使用 Windows App SDK 的应用。 Windows App SDK VSIX 包含你要用于构建 WinUI 3 应用的 Visual Studio 中的 WinUI 3 模板。

注意

若要查看 WinUI 3 控件和功能的运行情况，可从 GitHub 克隆并生成 WinUI 3 控件库，或从 Microsoft Store 进行下载。

设置开发环境后，请参阅 Visual Studio 中的 WinUI 3 模板，熟悉可用的 Visual Studio 项目和项模板。

有关开始构建 WinUI 3 应用的详细信息，请参阅以下文章：

• 创建你的第一个 WinUI 3 项目
• 使用 WinUI 3 和 Win32 互操作生成 C# .NET 应用

除限制和已知问题外，使用 WinUI 项目构建应用与使用 XAML 和 WinUI 2 构建 UWP 应用类似。 因此，有关 UWP 应用和 Windows SDK 中的 Windows.UI WinRT 命名空间的大多数指南文档均适用。

WinUI 3 API 参考文档请参阅此处：WinUI 3 API 参考

WebView2

要将 WebView2 与此 WinUI 3 版本一起使用，请下载在此页上的 Evergreen Bootstrapper 或 Evergreen Standalone Installer（如果尚未安装 WebView2 运行时）。

Windows 社区工具包

如果使用的是 Windows 社区工具包，请下载最新版本。

Visual Studio 支持

为了充分利用添加到 WinUI 3 中的最新工具功能，例如热重载、实时可视化树和实时属性资源浏览器，必须使用 Visual Studio 2019 16.10 的预览版。 请注意，Visual Studio 预览版是预发行版产品，因此在使用 Visual Studio 的预览版生成 WinUI 3 应用时，可能会遇到 bug 和限制。

下表显示了 Visual Studio 2019 版与 WinUI 3 Project Reunion 0.5 的兼容性。

VS 版本	WinUI 3 - Project Reunion 0.5
16.8	否
16.9	是，但没有热重载、实时可视化树或实时属性资源管理器功能
16.10 预览版	是，具有所有 WinUI 3 工具（预览版）

更新现有的 WinUI 3 应用

如果使用早期预览版或稳定版本的 WinUI 3 创建了应用，可更新项目以使用 WinUI 3 - Project Reunion 0.8 预览版。 有关说明，请参阅将现有项目更新到 Project Reunion 的最新版本。

此版本中引入的重大更改

• 现在可在此版本中使用透视表控件。
• 此版本还修复了 Project Reunion v0.5.5、v0.5.6 和 v0.5.7 服务版本中的大部分关键 bug。 对于未在此预览版中完成的服务修复，请参阅已知问题。

WinUI 3 - Project Reunion 0.8 预览版中已修复 bug 的列表

• x:Bind 在自定义 MenuFlyoutItem 中不起作用（一般来说，如果父级名称范围也使用 x:Bind，则 ControlTemplate 中的 x:Bind 不起作用）

  • 感谢 @lhak在 GitHub 上提交了此问题！

• 在顶级窗口（或岛）移动时隐藏窗口式弹出窗口

• WinUI 3 控件库中的 StandardUICommand 页未显示完整内容

• 用鼠标右键单击 TextBox 会导致应用程序崩溃

  • 感谢 @Herdubreid在 GitHub 上提交了此问题！

• 上下文菜单显示在 EditableComboBox 的错误位置

• 通过触摸更改 RichTextBlock 选择会导致选择指示器消失

• 使用 NavigationView 时出现 Microsoft C++ 异常：winrt::hresult_error at memory location 0x...

  • 感谢 @LeftTwixWand在 GitHub 上提交了此问题！

• WinUI 3 错误消息需要改写：“无法解析‘Windows.metadata’。 请安装 Windows 软件开发工具包。 Windows SDK 已随 Visual Studio 一起安装。”

• 引发异常的 VSM 资源库具有反向逻辑

  • 感谢 @HppZ在 GitHub 上提交了此问题！

• 当浏览器进程崩溃时，将焦点移出 WebView2（如有必要）

• 进度栏不显示“暂停”和“错误”选项之间的区别

  • 感谢 @j0shuams在 GitHub 上提交了此问题！

• PointerReplay 持续运行

• NavigationView 导致 UWP 出现崩溃，Reunion 0.5 预览版

  • 感谢 @kalin-todorov在 GitHub 上提交了此问题！

• AutoSuggestBox、ComboBox 和 CommandBarFlyout 未在弹出窗口中设置 ShouldConstrainToRootBounds="false"

• WinUI 3 - Project Reunion 0.5 生成 C# 托管应用的 C++ 异常

  • 感谢 @Noemata在 GitHub 上提交了此问题！

• WebView2 初始选项卡焦点丢失

• 当 DPI 在 Close() 之后发生更改时，WebView2 会崩溃

• AppBarButton 外观改变，浮出控件出现在 WinUI3 中的 CommandBar 上

  • 感谢 @eleanorleffler在 GitHub 上提交了此问题！

过去的 WinUI 3 预览版中引入的特性和功能

以下特性和功能在过去的 WinUI 3 预览版中引入，在 WinUI 3 - Project Reunion 0.8 预览版中继续受支持。

注意

以下功能中的部分功能将继续引入 WinUI 3 预览版，但下一个受支持版本可能不会包含这些功能。 这些功能带有试验标记，且在应用中使用时会引发警告。 在此版本中，属于 WinUI 2.6 预发行版的 API 也带有试验标记。

• 创建使用 WinUI 的桌面应用的功能，包括适用于 Win32 应用的 .NET
• 对生成 UWP 应用的预览级支持
• RadialGradientBrush
• TabView 更新
• 深色主题更新
• 对 WebView2 的改进和更新
  • 支持高 DPI
  • 支持调整窗口大小和移动窗口
  • 已更新为面向较新版本的 Edge
  • 不再需要引用 WebView2 特定的 Nuget 程序包
• SwapChainPanel
• MRT 核心支持
  • 这可使应用在启动时速度更快、更轻质，还能加快资源查找速度。
• Arm64 支持
• 在应用内部和外部进行拖放
• RenderTargetBitmap（目前仅限 XAML 内容 - 无 SwapChainPanel 内容）
• 自定义光标支持
• 线程外输入
• 对我们工具/开发人员体验的改进：
  • 实时可视化树、热重载、实时属性资源管理器及类似工具
  • Intellisense for WinUI 3
• 开放源代码迁移所需的改进
• 自定义标题栏功能：新的 Window.ExtendsContentIntoTitleBar 和 Window.SetTitleBar API，支持开发人员在桌面应用中创建自定义标题栏。
• 虚拟图面图像源支持
• 应用内 Acrylic
• 桌面应用中的多窗口支持
• 输入验证

提供反馈和建议

欢迎在 WinUI GitHub 存储库中提供反馈。

限制和已知问题

WinUI 3 - Project Reunion 0.8 预览版只是一个预览版。 Bug、限制和其他问题是少不了的。

以下各项是 WinUI 3 Project Reunion 0.8 的一些已知问题。 如果发现下面未列出的问题，请在 WinUI GitHub 存储库中，通过为现有问题贡献内容或提交新问题来告知我们。

平台和 OS 支持

WinUI 3 - Project Reunion 0.8 预览版与运行 Windows 10 2018 年 4 月更新（版本 1809 - 内部版本 17763）及更高版本的电脑兼容。

开发人员工具

• 仅支持 C# 和 C++/WinRT 应用。
• 桌面应用支持 .NET 6（或更高版本）和 C# 9，而且必须在 MSIX 应用中打包。
• 不提供 XAML 设计器支持。
• 不支持新的 C++/CX 应用，不过，现有应用可继续运行（请尽快迁移到 C++/WinRT）。
• 不支持未打包的桌面部署。
• 使用 F5 运行桌面应用时，请确保你运行的是打包项目。 在应用项目上按 F5 将运行未打包的应用，而 WinUI 3 尚不支持此类应用。

缺少的平台功能

• Xbox 支持

• HoloLens 支持

• 窗口式弹出窗口

  • 更具体地说，无论属性值如何，ShouldConstrainToRootBounds 属性表现得如同被设置为 true 一样。

• 墨迹支持，包括：

  • InkCanvas
  • HandwritingView
  • InkPresenter

• 背景 Acrylic

• MediaElement 和 MediaPlayerElement

• MapControl

• SwapChainPanel 不支持透明度

• 使用 CompositionBackdropBrush 的 AcrylicBrush 和其他效果无法从 SwapChainPanel 或 WebView2 采样。

• 全局展示使用回退行为，即纯色画笔

• 此版本不支持 XAML 岛

• 直接在现有的非 WinUI 桌面应用中使用 WinUI 3 具有以下限制：用于迁移现有应用的当前可用路径是将新的 WinUI 3 项目添加到解决方案中，并根据需要调整或重构逻辑。

• 不会在桌面应用中调用 Application.Suspending。 有关更多详细信息，请参阅有关 Application.Suspending 事件的 API 参考文档。

• 桌面应用中不再支持 UISettings.ColorValuesChanged 事件和 AccessibilitySettings.HighContrastChanged 事件。 如果使用它来检测 Windows 主题中的更改，可能会导致问题。

• 以前，如果要获取 CompositionCapabilities 实例，需要调用 CompositionCapabilites.GetForCurrentView()。 但是，从此调用返回的功能不依赖于视图。 为了解决并反映此问题，我们已在此版本中删除 GetForCurrentView() 静态，因此现在可以直接创建 CompositionCapabilties 对象。

• 桌面应用中不支持 CoreWindow、ApplicationView、CoreApplicationView、CoreDispatcher 及其依赖项（请参阅下文）

桌面应用中的 CoreWindow、ApplicationView、CoreApplicationView 和 CoreDispatcher

WinUI 3 预览版 4 以及后续标准版中的新增功能 CoreWindow、ApplicationView、CoreApplicationViewCoreDispatcher 及其依赖项在桌面应用中不可用。 例如，Window.Dispatcher 属性始终为 null，但 Window.DispatcherQueue 属性可用作替代项 。

这些 API 仅适用于 UWP 应用。 在过去的预览版中，它们也部分地在桌面应用中工作，但自预览版 4 开始，它们被完全禁用。 这些 API 是针对 UWP 情况设计的，在这种情况下，每个线程只有一个窗口，而未来版 WinUI3 的一个功能就是启用多个窗口。

有一些 API 在内部依赖于这些 API 的存在，因此在桌面应用中不受支持。 这些 API 通常具有静态 GetForCurrentView 方法。 例如 UIViewSettings.GetForCurrentView。

若要详细了解受影响 API 以及这些 API 的变通方法和替代方法，请参阅桌面应用中不支持的 Windows 运行时 API。

已知问题

• 由于 .NET SDK 和 winrt.runtime.dll 的版本不匹配，可能会出现生成错误。 可以尝试下面的解决方法：

  将 .NET SDK 显式设置为正确。 若要确定应用的正确版本，请在项目文件中找到 <TargetFramework> 标记。 通过应用在 <TargetFramework> 标记中面向的 Windows SDK 版本编号（例如 18362 或 19041），将以下项添加到项目文件中，然后保存项目：

  <ItemGroup>            
      <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.{Target Windows SDK Build Number}.16" />
      <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.{Target Windows SDK Build Number}.16" />
  </ItemGroup>
  

  请注意，.NET SDK 5.0.203 及更低版本必须采用此解决方案，但 .NET SDK 5.0.204 或 5.0.300 版本将不需要它。

• 使用 Visual Studio 2019 16.10 预览版 2 时，实时可视化树可能会导致崩溃。 若要避免这种情况，请更新到最新的 Visual Studio 2019 16.10 预览版。

• SetTitleBar 未设置或为 null 时，窗口标题按钮可能会被放置到错误位置

WinUI 3 控件库

查看 WinUI 3 控件库（以前称为 XAML 控件库 - WinUI 3 版本）以获取示例应用，该示例应用包含属于 WinUI 3 Project Reunion 0.8 预览版的所有控件和功能。

WinUI 3 控件库应用的示例

可通过 Microsoft Store 获取 WinUI 3 控件库应用。

也可以通过克隆 GitHub 存储库来下载该示例。 为此，请使用以下命令克隆 winui3 分支：

注意

此 GitHub 存储库中还有一个 winui3preview 分支，该分支提供使用 WinUI 3 - Project Reunion 0.8 预览版的 WinUI 3 控件库版本。

git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git

克隆后，请确保在本地 Git 环境中切换到 winui3 分支：

git checkout winui3

请参阅

• Windows 应用 SDK
• Windows App SDK 的稳定发布渠道
• Windows应用 SDK 示例