在桌面应用中托管 UWP XAML 控件（UWP XAML 岛）

重要

本主题使用或提及 CommunityToolkit/Microsoft.Toolkit.Win32 GitHub 存储库中的类型。 有关 UWP XAML 岛支持的重要信息，请参阅该存储库中的 XAML 岛通知。

从版本 1903 Windows 10开始，可以使用名为 UWP XAML Islands 的功能在非 UWP 桌面应用程序中托管 UWP XAML 控件。 借助此功能，可以使用仅通过 UWP XAML 控件提供的Windows UI 功能来增强现有WPF、Windows 窗体和 C++ 桌面（Win32）应用程序的外观、感觉和功能。 这意味着您可以在现有的WPF、Windows 窗体和C++桌面应用程序中使用UWP功能，例如Windows Ink和支持Fluent Design System的控件。

可以托管派生自 Windows.UI.Xaml.UIElement 的任何 UWP XAML 控件，包括：

  • Windows SDK 或适用于 UWP 库的 WinUI 提供的大多数第一方 UWP XAML 控件（请参阅 exceptions）。
  • 任何自定义 UWP XAML 控件（例如，由多个协同工作的 UWP XAML 控件组成的用户控件）。 必须有自定义控件的源代码，才能通过应用程序对其进行编译。

从根本上讲，UWP XAML 岛是使用 UWP XAML 托管 API 创建的。 此 API 由Windows 10版本 1903 SDK 中引入的多个Windows 运行时类和 COM 接口组成。 我们还在Windows Community Toolkit中提供了一组 XAML 岛.NET 控件，这些控件内部使用 UWP XAML 托管 API，并为 WPF 和 Windows 窗体 应用提供更方便的开发体验。

使用 UWP XAML 岛的方式取决于应用程序类型和要托管的 UWP XAML 控件的类型。

要求

UWP XAML 岛具有以下运行时要求：

  • Windows 10版本 1903 或更高版本。
  • 如果你的应用程序未打包到 MSIX 包中用于部署，则必须在计算机上安装 Visual C++ 运行时。

WPF和Windows 窗体应用程序

注释

目前仅在面向 .NET Core 3.x 的应用支持使用 UWP XAML 岛在 WPF 和 Windows 窗体 应用中托管 UWP XAML 控件。 UWP XAML 岛尚不支持那些面向 .NET 的应用程序，也不支持面向任意版本 .NET 框架的应用程序。

我们建议 WPF 和 Windows 窗体 应用程序使用 Windows 社区工具包中提供的 XAML 岛 .NET 控件。 这些控件提供一个对象模型，该模型模拟 （或提供对相应 UWP XAML 控件的属性、方法和事件的访问）。 它们还处理键盘导航和布局更改等行为。

WPF和Windows 窗体应用程序有两组 XAML 岛控件：包装控件和主机控件。

封装控件

WPF 和 Windows 窗体 应用程序可以使用一系列 XAML 岛控件，这些控件封装了特定 UWP XAML 控件的界面和功能。 可以直接将这些控件添加到WPF或Windows 窗体项目的设计界面，然后像在设计器中使用其他任何WPF或Windows 窗体控件一样使用它们。

Windows Community Toolkit 中当前提供了以下包装的 UWP XAML 控件。

控制 支持的 OS 的最低版本 Description
InkCanvas
InkToolbar		 Windows 10版本 1903 在Windows 窗体或WPF桌面应用程序中，提供用于Windows Ink用户交互的界面和相关工具栏。
MediaPlayerElement Windows 10版本 1903 在Windows 窗体或WPF桌面应用程序中嵌入一个用于流式传输和呈现媒体内容（如视频）的视图。
MapControl Windows 10版本 1903 使你可以在Windows 窗体或WPF桌面应用程序中显示符号或照片现实地图。

有关演示如何使用封装的 UWP XAML 控件的详解，请参阅使用 XAML 岛在 C# WPF 应用中托管 UWP XAML 控件。

主机控件

对于功能超出现有封装控件所涵盖范围的自定义控件和其他方案，WPF和Windows 窗体应用程序还可以使用 Windows 社区工具包中提供的 WindowsXamlHost 控件。

