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

项目
10/15/2024

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

重要链接：

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

最新稳定通道版本：

Windows App SDK 的最新稳定通道发行说明

下载 Windows App SDK

注意

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

版本 1.5.6 （1.5.240802000）

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

修复了有时中断 Min/Max/Close 按钮输入的问题 InputNonClientPointerSource 。有关详细信息，请参阅 GitHub 问题 #9749。
修复了在使用触摸板时关闭窗口时可能出现的崩溃。

版本 1.5.5 （1.5.240627000）

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

修复了在加载完成后更改映像源时映像加载期间可能出现的崩溃。
修复了使用 InputNonClientPointerSource时可能出现的崩溃。
修复了仅包含 WebView2 控件的窗口无法正确将初始键盘焦点设置为 WebView2 的问题，使它无法使用键盘和辅助功能工具。有关详细信息，请参阅 GitHub 问题 WebView2Feedback#2330。

版本 1.5.4 （1.5.240607001）

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

修复了修复 GitHub 问题 #8857 以正确将库 resources.pri 合并到应用的 resources.pri 的问题。
修复了 WebView2 每次单击时发送额外 blur 事件和 focus 事件的问题。有关详细信息，请参阅 GitHub 问题 #9288。这还修复了下拉列表未响应的问题，如 GitHub 问题 #9566 中所示。
修复了创建新窗口或弹出窗口已取消任何正在进行的拖动操作的问题。有关详细信息，请参阅 GitHub 问题 #9360。
修复了定义负视图框的 SVG 文件不再呈现的问题。有关详细信息，请参阅 GitHub 问题 #9415。
修复了在使用弱引用之前未检查 null 的问题x:Bind，这可能会导致崩溃。有关详细信息，请参阅 GitHub 问题 #9551。
修复了以下问题：当窗口最大化时，在标题栏边缘上错误地显示调整光标大小，这也会导致在这些区域中单击或拖动时出现错误行为。有关详细信息，请参阅 GitHub 问题 #8665。

版本 1.5.3 (1.5.240428000)

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

修正了 ItemsRepeater 有时会导致其窗口被移到前面的问题。
修正了更新 AcrylicBrush 的透明度状态时可能出现的故障。
修正了以下问题：如果项目位于比主窗口更高或更宽的 ShouldConstrainToRootBounds="false" 弹出窗口中，则 ItemsRepeater 不会生成足够的项目。
修正了以下问题：如果项目文件未指定 TargetPlatformVersion，则生成时可能会出现错误 MSB4086。此错误是 GitHub 问题 #9531 的一部分。

版本 1.5.2 (1.5.240404000)

它是 Windows 应用 SDK 的维护版本，其中包括针对 1.5 版本的关键 bug 修复以及小组件源提供程序的新功能。

源提供程序现在可在小组件仪表板中显示公告：
- 新的 FeedManager.TryShowAnnouncement API 允许源提供程序请求小组件仪表板显示其公告。若要显示公告，请创建一个 FeedAnnouncement 对象并调用 FeedManager.TryShowAnnouncement API。
- 源公告会将自己的锁屏提醒显示在任务栏中，而这些锁屏提醒可使用 FeedAnnouncement API 进行自定义。
当用户与提供程序交互时，源提供程序现在可选择接收有关其提供程序的分析与错误报表的信息。若要选择加入，请让提供商实现 IFeedProviderAnalytics 和/或 IFeedProviderErrors 接口。

源提供程序更新包括以下新的 API：

Microsoft.Windows.Widgets.Feeds.Providers
 
    FeedAnalyticsInfoReportedArgs
    FeedErrorInfoReportedArgs
    FeedManager
        SendMessageToContent
        TryShowAnnouncement
 
    FeedMessageReceivedArgs
    FeedResourceRequest
    FeedResourceRequestedArgs
    FeedResourceResponse
    IFeedAnnouncementInvokedTarget
    IFeedManager2
    IFeedProviderAnalytics
    IFeedProviderErrors
    IFeedProviderMessage
    IFeedResourceProvider

Microsoft.Windows.Widgets.Notifications
 
    AnnouncementActionKind
    AnnouncementTextColor
    FeedAnnouncement
    FeedAnnouncementInvokedArgs

Bug 修复

已修复以下问题：当主显示器未以 60 Hz 运行时，DispatcherTimer 则不会在正确的时间触发。
已修复以下问题：当以 100% 以外的比例系数运行时，文本框输入法编辑器 (IME) 窗口会出现位置错误。有关详细信息，请参阅 GitHub 问题 #9382。
已修复以下问题：从另一应用启动的拖放操作可能不支持正确的“复制/移动/链接删除”操作。
已修复重置 ListView ItemsSource 并立即突出显示时出现的潜在崩溃问题。
已修复 ShouldConstrainToRootBounds="false" 弹出窗口/浮出控件未应用任何继承的缩放转换的问题。有关详细信息，请参阅 GitHub 问题 #9118 和 #9433。
已修复当合成对象被销毁但仍有动画在运行时出现的潜在崩溃问题。
已修复在 NavigationView::RevokeNavigationViewItemRevokers 中执行关闭时出现的潜在崩溃问题。

版本 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 控件

注意

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

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

新的 SelectorBar 控件

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

WinUI 3 SelectorBar 控件

CommandBarFlyout 主命令中的标签

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

WinUI 3 CommandBarFlyout 标签

针对自定义环境/选项的 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 的拖放支持
- 为了澄清，支持在 1.5 中拖动到 WebView2 中，例如将 PNG 从文件资源管理器拖动到必应进行视觉搜索。工作正在进行 1.6，以支持拖出 WebView2。
对表视图和墨迹控件进行调查

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

已知问题

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

Bug 修复

修复了 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。

通过

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