Windows 应用 SDK 的稳定通道发行说明

项目
03/03/2024

稳定通道提供支持在生产环境中供应用使用的 Windows 应用 SDK 版本。使用 Windows 应用 SDK 稳定版本的应用还可以发布到 Microsoft Store。

当前提供稳定通道的以下版本：

版本 1.5
版本 1.4
版本 1.3
版本 1.2
版本 1.1
版本 1.0
版本 0.8
版本 0.5

如果要将现有应用从较旧版本的 Windows 应用 SDK 升级到较新版本，请参阅将现有项目更新到 Windows 应用 SDK 的最新版本。

Windows 应用 SDK 下载

注意

Windows 应用 Visual Studio 扩展 (VSIX) 已不再作为单独的下载进行分发。它们可在 Visual Studio 内的 Visual Studio Marketplace 中使用。

版本 1.5

版本 1.5.1 (1.5.240311000)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.5 的关键 bug 修复。

修复了由于无法复制“map.html”而导致独立应用无法构建的问题。
修复了由于拒绝有效令牌而 MapControl 无法初始化的问题。有关详细信息，请参阅 GitHub #9324。
修复了 MapControl 使用蓝色背景加载的问题。有关详细信息，请参阅 GitHub #9377。
修复了单击 NavigationViewItem 的 V 形无法在一次单击中正确展开或折叠的问题。这也导致在 PaneDisplayMode="Top" 模式下单击 V 字形时，菜单显示为空白。有关详细信息，请参阅 GitHub #9423 和 #9426。
修正了一个问题，即使用触控或笔点击 NavigationViewItem 会阻止项目对未来的任何输入做出响应。有关详细信息，请参阅 GitHub #9429。
修复了在 NavigationView.PaneFooter 区域中单击项目时发生的崩溃问题。有关详细信息，请参阅 GitHub #9396。
修复了菜单中的图标有时显示在错误位置的问题。有关详细信息，请参阅 GitHub #9409。
修复了一个问题，即亚克力在从窗口切换回来之前不会显示在菜单上。有关详细信息，请参阅 GitHub #9406。
修复了 TextBox/RichEditBox 初始化期间可能发生的崩溃。有关详细信息，请参阅 GitHub #9216。
修复了 NavigationView 抛出并在销毁时捕获的一些干扰异常。
修复了以下问题：由于 PointerCaptureLost 消息触发不正确，“捏合缩放”手势有时会显示为平移或点击。

版本 1.5

以下部分描述了版本 1.5 的新功能和已更新功能，以及已知问题。

在现有的 Windows 应用 SDK 1.4 应用中，可以将 Nuget 包更新为 1.5.240227000（请参阅使用 NuGet 包管理器在 Visual Studio 中安装和管理包中的更新包部分）。

有关已更新的运行时和 MSIX，请参阅 Windows 应用 SDK 下载。

XAML Islands 运行时和关机更新

WinAppSDK 1.4 和 WinAppSDK 1.5 对于基于 XAML Islands 的应用程序来说，当任何线程上的最后一个 XAML 窗口被关闭时，其行为是不同的。

在 WinAppSDK 1.4 中，当线程上最后一个 XAML 窗口关闭时，XAML 运行时总是退出线程的事件循环。
在 WinAppSDK 1.5 中：
- 如果应用是 WinUI 桌面应用，则默认行为仍与 WinAppSDK 1.4 中的行为相同。
- 如果将 XAML 用于 DesktopWindowXamlSource ("XAML Islands") API，则默认行为现在是 XAML 不会自动退出线程的事件循环。
- 在这两种模式中，都可通过设置 Application.DispatcherShutdownMode 属性来更改此行为。

有关详细信息，请参阅 Application.DispatcherShutdownMode 属性的文档（如果可用）。它可完成 GitHub 建议 #8492。

在 XAML 运行时的生存期内，WinAppSDK 1.4 和 WinAppSDK 1.5 对于基于 XAML Islands 的应用程序之间存在行为差异：

在 WinAppSDK 1.4 中，如果给定线程中的所有 WindowsXamlManager 对象和 DesktopWindowXamlSource 对象都已关闭或关机，或者该线程上运行的 DispatcherQueue 处于关闭状态（在此情况下，XAML 运行时会在 DispatcherQueue.FrameworkShutdownStarting 阶段关闭），则 XAML 运行时会在线程上关闭。
在 WinAppSDK 1.5 中，仅当在该线程上运行的 DispatcherQueue 关闭（XAML 运行时在 DispatcherQueue.FrameworkShutdownStarting 阶段始终会关闭）时，XAML 运行时才会在线程上关闭。

