用户界面迁移（包括 WinUI 3）
本主题说明如何迁移用户界面 (UI) 代码，包括迁移到 Windows UI 库 (WinUI) 3。
API 和/或功能差异摘要
Window.Current 属性会迁移到 App.Window。 并且 CoreDispatcher.RunAsync 方法也会迁移到 DispatcherQueue.TryEnqueue。
需要在 MessageDialog 和选取器上设置窗口的句柄 (HWND)。
若要使用 DataTransferManager API，需要将它们与窗口进行关联。
对于 ContentDialog 和弹出窗口，需要设置其 XamlRoot 属性。
可能需要重构视觉状态管理器和 Page.Resources XAML 标记。
在 Windows 应用 SDK 中，AcrylicBrush 始终从应用内容中采样。
更改 Windows.UI.Xaml.Window.Current to App.Window
如果 UWP 应用中使用的是 Windows.UI.Xaml.Window.Current 属性，则本部分适用。 Windows 应用 SDK 中不支持此属性，因此本部分介绍如何移植使用 Window.Current 的 UWP 代码。
// MainPage.xaml.cs in a UWP app
var width = Window.Current.Bounds.Width;
// MainPage.xaml.cpp in a UWP app
auto width{ Window::Current().Bounds().Width };
Windows 应用 SDK应用可以使用 App 类上的公共静态属性添加自己的当前窗口或main窗口概念。
// App.xaml.cs in a Windows App SDK app
public partial class App : Application
{
...
public static Window Window { get { return m_window; } }
private static Window m_window;
}
// App.xaml.h in a Windows App SDK app
...
struct App : AppT<App>
{
...
static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };
private:
static winrt::Microsoft::UI::Xaml::Window window;
};
...
// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...
然后，在 App 类本身中，只需将 Window.Current 更改为 window。 在 App 类之外，将 Window.Current 更改为 App.Window，如下所示：
// MainPage.xaml.cs in a UWP app
var width = App.Window.Bounds.Width;
// MainPage.xaml.cpp in a UWP app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };
MessageDialog 和 Pickers
在 UWP 应用中，如果使用来自 Windows.UI.Popups 或 Windows.Storage.Pickers 命名空间的特定类型，则此部分包含有助于迁移该代码的信息。 下面的代码示例使用 MessageDialog，但可以应用完全相同的技术来显示选取器（例如 FileOpenPicker、FileSavePicker 或 FolderPicker）。
显示 依赖于 CoreWindow 的 WinRT UI 对象中介绍了在桌面应用中必须执行的步骤。
注意
对于新应用，建议使用 ContentDialog 控件而不是 MessageDialog。 有关详细信息，请参阅下面的 ContentDialog 和 Popup 部分。
下面是一些用于显示 MessageDialog 的典型 UWP 代码。
// In a UWP app
var showDialog = new Windows.UI.Popups.MessageDialog("Message here");
await showDialog.ShowAsync();
// In a UWP app
auto showDialog{ Windows::UI::Popups::MessageDialog(L"Message here") };
co_await showDialog.ShowAsync();
下面是Windows 应用 SDK应用中的等效代码。
// MainWindow.xaml.cs in a WinUI 3 app
var showDialog = new Windows.UI.Popups.MessageDialog("Message here");
WinRT.Interop.InitializeWithWindow.Initialize(showDialog,
WinRT.Interop.WindowNative.GetWindowHandle(this));
await showDialog.ShowAsync();
// pch.h in a WinUI 3 app
...
#include <Shobjidl.h>
#include <microsoft.ui.xaml.window.h>
#include <winrt/Windows.UI.Popups.h>
...
// MainWindow.xaml.cpp
...
auto showDialog{ Windows::UI::Popups::MessageDialog(L"Message here") };
auto windowNative{ this->m_inner.as<::IWindowNative>() };
HWND hWnd{ 0 };
windowNative->get_WindowHandle(&hWnd);
showDialog.as<::IInitializeWithWindow>()->Initialize(hWnd);
co_await showDialog.ShowAsync();
DataTransferManager
在 UWP 应用中，如果调用 DataTransferManager.ShowShareUI 方法，则本部分包含有助于迁移该代码的信息。
下面是一些调用 ShowShareUI 的典型 UWP 代码。
// In a UWP app
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.GetForCurrentView();
dataTransferManager.DataRequested += (sender, args) =>
{
args.Request.Data.Properties.Title = "In a UWP app...";
args.Request.Data.SetText("...display the user interface for sharing content with another app.");
args.Request.Data.RequestedOperation =
Windows.ApplicationModel.DataTransfer.DataPackageOperation.Copy;
};
Windows.ApplicationModel.DataTransfer.DataTransferManager.ShowShareUI();
// In a UWP app
#include <winrt/Windows.ApplicationModel.DataTransfer.h>
...
auto dataTransferManager{ Windows::ApplicationModel::DataTransfer::DataTransferManager::GetForCurrentView() };
dataTransferManager.DataRequested([](Windows::ApplicationModel::DataTransfer::DataTransferManager const& /* sender */,
Windows::ApplicationModel::DataTransfer::DataRequestedEventArgs const& args)
{
args.Request().Data().Properties().Title(L"In a UWP app...");
args.Request().Data().SetText(L"...display the user interface for sharing content with another app.");
args.Request().Data().RequestedOperation(Windows::ApplicationModel::DataTransfer::DataPackageOperation::Copy);
});
Windows::ApplicationModel::DataTransfer::DataTransferManager::ShowShareUI();
若要在 Windows 应用 SDK 应用中使用 DataTransferManager.ShowShareUI，需要将共享 UI 与窗口关联。 这需要手动完成。 有关详细信息和代码示例，请参阅 显示依赖于 CoreWindow 的 WinRT UI 对象。
ContentDialog 和 Popup
如果在 UWP 应用中使用 Windows.UI.Xaml.Controls.ContentDialog 或 Windows.UI.Xaml.Controls.Primitives.Popup 类，本部分包含有助于迁移该代码的信息。 下面的代码示例使用 ContentDialog，但可以应用完全相同的技术来显示 Popup 对象。
下面是显示 ContentDialog 的一些典型 UWP 代码。
// MainPage.xaml.cs in a UWP app
var unsupportedFilesDialog = new ContentDialog();
// Set Title, Content, etc.
await unsupportedFilesDialog.ShowAsync();
// MainPage.xaml.cpp in a UWP app
ContentDialog unsupportedFilesDialog{};
// Set Title, Content, etc.
co_await unsupportedFilesDialog.ShowAsync();
在 Windows 应用 SDK 应用中，也只需设置对话框的 XamlRoot 属性。 操作方法如下。
// MainPage.xaml.cs in a Windows App SDK app
var unsupportedFilesDialog = new ContentDialog();
// Set Title, Content, etc.
unsupportedFilesDialog.XamlRoot = this.Content.XamlRoot;
await unsupportedFilesDialog.ShowAsync();
// MainPage.xaml.cpp in a Windows App SDK app
ContentDialog unsupportedFilesDialog{};
// Set Title, Content, etc.
unsupportedFilesDialog.XamlRoot(this->Content().XamlRoot());
co_await unsupportedFilesDialog.ShowAsync();
是否需要实现页面导航？
在 UWP 项目中，默认情况下，App 类的方法中将包含导航代码，即使应用简单到只有一个页面。
在 Visual Studio 中创建新 Windows 应用 SDK 项目时，项目模板会提供 MainWindow 类（类型为 Microsoft.UI.Xaml.Window），但是未提供 Page。 并且项目模板未提供任何导航代码。
对于足够简单的 Windows 应用 SDK 应用（单页应用），也许可以对它进行简化。 可能不需要在 Windows 应用 SDK 项目中创建页面或用户控件，而是将该单页的 XAML 标记和后置代码复制到 MainWindow 中。 但是，MainWindow 不支持某些内容。 窗口不是 DependencyObject，因此其上不存在 Resources 和 DataContext 等功能。 加载和卸载等事件也不具有这些功能。 有关详细信息和规避方法，请参阅视觉状态管理器和 Page.Resources。
另一方面，如果你希望或需要在Windows 应用 SDK应用中的页面之间进行导航，则可以通过从 UWP 应用迁移 App.OnLaunched 和 App：：OnNavigationFailed 方法执行此操作。 在 App.OnLaunched 中，找到导航代码（创建 rootFrame 的代码，并导航到应用的第一页）并直接将其合并到两个现有代码行（创建窗口的行，然后激活它）之间。 还需要迁移复制粘贴的代码。 有关简单的代码示例，请参阅 Page 类。
视觉状态管理器和 Page.Resources
另请参阅是否需要实现页面导航？。 如果 UWP 应用简单到可以在其中将 XAML 标记和后置代码复制到 MainWindow 中，请注意这些异常。
MainWindow 类（类型为 Microsoft.UI.Xaml.Window）不是控件，因此它不支持视觉状态管理器 XAML 标记和后置代码（请参阅教程：创建自适应布局）。 不过，有以下两个选项可供选择：
- 将 UserControl 项添加到项目，并迁移标记和后置代码。 然后将该用户控件的实例放在 MainWindow 中。
- 将 Page 项添加到项目，并迁移标记和后置代码。 然后，将代码添加到 App 类以导航到启动时的该页，如是否需要实现页导航？中所述。
此外，无法将元素复制到 <Page.Resources>MainWindow ，只需将其重命名为 <Window.Resources>。 相反，请将 MainWindow 的 XAML 标记中的根布局容器（例如网格）下的“资源”元素作为父级。 效果如下所示：
<Window ...>
<Grid>
<Grid.Resources>...</Grid.Resources>
...
</Grid>
</Window>
AcrylicBrush.BackgroundSource 属性
AcrylicBrush.BackgroundSource属性存在于 UWP 中，但不存在于 Windows 应用 SDK 中。 在 Windows 应用 SDK 中，AcrylicBrush 始终从应用内容中采样。
因此，如果要访问 UWP 应用源代码中的 AcrylicBrush.BackgroundSource 属性（无论是在 XAML 标记中还是命令性代码中），在将应用迁移到 Windows 应用 SDK 时，请删除该代码。 请改用 DesktopAcrylicController 类。
相关主题
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