窗口功能迁移

本主题包含与窗口管理相关的指南，包括从 UWP 的“ApplicationView”/或“AppWindow”迁移到 Window 应用 SDK “Microsoft.UI.Windowing.AppWindow”。

重要的 API

• Microsoft.UI.Windowing.AppWindow
• Windows.UI.Core.CoreWindow.Dispatcher 属性
• Microsoft.UI.Window.DispatcherQueue 属性

API 和/或功能差异摘要

Windows App SDK提供基于 Win32 HWND 模型的 Microsoft.UI.Windowing.AppWindow 类。 AppWindow 类是 Windows App SDK 对 UWP 中 ApplicationView、CoreWindow 和 AppWindow 的版本。

若要利用Windows App SDK窗口化 API，这意味着你将迁移 UWP 代码以使用 Win32 模型。 有关 Windows App SDK AppWindow 的详细信息，请参阅 Manage 应用 windows。

UWP 中的窗口类型与Windows App SDK

在 UWP 应用中，可以使用 ApplicationView/ 或 AppWindow 来承载窗口内容。 将代码迁移到Windows App SDK所涉及的工作取决于 UWP 应用使用的这两种开窗模型中的哪一种。 如果熟悉 UWP 的Windows.UI.WindowManagement.AppWindow，你可能会看到它与 Microsoft.UI.Windowing.AppWindow 之间的相似之处。

UWP 窗口类型

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow。
• Windows.UI.WindowManagement.AppWindow。 AppWindow 合并了应用用于显示内容的 UI 线程和窗口。 使用 AppWindow 的 UWP 应用的工作量会比使用 ApplicationView/CoreWindow 的应用在迁移到 Windows App SDK AppWindow 时少。

Windows App SDK窗口类型

• Microsoft.UI.Windowing.AppWindow 是应用内容的系统托管容器的高级抽象。

请记住，UWP 和 Win32 之间的窗口化模型差异意味着 UWP API surface 与 Windows App SDK API surface 之间没有直接的 1：1 映射。 即使是那些确实从 UWP 继承的类和成员名称，并在本主题的映射表中有所体现，其行为也可能有所不同。

初始屏幕

与 UWP 应用不同，Win32 应用默认情况下在启动时不会显示初始屏幕。 依赖于此功能获得启动体验的 UWP 应用可以选择实现到其第一个应用窗口的自定义转换。

创建、显示、关闭和销毁窗口

Microsoft.UI.Windowing.AppWindow 的生存期与 HWND 的生存期相同；这意味着 AppWindow 对象在窗口创建后立即可用，在窗口关闭时销毁。

创建和显示

AppWindow.Create 使用默认配置创建应用窗口。 只有在未使用 UI 框架的情况下，才需要创建和显示窗口。 如果要将 UWP 应用迁移到与 Win32 兼容的 UI 框架，则仍可以使用窗口化互操作方法从已创建的窗口访问 AppWindow 对象。

关闭

在 UWP 中，ApplicationView.TryConsolidateAsync 是用户发起关闭手势的编程等效项。 此合并概念（在 UWP 的 ApplicationViewCoreWindow 窗口化模型中）在 Win32 中不存在。 Win32 不要求窗口存在于单独线程中。 复制 UWP 的 ApplicationViewCoreWindow 窗口化模型需要开发人员创建新线程，并在其中创建新窗口。 在 Win32 模型下，默认系统行为是“关闭”“隐藏”>“销毁”。

基本窗口自定义

从 UWP 迁移到Windows App SDK时，可以从默认 AppWindow 获得相同的体验。 但如果需要，可以更改默认的 Microsoft.UI.Windowing.AppWindow，以获得自定义窗口化体验。 有关如何自定义窗口的详细信息，请参阅 Microsoft.UI.Windowing.AppWindow。

调整窗口大小

定位窗口

窗口标题

紧凑覆盖层和全屏

进入小窗口模式或全屏的应用应利用 Windows App SDK AppWindowPresenter。 如果熟悉 UWP AppWindow，则你可能已熟悉演示器的概念。

没有从 UWP 应用窗口演示者到Windows App SDK应用窗口演示者的功能和行为的 1：1 映射。 如果你具有 UWP ApplicationViewCoreWindow 应用，则仍可在应用中实现紧凑覆盖层（画中画）或全屏窗口化体验，但演示器的概念对你来说可能是新概念。 有关应用窗口演示器的详细信息，请参阅演示器。 默认情况下，AppWindow 在创建时会应用一个重叠的演示器。 除了默认值之外，CompactOverlay 和 FullScreen 是唯一可用的演示器。

紧凑覆盖层

如果使用 UWP 的 ApplicationViewMode 或 AppWindowPresentionKind 呈现紧凑覆盖层窗口，则应使用紧凑覆盖层 AppWindowPresenterKind。 Microsoft.UI.Windowing.CompactOverlayPresenter 仅支持三种 16:9 纵横比的固定窗口大小，用户无法调整大小。 应使用AppWindow.SetPresenter 更改 AppWindow 的呈现，而不是使用 ApplicationViewMode.TryEnterViewModeAsync 或 AppWindowPresenterKind.RequestPresentation。

全屏