有关详细信息，请参阅 WindowsXamlManager 类的文档（如果可用）。

WindowsXamlManager.InitializeForCurrentThread() 中存在行为差异：

在 WinAppSDK 1.4 中，WindowsXamlManager.InitializeForCurrentThread() 会随每个调用返回 WindowsXamlManager 对象的唯一实例。
在 WinAppSDK 1.5 中，如果线程上已存在一个实例，WindowsXamlManager.InitializeForCurrentThread() 则会返回现有实例。 Close/Dispose() 此时会被忽略。

WinUI Maps 控件

WinUI Maps 控件现已推出！此控件由 WebView2 和 Azure Maps 提供支持，提供以下功能：

使用地图按钮或触控进行平移和缩放。
将地图的样式更改为卫星视图、地形视图或街道视图。
以编程方式向地图添加带有开发人员可自定义图标的可交互图钉。
针对地图在初始加载时居中的位置进行开发人员自定义。
控件，用于开发人员隐藏或显示用于平移、缩放和地图样式的按钮。

WinUI 3 Maps Control

注意

若要使用 Maps 控件，则需要 Azure Maps 密钥。若要创建密钥，请参阅用于创建 Web 应用的 Azure Maps 文档页面。

Maps 控件是一个全新组件，欢迎你提供反馈，评估其未来方向！

新的 SelectorBar 控件

在 1.5 中，我们添加了一个新的 SelectorBar 控件，它允许用户在多个数据视图之间进行切换。此控件以前在 1.5 路线图中被称为“SegmentedControl”。

WinUI 3 SelectorBar Control

CommandBarFlyout 主命令中的标签

现已更新 CommandBarFlyout 的视觉效果，以便在已对 AppBarButton 设置 Label 属性的情况下为主要命令区域中的项目显示文本标签。以前，CommandBarFlyout 区域中的主要命令仅会显示一个图标，但现在它们则可同时显示图标和标签以提高可用性。

WinUI 3 CommandBarFlyout Labels

针对自定义环境/选项的 WebView2 支持

WinUI WebView2 控件现已公开使用自定义 CoreWebView2Environment 和 CoreWebView2ControllerOptions 来自定义基础 CoreWebView2 对象的功能。借助此功能，应用作者便可指定要从中加载 WebView2Runtime、选择使用其他 UserDataFolder 或设置选项（如 IsPrivateModeEnabled 和 ScriptLocale）的备用路径。

针对 .NET 8 的支持

我们在最新的 1.4 服务版本中添加了对 .NET 8 的支持，但仍保留了有关使用特定于平台的 RID 的警告。在 1.5 中，我们已完成此工作，以便该警告不再显示。

改进了调试功能和源可用性

现在，我们已将 Microsoft-ui-xaml 存储库中的代码的 GitHub 源代码服务器信息注入到公共符号中，以便调试器能自动下载源代码。我们还对整个 WinAppSDK 中的符号进行了其他修复和改进，从而改善调试体验。

改进了调试布局循环的对应功能

在 WinUI 应用中调试布局循环可能会成为一个难题，因此在 1.5 中，DebugSettings 对象现在会公开某些选项，以便为布局流程启用改进的日志记录和断点，从而更轻松地调试和修复应用中的布局循环。

WinAppSDK 中的其他新功能

增加了对 PublishSingleFile 部署模型的支持。有关 PublishSingleFile 的详细信息，请参阅单文件部署文档。
添加了对屏幕阅读器支持、文本缩放支持和其他辅助功能的改进。
基于我们优先处理的 GitHub bug 积压工作的各种稳定性与性能改进。

新功能会单独发布

适用于 C# 和 C++ 的 WinAppSDK Visual Studio 模板的新版本现在会通过 Visual Studio Marketplace 进行发布，且会在 1.5 发布后的几周内显示。借助新版本，这些模板现在可独立于 WinAppSDK 版本来发布，从而能更灵活地获取客户的更新。

以前规划的其他功能

在 1.5 中，我们在针对路线图而宣布的以下功能方面取得了进展，但尚未彻底完成。它们将继续进入 1.6 期限。

选项卡式窗口
针对 WebView2 的拖放支持
对表视图和墨迹控件进行调查

动态照明功能已暂时从路线图中删除。

已知问题