控制 支持的 OS 的最低版本 Description
WindowsXamlHost Windows 10版本 1903 可以托管派生自 Windows 的任何 UWP XAML 控件。Ui。Xaml.UIElement，包括由Windows SDK 提供的任何第一方 UWP XAML 控件以及自定义控件。

有关演示如何使用 WindowsXamlHost 控件的演练， 请参阅 使用 XAML 岛在 C# WPF 应用中托管 UWP XAML 控件和 使用 XAML 岛在WPF应用中托管自定义 UWP XAML 控件。

将项目配置为使用 XAML 岛屿 .NET 控件

XAML 岛.NET控件需要 Windows 10 版本 1903 或更高版本。 若要使用这些控件，请安装下面列出的 NuGet 包之一。 这些包提供了使用 XAML 岛包装控件和主机控件所需的一切，并包括其他也是必需的相关 NuGet 包。

控制类型 NuGet 包 相关文章
封装控件 以下包的 6.0.0 版或更高版本： 在 C# WPF 应用中使用 XAML Islands 托管 UWP XAML 控件
主机控件 以下包的 6.0.0 版或更高版本： 在 C# WPF 应用中使用 XAML Islands 托管 UWP XAML 控件
在WPF应用中托管自定义 UWP XAML 控件

请注意以下详细信息：

  • 主机控件包也包括在包装控件包中。 若要使用这两组控件，可以安装包装控件包。

  • 如果要托管自定义 UWP XAML 控件，则还需要执行一些其他步骤来引用自定义控件。 有关详细信息，请参阅使用 XAML 岛在WPF应用中托管自定义 UWP XAML 控件。

网页视图控件

Windows 社区工具包还提供以下.NET控件，用于在WPF和Windows 窗体应用程序中托管 Web 内容。 这些控件通常用于与 XAML 岛控件类似的桌面应用现代化方案，并且它们与 XAML 岛控件位于相同的 Microsoft.Toolkit.Win32 存储库中。

控制 支持的 OS 的最低版本 Description
WebView Windows 10版本 1803 使用 Microsoft Edge 呈现引擎来显示 Web 内容。
WebViewCompatible Windows 7 提供与更多 OS 版本兼容的 WebView 版本。 此控件使用 Microsoft Edge 呈现引擎在 Windows 10 版本 1803 及更高版本上显示 Web 内容，以及 Internet Explorer 呈现引擎在早期版本的 Windows 10、Windows 8.x 和 Windows 7 上显示 Web 内容。

若要使用这些控件，请安装以下 NuGet 包之一：

C++ 桌面 (Win32) 应用程序

C++ 桌面应用程序中不支持 XAML 岛 .NET 控件。 这些应用程序必须使用 Windows 10 SDK （版本 1903 及更高版本）提供的 UWP XAML 托管 API。

UWP XAML 托管 API 由多个Windows 运行时类和 COM 接口组成，C++ 桌面应用程序可用于托管派生自 Windows 的任何 UWP XAML 控件。Ui。Xaml.UIElement。 可以在应用程序中具有关联窗口句柄（HWND）的任何 UI 元素中托管 UWP XAML 控件。 有关此 API 的详细信息，请参阅以下文章。

注释

Windows社区工具包中的包装控件和主机控件在内部使用 UWP XAML 托管 API，并实现你不需要自行处理的所有行为（如果直接使用 UWP XAML 托管 API，包括键盘导航和布局更改）。 对于WPF和Windows 窗体应用程序，强烈建议直接使用这些控件而不是 UWP XAML 托管 API，因为它们会抽象化使用 API 的许多实现详细信息。

UWP XAML 岛屿架构

下面快速了解了如何在 UWP XAML 托管 API 的基础上以体系结构方式组织不同类型的 XAML 岛控件。

主机控件体系结构

此图表底部所示的 API 随 Windows SDK 提供。 包装控件和主机控件可通过 Windows 社区工具包中的 NuGet 包获得。

限制和解决方法

以下部分讨论了使用 UWP XAML 岛桌面应用中某些 UWP 开发方案的限制和解决方法。

仅通过变通方法支持