如果使用 UWP 的 ApplicationViewWindowingMode 或 AppWindowPresentionKind 类呈现全屏窗口，则应使用全屏 AppWindowPresenterKind。 Windows App SDK仅支持最严格的全屏体验（即当 FullScreen 为 IsExclusive 时）。 对于 ApplicationView/CoreWindow，可以使用 ApplicationView.ExitFullScreenMode 方法使应用从全屏模式退出。 使用演示器时，可以通过使用 AppWindow.SetPresenter 将演示器设置回重叠/默认值，使应用退出全屏。

有关如何使用应用程序窗口管理器的更多详细信息，请参阅窗口库示例。 它演示如何切换不同的应用窗口演示器状态。

自定义标题栏

如果应用使用默认标题栏，则迁移到 Win32 时无需额外的标题栏工作。 另一方面，如果 UWP 应用具有自定义标题栏，则可以在Windows App SDK应用中重新创建以下方案。

1. 自定义系统绘制的标题栏
2. 应用绘制的自定义标题栏

代码从使用 UWP ApplicationViewTitleBar、CoreApplicationViewTitleBar 和 AppWindowTitleBar 类迁移到使用 Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar 类。

自定义系统绘制的标题栏

下面是颜色自定义 API 的表。

除了 AppWindow.Title API 之外，这些Windows App SDK API 还用于进一步自定义系统绘制的标题栏。

• AppWindow.SetIcon. 使用 hIcon 句柄或指向资源或文件的字符串路径设置标题栏和任务栏图标图片。
• 应用窗口标题栏.图标显示选项. 获取或设置一个值，该值指定窗口图标在标题栏中的显示方式。 目前支持两个值 — HideIconAndSystemMenu 和 ShowIconAndSystemMenu。
• AppWindowTitleBar.ResetToDefault. 将当前标题栏重置回窗口的默认设置。

应用绘制的自定义标题栏（完全自定义）

如果要迁移到使用 AppWindowTitleBar，建议在调用以下自定义标题栏 API 之前，在代码中检查 AppWindowTitleBar.IsCustomizationSupported。

这些Windows App SDK API 用于完整标题栏自定义。

• AppWindowTitleBar.SetDragRectangles。 为窗口设置拖动区域。
• AppWindowTitleBar.ResetToDefault. 将当前标题栏重置回窗口的默认设置。

这些 UWP AppWindow API 没有直接的 1：1 映射到 Windows App SDK API。

• AppWindowTitleBarVisibility（应用窗口标题栏可见性）。 定义指定 AppWindowTitleBar 的首选可见性的常量。
• AppWindowTitleBar.GetPreferredVisibility。 检索标题栏的首选可见性模式。
• AppWindowTitleBar.SetPreferredVisibility。 设置标题栏的首选可见性模式。

有关如何使用 AppWindowTitleBar 的更多详细信息，请参阅 Windowing 库示例。 它演示如何创建自定义颜色标题栏以及如何绘制自定义标题栏。

事件处理

如果 UWP 应用使用 AppWindow.Changed 事件，可以将该代码迁移到 Microsoft.UI.Windowing.AppWindow.Changed 事件。

大小更改事件

迁移大小更改的事件处理代码时，应切换到使用 Windows App SDK AppWindowChangedEventArgs.DidSizeChange 属性。 如果应用窗口的大小发生更改，则值为 true；否则为 false。

MainPage 和 MainWindow

在 Visual Studio 中创建新的 UWP project时，project 模板提供 MainPage 类。 对于你的应用，你可能重命名了该类（和/或添加了更多页面和用户控件）。 project模板还提供 App 类方法中的导航代码。

在 Visual Studio 中创建新的Windows App SDK project时， project模板提供一个 MainWindow 类（类型为 Microsoft.UI.Xaml.Window），但没有Page。 project模板不提供任何导航代码。

但是，可以选择将页面和用户控件添加到Windows App SDK project。 例如，可以将新页面项添加到 project（WinUI>Blank Page （WinUI）），并将其命名为 MainPage.xaml 或其他名称。 这将在您的项目中添加一个类型为Microsoft.UI.Xaml.Controls.Page的新类。 然后，有关将导航代码添加到project的信息，请参阅 我是否需要实现页面导航？。

对于足够简单的 Windows App SDK 应用来说，无需创建页面或用户控件，并且可以将 XAML 标记和后台代码复制到 MainWindow。 但有关该工作流的例外情况的信息，请参阅 视觉状态管理器和 Page.Resources。

将 CoreWindow.Dispatcher 更改为 Window.DispatcherQueue

UWP 的 Windows.UI.Core.CoreWindow 类的一些用例迁移到Windows App SDK的 Microsoft.UI.Xaml.Window。

例如，如果在 UWP 应用中使用 Windows.UI.Core.CoreWindow.Dispatcher 属性，则解决方案不是迁移到 Microsoft.UI.Xaml.Window.Dispatcher 属性（始终返回 null）。 而是迁移到 Microsoft.UI.Xaml.Window.DispatcherQueue 属性，该属性返回 Microsoft.UI.Dispatching.DispatcherQueue。

有关详细信息和代码示例，请参阅 将 Windows.UI.Core.CoreDispatcher 更改为 Microsoft.UI.Dispatching.DispatcherQueue。

相关主题

• Windows App SDK和支持的 Windows 版本
• 迁移线程处理功能