使用包含 .xaml 文件等资源的库时，可能会在运行时收到一条错误消息，其中指示未找到这些资源。在此情况下，可能需要在项目文件中插入 <ShouldComputeInputPris>true</ShouldComputeInputPris> 以确保包含这些资源。
单击 NavigationViewItem 的 V 形时，无法再通过单击而正确展开或折叠。双击仍然有效，就像单击 NavigationViewItem 中的其他位置一样。

缺陷修复

修复了 StackPanel 将间距设置应用于折叠项的问题。有关详细信息，请参阅 GitHub 问题 #916。
修复了关闭其他应用窗口后滚动控件不再工作的问题。有关详细信息，请参阅 GitHub 问题 #9292 和 #9355。
修复了在渲染第一帧前将 DebugSettings.EnableFrameRateCounter 设为 true 时出现崩溃的问题。有关详细信息，请参阅 GitHub 问题 #2835。
修复了针对 C++ 的潜在编译错误，其中某些标头未包含必需的依赖项。请注意，#include 顺序更改可能会影响某些应用；例如，如果应用使用的是早于 2023 的 C++/WinRT 版本，则可能会导致 IInspectable 编译错误。有关详细信息，请参阅 GitHub 问题 #9014。
修复了在 ItemsRepeaterDataTemplate 中 ElementName 不起作用的问题。有关详细信息，请参阅 GitHub 问题 #560。
修复了在已启用应用内工具栏的 Visual Studio 下运行应用时出现崩溃的问题。需要 Visual Studio 17.8 预览版 2 或更高版本才能完全获取修补程序。有关详细信息，请参阅 GitHub 问题 #8806。
修复了快速滚动时 AnnotatedScrollbar 有时会崩溃的问题。
修复了菜单文本有时会被截断的问题。
修正了教学提示没有得到适当关注的问题。有关详细信息，请参阅 GitHub 问题 #3257。
修正了在启动时将 TeachingTip 的 TailVisibility 设置为已折叠时应用程序崩溃的问题。有关详细信息，请参阅 GitHub 问题 #8731。
修复了在使用库时有关 PRI 文件处理方式的问题。有关详细信息，请参阅 GitHub 问题 #8857。
修正了 1.5 试验版 2 版本中没有生成投影 DLL 的问题。有关详细信息，请参阅 GitHub 问题 #4152。
修正了以下问题：RichEditBox 的文本格式弹出窗口上的省略号按钮不能正确显示操作列表。有关详细信息，请参阅 GitHub 问题 #9140。
修正了以下问题：ListView 不能正确处理键盘快捷键。有关详细信息，请参阅 GitHub 问题 #8063。
修正了以下问题：使用 AccessKey 关闭窗口时发生访问冲突。有关详细信息，请参阅 GitHub 问题 #8648。
修复了使用 AccessKey 来关闭窗口时出现的崩溃问题。有关详细信息，请参阅 GitHub 问题 #9002。
修正了影响 MenuBar 内 MenuFlyoutItem 中的文本对齐的问题。有关详细信息，请参阅 GitHub 问题 #8755。
修正了右键单击时突出显示的文本不会保持突出显示的问题。有关详细信息，请参阅 GitHub 问题 #1801。
修正了关闭非活动窗口导致应用程序崩溃的问题。有关详细信息，请参阅 GitHub 问题 #8913。
修正了当使用鼠标中键滚动并随后立即单击左键时可能挂起应用程序的问题。有关详细信息，请参阅 GitHub 问题 #9233。
修复了当使用自定义 NavigationViewItem 时导致应用程序启动时崩溃的问题。有关详细信息，请参阅 GitHub 问题 #8814。
修复了省略号按钮会不正确地生成错误的 NavigationView 问题。有关详细信息，请参阅 GitHub 问题 #8380。
修复了在多窗口应用中 SystemBackdrop 无法正确渲染的问题。有关详细信息，请参阅 GitHub 问题 #8423。
修复了当插入到 ObservableCollection 开头时的重复问题。有关详细信息，请参阅 GitHub 问题 #8370。

版本 1.4

版本 1.4.5 (1.4.240211001)

这是 Windows 应用 SDK 的服务版本，其中包含 1.4 版本的严重 bug 修复。

修正了在使用鼠标滚轮滚动时单击鼠标按钮时可能会挂起应用程序的问题。有关详细信息，请参阅 GitHub 问题 #9233。
修正了引用 NuGet 包链时出现重复资产的问题。有关详细信息，请参阅 GitHub 问题 #8857。
修正了以下几个 BreadcrumbBar 问题：包括内存泄露、省略号菜单为空时崩溃，以及省略号菜单在窗口内被错误地约束。
修正了释放图形资源时关闭时可能出现的崩溃。