✔️ 在当前版本的 UWP XAML 岛中，有条件地支持托管来自 WinUI for UWP 库 的控件。 如果桌面应用将 MSIX 包用于部署，则可以承载来自 Microsoft.UI.Xaml NugGet 包的预发行版或发行版的 WinUI 控件。 如果桌面应用不是使用 MSIX 打包的，则只有在安装了 Microsoft.UI.Xaml NuGet 包的预发行版或使用动态依赖项 API 的情况下，才能承载 WinUI 控件。

✔️ 若要access XAML 岛中 XAML 内容树的根元素，并获取其托管上下文的相关信息， 请勿使用 CoreWindow、ApplicationView 和 Window 类。 相反，请使用 XamlRoot 类。 有关详情，请参阅本部分。

若要支持 共享协定，从 WPF、Windows 窗体 或 C++ 桌面（Win32）应用中，您的应用程序必须使用 IDataTransferManagerInterop 接口来获取 DataTransferManager 对象，以启动特定窗口的共享操作。 有关演示如何在WPF应用中使用此接口的示例，请参阅 ShareSource 示例。

不支持在 UWP XAML 岛中使用 x:Bind 与托管控件一起。 必须在.NET标准库中声明数据模型。

不支持

🚫在面向 .NET 框架的 WPF 和 Windows 窗体应用中使用 UWP XAML 岛屿。 UWP XAML 岛仅在面向 .NET Core 3.x 的应用中受支持。

🚫 在 UWP XAML 岛中，UWP XAML 内容在运行时不会响应 Windows 主题从深色切换到浅色或从浅色切换到深色的变化。 内容在运行时能响应高对比度的更改。

🚫 添加 Windows.UI.Xaml.WebView 控件。 有关 WPF 和 WinForms 应用，请参阅这些替代方案 。

🚫 MediaPlayer 控件和 MediaPlayerElement 主机控件在全屏模式下不受支持。

🚫 带手写视图的文本输入。 有关此功能的详细信息，请参阅本文。

🚫 使用 @Places 和 @People 内容链接的文本控件。 有关此功能的详细信息，请参阅本文。

🚫 UWP XAML 岛不支持托管包含接受文本输入的控件的 ContentDialog 例如 TextBox、RichEditBox 或 AutoSuggestBox。 如果这样做，输入控件将无法正确响应按键。 若要使用 XAML Islands 实现类似的功能，建议托管一个包含输入控件的 Popup。

🚫 UWP XAML Islands 当前不支持在托管的 Windows.UI.Xaml.Controls.Image 控件中显示 SVG 文件或使用 Windows.UI.Xaml.Media.Imaging.SvgImageSource 对象。 作为一种解决方法，请将要显示的图像文件转换为基于光栅的格式，如 JPG 或 PNG。

XAML 岛的窗口托管上下文

当您将 UWP XAML 岛托管在桌面应用中时，可以在同一线程上同时运行多个 XAML 内容树。 若要访问 XAML 岛中 XAML 内容树的根元素，并获取有关其托管上下文的相关信息，请使用 XamlRoot 类。 CoreWindow、ApplicationView 和 Window 类不会为 UWP XAML 岛提供正确的信息。 CoreWindow 和 Window 对象在线程上存在并且可供应用访问，但它们不会返回有意义的边界或可见性（它们始终不可见且大小为 1x1）。 有关详细信息，请参阅窗口系统宿主。

例如，要获取包含在 XAML 岛托管的 UWP XAML 控件所在窗口的边界矩形，请使用控件的 XamlRoot.Size 属性。 因为可以在 XAML 岛中托管的每个 UWP XAML 控件都派生自 Windows。Ui。Xaml.UIElement，可以使用控件的 XamlRoot 属性访问 XamlRoot 对象。

Size windowSize = myUWPControl.XamlRoot.Size;

不要使用 CoreWindows.Bounds 属性来获取边界矩形。

// This will return incorrect information for a UWP XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

在 UWP XAML Islands 的上下文中，有一些常见的窗口管理相关 API 是需要避免使用的，推荐使用 XamlRoot 作为替代。有关详细信息，请参阅本节中的表。

有关演示如何在WPF应用中使用此接口的示例，请参阅 ShareSource 示例。

其他资源

有关使用 UWP XAML 岛的详细信息和教程，请参阅以下文章和资源：

  • Last updated on