版本 1.4.4（1.4.231219000）

这是 Windows 应用 SDK 的服务版本，其中包含 1.4 版本的严重 bug 修复。

修复了 WinUI 3 诊断安全问题。
修复了通过触摸激活时密码框不显示屏幕键盘的输入问题。有关详细信息，请参阅 GitHub 问题 #8946。
修复了导致 Microsoft.UI.Xaml.Controls.dll 文件大小意外增长的问题。
修复了设置焦点时可能导致崩溃的 CommandBarFlyout 问题。
更新了对 .NET 8 RID 特定资产处理的 Windows 应用 SDK 支持。
修复了导致某些交换链定位或拉伸错误的问题。

版本 1.4.3 (1.4.231115000)

这是 Windows 应用 SDK 的服务版本，其中包含 1.4 版本的严重 bug 修复。

修复了一个问题：菜单可能会在短时间内以没有背景的形式显示。
修复了特定多显示器场景下可能发生的崩溃。
修复了上下文菜单可能出现在屏幕外的问题。
修复了窗口样式和最大化行为的问题。有关详细信息，请参阅 GitHub 问题 #8996。
修复了 Islands 的一个问题：可能会意外地从另一个控件中夺取焦点。
修复了 NavigationView 上的 Tab 键顺序问题。
修复了标题栏顶部可能会出现白色条的呈现问题。有关详细信息，请参阅 GitHub 问题 #8947。
各种性能修复。

版本 1.4.2 (1.4.231008000)

这是 Windows 应用 SDK 的服务版本，其中包含 1.4 版本的严重 bug 修复。

修复了因内存过多和对象分配而导致的 explorer.exe 崩溃问题。
修复了阻止后退按钮正常工作的标题栏交互问题。
修复了多次包含某个源文件时生成警告的问题。
修复了影响上下文菜单性能的问题。
修复了使目标 .exe 始终指向 WindowsApps 文件夹中包的相同位置的 .lnk 快捷方式问题。
修复了影响以特定字体正确呈现印度语文本的 DWriteCore 问题。
修复了列表视图中无法使用键盘上的 Tab/Shift + Tab 在嵌套的选定项之间正确导航的问题。
修复了第二次展开 ComboBox 后通过触摸中断滚动 ComboBox 项的问题。有关详细信息，请参阅 GitHub 问题 #8831。
修复了 WinAppSDK 包不包含某些语言的 WinUI 本地化资源的问题。
修复了文件资源管理器和 XAML 的用户首选语言的显示方式之间的不一致。
修复了导致活动选项卡下显示细线的文件资源管理器技术问题。
修复了某些框架提供的键盘加速器未正确本地化的问题。有关详细信息，请参阅 GitHub 问题 #2023。
修复了点击时重复滚动的 RepeatButton 控件的问题。
修复了 WinAppSDK 安装程序 .exe，使其具有正确的资源版本信息。

版本 1.4.1 （1.4.230913002）

这是 Windows 应用 SDK 的服务版本，其中包含 1.4 版本的严重 bug 修复。

修复了提高第一帧时间的性能问题。
修复了菜单不顾及 RequestedTheme 的问题。例如，此问题可能导致白色背景上的白色文本。有关详细信息，请参阅 GitHub 问题 #8756。
修复了导致亚克力背景有时在某些菜单中完全透明的问题。
修复了 XAML 有时导致 Windows 不必要地重新画桌面壁纸的问题。
修复了对 ListView 和 GridView 的 TabNavigation = Local 和 TabNavigation = Cycle 的支持，现在除了箭头键外，还可以使用 TAB 在标头和项之间导航。
修复了关闭工具提示时出现的一些干扰异常。有关详细信息，请参阅 GitHub 问题 #8699。

版本 1.4

以下部分描述了版本 1.4 的新功能和已更新功能，以及已知问题。

在现有的 Windows 应用 SDK 1.3 应用中，可以将 Nuget 包更新为 1.4.230822000（请参阅使用 NuGet 包管理器在 Visual Studio 中安装和管理包中的更新包部分）。

有关已更新的运行时和 MSIX，请参阅 Windows 应用 SDK 下载。

自定义标题栏 + AppWindow 标题栏合并

WinUI 3 自定义标题栏使用 AppWindow 标题栏实现，以及 Windows 应用 SDK 1.4 中的 NonClientInputPointerSource API。因此，这两个标题栏现在实现的行为方式都与相同的功能和限制相同。在所有受支持的情况下，这完全向后兼容 - 任何具有自定义标题栏的应用都将像以前一样运行。但是，对于可能不熟悉自定义标题栏的 WinUI 3 开发人员来说，现在利用这些新功能来了解和使用它们变得更加容易：

更好的默认方案，开发人员不专门定义标题栏元素（替换 WinUI 2 中的回退标题栏）
标题栏中的不同拖动区域，使你能够创建多个拖动区域，并将可单击控件放置在非工作区区域的任何部分（标题栏区域）
应用范围的可拖动区域，可放置在应用中的任意位置或使整个应用可拖动
更好的主题支持，用于替换基于资源的主题
- 由于拖动区域是透明的，因此每次都遵循应用主题
更多自定义：隐藏最小值、最大值和关闭按钮；将系统图标置于标题栏中；或具有不同的区域充当接收 NCHITTEST 响应的描述文字按钮
更多开发人员自由度，使你能够混合和匹配 AppWindow 标题栏 API，例如，对大多数方案使用更高级别的 WinUI 3 API，但将 AppWindow API 混合在较低级别的控制中

小组件更新

已为小组件提供程序添加了三个新接口来实现：IWidgetProvider2、IWidgetProviderAnalytics 和 IWidgetProviderErrors。 IWidgetProvider2 允许提供程序响应用户调用的自定义操作，这与第一方小组件可用的操作相同。提供程序使用 IWidgetProviderAnalytics 和 IWidgetProviderErrors 接口收集其小组件的遥测数据；有关小组件的分析和故障事件将传达给相应的小组件提供程序。 WidgetCustomizationRequestedArgs、WidgetAnalyticsInfoReportedArgs 和 WidgetErrorInfoReportedArgs 类用于传达相关信息以支持新功能。

XAML 岛不再为试验性

XAML 岛和基础 ContentIslands 平台不再具有实验性。

目前，XAML 岛仅在 C++ 应用中进行测试以供使用。此版本不包含任何用于 WPF 或 WinForms 的方便的包装元素。
DesktopWindowXamlSource 和相关类型已添加到 XAML 岛的 Microsoft.UI.Xaml.Hosting 命名空间中。添加了 XamlRoot.ContentIslandEnvironment 以帮助访问元素的基础岛信息。
Microsoft.UI.Content 命名空间和 Microsoft.UI.Input 命名空间中引入了许多新类型，作为对 XAML 岛的基础支持，或者使用此 ContentIslands 功能而不使用 XAML。
已为岛方案在 Microsoft.UI.Input.DragDrop 命名空间中添加了新的 DragDropManager（加上相关类型）。

ItemsView

我们引入了一个名为 ItemsView 的新列表控件和相应的具体 ItemContainer 类。 ItemContainer 是一个具有内置选择状态和视觉对象的轻型容器，可以轻松包装所需内容，并可用于集合控件方案的 ItemsView。

新 ItemsView 控件显示数据收集。 ItemsView 类似于 ListView 和 GridView 控件，但使用 ItemsRepeater、ScrollView、ItemContainer 和 ItemCollectionTransitionProvider 组件生成。它提供插入自定义 Layout 或 ItemCollectionTransitionProvider 实现的独特功能。另一个关键优势是能够在保留项目选择的同时动态切换布局。内部 ScrollView 控件还提供在控件 ListView/GridView 的 ScrollViewer 的控件中不可用的功能，例如在编程滚动期间控制动画的功能。
- 使用 ItemsRepeater 的新 ItemTransitionProvider 属性（以及新的 ItemsView 控件），可以指定一个 ItemCollectionTransitionProvider 对象来控制该控件上的过渡动画。 CreateDefaultItemTransitionProvider 方法也已添加到 Layout，这样，如果 ItemsView 控件上未显式提供回退转换，布局对象将提供回退转换。
- Layout 上新的 IndexBasedLayoutOrientation 属性，其中布局方向（如果有）项基于源集合中的索引。默认值为 IndexBasedLayoutOrientation.None。自定义布局通过调用新的（受保护的） SetIndexBasedLayoutOrientation 方法来设置此属性。
- VirtualizingLayoutContext 上的新 VisibleRect 属性获取与 Layout 关联的 FrameworkElement 内的可见视区矩形。可以重写受保护的虚拟 VirtualizingLayoutContext.VisibleRectCore 方法，以提供将从属性返回 VisibleRect 的值。
新 LinedFlowLayout 类通常用于布局集合控件的 ItemsView 项。它特别适用于显示图片集合。它通过将它们从左到右、从上到下布局，以相等的高度行来执行此操作。图片填充水平线，然后换行到下一行。图片可能裁剪左侧和右侧边缘，以适应一行。在采用拉伸模式时，它们还可以水平展开，并裁剪顶部和下边缘以填充线条。

WinAppSDK 中的新功能

允许 Win32 WinRT 应用检测系统高对比度设置何时更改的新 ThemeSettings 类，类似于 UWP 的 AccessibilitySettings 类。有关详细信息，请参阅 GitHub 上的 ThemeSettings API 规范。
AccessKeyManager.EnterDisplayMode 是一种显示所提供根的当前重点元素的访问键的新方法。当显示调用命令的键提示时，访问键处于“显示模式”，例如按“画图”中的 Alt 键以显示哪些键与哪些控件对应。此方法允许以编程方式进入显示模式。
Application.ResourceManagerRequested 提供了一种机制，用于为默认 IResourceManager 不起作用的方案提供不同的 ResourceManager 来解析资源 URI。有关详细信息，请参阅 GitHub 上的 Application.ResourceManagerRequested API 规范。
WebView2 SDK 的版本从 1661.34 更新为 1823.32。
现在支持 Popup/FlyoutBase.IsConstrainedToRootBounds = false，允许弹出窗口/浮出控件扩展到父窗口边界之外。 SystemBackdrop 属性已添加到这些类型，以支持在这些不受约束的弹出窗口中具有亚克力。默认情况下，菜单使用此控件来具有亚克力。
Closed、FrameworkClosed 和 IsClosed 已添加到 DesktopAcrylicController 和 MicaController，以改进对象/线程关闭期间的处理。
现在可以将 DesktopAcrylicController.Kind 设置为在一些标准亚克力外观之间进行选择。
DispatcherQueue 具有一些新事件和帮助程序，以便更好地组织关闭和使用岛的应用轻松运行标准支持的事件循环。
Microsoft.UI.Input 命名空间中的 InputNonClientPointerSource 可用于自定义标题栏方案来定义非工作区区域。代码可以注册相应的事件，例如悬停在这些区域中单击事件。
AppWindow 有一些新的帮助程序来获取和关联 DispatcherQueue。
新 TreeView.SelectionChanged 事件允许开发人员在用户或代码隐藏更改控件中的 TreeView 选定节点集时做出响应。
新 ScrollView 控件提供了 ScrollViewer 的新替代方法。此新控件在行为和 API 中与现有 ScrollViewer 控件高度一致，但基于 InteractionTracker，具有动画驱动视图更改等新功能，还旨在确保完整的 ItemsRepeater 功能。有关更多详细信息，请参阅更灵活的 ScrollViewer · 问题 #108 · microsoft/microsoft-ui-xaml （github.com）。各种新类型（包括 ScrollPresenter）是整体 ScrollView 模型的一部分。
新 AnnotatedScrollBar 控件通过提供一种简单的方法来浏览大型项集合，以扩展常规滚动条的功能。这是通过可单击的滑轨实现的，标签充当标记。它还允许在悬停在可单击的滑轨上时显示工具提示，从而更精细地了解可滚动内容。

已知问题

使用 ExtendsContentIntoTitleBar = true 时，默认情况下，单击窗口的左上角始终显示系统窗口菜单（最小化/关闭/等），而不是让指针输入窗口的内容。例如，这意味着标题栏该区域的“后退”按钮将不起作用。此问题的解决方法是在窗口的 AppWindow 上设置 AppWindow.TitleBar.IconShowOptions = Microsoft.UI.Windowing.IconShowOptions.HideIconAndSystemMenu。
隐藏 ShouldConstrainToRootBounds="False" 弹出窗口/浮出控件时，会出现一些新的可连续异常。这包括隐藏工具提示，如下所示：消除工具提示会引发 4 个本机异常 · 问题 #8699 · microsoft/microsoft-ui-xaml （github.com）
在 1.4 中，AppWindow 而不是 XAML 现在绘制了 ExtendsContentIntoTitleBar = true 的最小/最大/关闭描述文字按钮。这是设计使然，但它可能会影响重写 XAML 的内部样式的应用，以隐藏或执行对这些按钮的额外自定义，例如在此报告中：无法隐藏标题栏 · 问题 #8705 · microsoft/microsoft-ui-xaml （github.com）
.NET 8 中存在中断性变更，它如何处理运行时标识符图：[中断性变更]：面向 .NET 8 及更高版本的项目默认使用更小的可移植 RID 图形。问题 #36527 ·dotnet/docs (github.com)。由于此问题，并且由于 .NET 8 尚未正式发布，因此 Windows 应用 SDK 1.4 不支持 .NET 8。但是，如果仍希望将 .NET 8 的预发行版本与此版本的应用 SDK 为目标，建议执行以下步骤：
- 建议将 UseRidGraph 设置为 true。还需要将 .csproj 文件中的 <RuntimeIdentifiers> 属性更新为 <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>，并更新每个 Propeties\*pubxml 文件，以便从 win10 切换到 <RuntimeIdentifier> 属性中的 win（例如，<RuntimeIdentifier>win-x86</RuntimeIdentifier>）。
使用 Windows 应用 SDK 1.4，Microsoft.WindowsAppSDK.DeploymentManager.CS.targets 中的目标 GenerateDeploymentManagerCS 已重命名为 GenerateBootstrapCS。
MenuFlyout 后台不使用应用程序请求的主题：
- MenuFlyoutItem 文本不会与系统主题同步。 ·问题 #8678 · microsoft/microsoft-ui-xaml （github.com）
- 1.4 预览版：浮出背景主题派生自系统主题，而不是从其关联的元素派生。问题 #8756 · microsoft/microsoft-ui-xaml （github.com）

Bug 修复

修复了调用 Microsoft.Windows.AppLifecycle.AppInstance.Restart("") API 导致解压缩的应用崩溃的问题。有关详细信息，请参阅 GitHub 问题 #2792。
修复了 1.4-experimental1 中引入的安装程序崩溃问题。有关详细信息，请参阅 GitHub 问题 #3760。
修复了 TextBlock 中未正确删除文本删除的问题。有关详细信息，请参阅 GitHub 问题 #1093。
修复了导致面板中 TabFocusNavigation 设置为“一次”的 Shift + Tab 导航错误的问题。有关详细信息，请参阅 GitHub 问题 #1363。
修复了 C++/WinRT 中阻止 {x:Bind} 使用命名 XAML 控件的属性正常工作的问题。有关详细信息，请参阅 GitHub 问题 #2721。
修复了 WinUI 桌面应用中由设置 DebugSettings.EnableFrameRateCounter = true 引起的运行时 AccessViolation 问题。有关详细信息，请参阅 GitHub 问题 #2835。
修复了 XamlTypeInfo.g.cpp 不包含所需标头的问题。有关详细信息，请参阅 GitHub 问题 #4907。
修复了同时多点触控和鼠标输入导致的崩溃问题。有关详细信息，请参阅 GitHub 问题 #7622。
修复了当禁用鼠标悬停上非活动窗口的系统设置已生效时，阻止活动 WinUI 3 应用窗口滚动的问题。有关详细信息，请参阅 GitHub 问题 #8764。
修复了尝试子类 MediaPlayerElement 时出现的崩溃。
修复了 TreeView 中的一些崩溃和内存泄漏问题。
修复了使用键盘在 RadioButtons 中导航时可能发生的应用挂起问题。
修复了使用键盘在 PipsPager 中导航时的崩溃。
修复了使用“设置”应用中的“文本大小”辅助功能设置缩放的 WebView2 内容。
修复了在显示器关闭时动画运行时可能发生的崩溃。
修复了 1.3 中引入的性能问题，该问题为第一个布局/呈现增加了约 10% 的开销。

版本 1.3

版本 1.3.3 （1.3.230724000）

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.3 的关键 bug 修复。

修复了关闭对话框时鼠标有时会停止工作的问题。
修复了由于系统上包版本不匹配而阻止应用安装的部署问题。有关详细信息，请参阅 GitHub 问题 #3740。
修复了影响 Windows 应用 SDK 1.3 中的上下文菜单定位的问题。
修复了导致某些 WinUI3 应用在某些情况下因 XAML 过早关闭而关闭应用时崩溃的问题。
修复了字体图标在从右到左的语言中无法正确镜像的问题。有关详细信息，请参阅 GitHub 问题 #7661。
修复了在资源按错误顺序被拆毁时导致应用在关闭时崩溃的问题。有关详细信息，请参阅 GitHub 问题 #7924。

版本 1.3.2 (1.3.230602002)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.3 的关键 bug 修复。

修复了设置受保护游标时出现的故障。
修复了应用启动期间 XamlMetadataProvider 的性能问题。有关详细信息，请参阅 GitHub 问题 #8281。
修复了 RichTextBlock 中超链接和触控的问题。有关详细信息，请参阅 GitHub 问题 #6513。
修复了 WebView2 中滚动和触控板的问题。有关详细信息，请参阅 GitHub 问题 #7772。
修复了 Windows 应用 SDK 的更新有时需要重启 Visual Studio 的问题。有关详细信息，请参阅 GitHub 问题 #3554。
修复了在调试器中运行时，关闭时出现的干扰异常。

版本 1.3.1 (1.3.230502000)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.3 的关键 bug 修复。

修复了在内容为 null 的情况下设置 SystemBackdrop 时导致应用崩溃的问题。有关详细信息，请参阅 GitHub 问题 #8416。
修复了在 XAML 中设置窗口标题（这是 1.3.0 中添加的新功能）时导致应用崩溃的问题。有关详细信息，请参阅 GitHub 问题 #3689。
修复了窗口在其内容发生更改时错误地获取焦点的问题。
修复了使用 WinAppSDK 1.3 项目模板创建 C++ 项目时出现的问题。
更新了 Visual Studio Marketplace 上的模板

版本 1.3

以下部分描述了版本 1.3 的新功能和已更新功能，以及已知问题。

在现有的 Windows 应用 SDK 1.2 应用中，可以将 Nuget 包更新为 1.3.230331000（请参阅使用 NuGet 包管理器在 Visual Studio 中安装和管理包中的更新包部分）。

有关已更新的运行时和 MSIX，请参阅 Windows 应用 SDK 下载。

XAML 背景 API

借助 XAML 窗口中的内置属性，现在可以更轻松地在 WinUI 3 应用中使用 Mica & Background Acrylic 背景。有关 Xaml 背景属性的详细信息，请参阅系统背景和 Mica 背景 API 文档。

public MainWindow()
{
    this.InitializeComponent();

    this.SystemBackdrop = new MicaBackdrop();
}

Window.AppWindow

现在，只需替换几行样板代码，就可以直接通过 Window.AppWindow 从窗口使用 AppWindow API。

WinAppSDK 中的新功能

ApplicationModel.DynamicDependency：取代已弃用的 MddGetGenerationId 的 PackageDependency.PackageGraphRevisionId。
环境管理器：EnvironmentManager.AreChangesTracked 告知你是否可在应用程序中跟踪对环境管理器的更改。
当无法解析引用的 Static/ThemeResource 查找时，现在会引发新事件 DebugSettings.XamlResourceReferenceFailed。使用此事件可以访问某个跟踪，该跟踪详细说明了在框架中的哪个位置搜索该键，以便更好地调试 Static 和 ThemeResource 查找失败。有关详细信息，请参阅 GitHub 上的跟踪 XAML 资源引用查找失败 API 规范。

其他更新

参阅 WinAppSDK GitHub 上的 WinAppSDK 1.3 里程碑，了解此版本中解决的其他问题。
参阅 microsoft-ui-xaml GitHub 上的 WinAppSDK 1.3 里程碑中的 WinUI 3，了解此版本中解决的其他问题。
现在，使用最新的试验性 VSIX，可以通过 Visual Studio 菜单在未打包和打包之间转换应用，而无需在项目文件中执行此操作。

已知问题

由于最近对 xaml 编译器进行了更改，升级到版本 1.3 的现有项目可能会在 Visual Studio 中遇到如下所示的生成错误：

> C:\Users\user\\.nuget\packages\microsoft.windowsappsdk\\**1.3.230331000**\buildTransitive\Microsoft.UI.Xaml.Markup.Compiler.interop.targets(537,17): error MSB4064: The "PrecompiledHeaderFile" parameter is not supported by the "CompileXaml" task loaded from assembly: Microsoft.UI.Xaml.Markup.Compiler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=de31ebe4ad15742b from the path: C:\Users\user\\.nuget\packages\microsoft.windowsappsdk\\**1.2.230118.102**\tools\net472\Microsoft.UI.Xaml.Markup.Compiler.dll. Verify that the parameter exists on the task, the <UsingTask> points to the correct assembly, and it is a settable public instance property.

此错误的原因是 Visual Studio 使用版本 1.2 中缓存的 xaml 编译器任务 dll，但使用版本 1.3 中不兼容的 MSBuild 逻辑驱动该 dll，如上面的错误文本所示。解决方法是关闭 Visual Studio，重启它，然后重新加载解决方案。