在桌面应用中托管 UWP XAML 控件(XAML 孤岛)Host UWP XAML controls in desktop apps (XAML Islands)

从 Windows 10 版本1903开始,你可以使用一个名为XAML 孤岛的功能在非 UWP 桌面应用程序中托管 UWP 控件。Starting in Windows 10, version 1903, you can host UWP controls in non-UWP desktop applications using a feature called XAML Islands. 利用此功能,你可以使用仅可通过 UWP 控件获取的最新 Windows 10 UI 功能增强C++现有 WPF、Windows 窗体和 Win32 应用程序的外观和功能。This feature enables you to enhance the look, feel, and functionality of your existing WPF, Windows Forms, and C++ Win32 applications with the latest Windows 10 UI features that are only available via UWP controls. 这意味着,可以使用 UWP 功能,如Windows 墨迹和控件,这些功能支持现有 WPF、Windows 窗体和C++ Win32 应用程序中的熟知设计系统This means that you can use UWP features such as Windows Ink and controls that support the Fluent Design System in your existing WPF, Windows Forms, and C++ Win32 applications.

你可以承载从Windows派生的任何 UWP 控件,其中包括:You can host any UWP control that derives from Windows.UI.Xaml.UIElement, including:

  • Windows SDK 或 WinUI 库提供的任何第三方 UWP 控件。Any first-party UWP control provided by the Windows SDK or WinUI library.
  • 任何自定义 UWP 控件(例如,包含多个可一起工作的 UWP 控件的用户控件)。Any custom UWP control (for example, a user control that consists of several UWP controls that work together). 您必须具有自定义控件的源代码,以便可以使用您的应用程序进行编译。You must have the source code for the custom control so you can compile it with your application.

从根本上讲,使用UWP xaml 宿主 API创建了 xaml 孤岛。Fundamentally, XAML Islands are created by using the UWP XAML hosting API. 此 API 包含 Windows 10 版本 1903 SDK 中引入的几个 Windows 运行时类和 COM 接口。This API consists of several Windows Runtime classes and COM interfaces that were introduced in the Windows 10, version 1903 SDK. 我们还在Windows 社区工具包中提供一组 XAML 岛 .net 控件,这些控件在内部使用 UWP XAML 宿主 API 并为 WPF 和 Windows 窗体应用提供更方便的开发体验。We also provide a set of XAML Island .NET controls in the Windows Community Toolkit that use the UWP XAML hosting API internally and provide a more convenient development experience for WPF and Windows Forms apps.

使用 XAML 孤岛的方式取决于您的应用程序类型和要承载的 UWP 控件类型。The way you use XAML Islands depends on your application type and the types of UWP controls you want to host.

备注

如果你有关于 XAML 孤岛的反馈,请在Microsoft 工具包存储库中创建一个新问题,并在此处留下你的意见。If you have feedback about XAML Islands, create a new issue in the Microsoft.Toolkit.Win32 repo and leave your comments there. 如果你想要私下提交反馈,则可以将其发送到 XamlIslandsFeedback@microsoft.com。If you prefer to submit your feedback privately, you can send it to XamlIslandsFeedback@microsoft.com. 你的见解和方案对我们至关重要。Your insights and scenarios are critically important to us.

WPF 和 Windows 窗体应用程序WPF and Windows Forms applications

建议 WPF 和 Windows 窗体应用程序使用 Windows 社区工具包中提供的 XAML 岛 .NET 控件。We recommend that WPF and Windows Forms applications use the XAML Island .NET controls that are available in the Windows Community Toolkit. 这些控件提供一个对象模型,用于模拟(或提供对)相应 UWP 控件的属性、方法和事件的访问。These controls provide an object model that mimics (or provides access to) the properties, methods, and events of the corresponding UWP controls. 它们还处理键盘导航和布局更改等行为。They also handle behavior such as keyboard navigation and layout changes.

WPF 和 Windows 窗体应用程序有两组 XAML 岛控件:包装控件宿主控件There are two sets of XAML Island controls for WPF and Windows Forms applications: wrapped controls and host controls. 从 Windows 10 版本1903,这些控件作为开发人员预览版提供As of Windows 10, version 1903, these controls are available as a developer preview.

包装控件Wrapped controls

WPF 和 Windows 窗体应用程序可以使用包装特定 UWP 控件的界面和功能的 XAML 岛控件选择。WPF and Windows Forms applications can use a selection of XAML Island controls that wrap the interface and functionality of a specific UWP control. 可以直接将这些控件添加到 WPF 或 Windows 窗体项目的设计图面上,然后在设计器中将其与任何其他 WPF 或 Windows 窗体控件一起使用。You can add these controls directly to the design surface of your WPF or Windows Forms project and then use them like any other WPF or Windows Forms control in the designer.

下面的已包装 UWP 控件目前在 Windows 社区工具包中可用。The following wrapped UWP controls are currently available in the Windows Community Toolkit.

控件Control 支持的最低操作系统Minimum supported OS 描述Description
InkCanvasInkCanvas
InkToolbarInkToolbar
Windows 10 版本 1903Windows 10, version 1903 为 Windows 窗体或 WPF 桌面应用程序中的基于 Windows Ink 的用户交互提供一个表面和相关的工具栏。Provide a surface and related toolbars for Windows Ink-based user interaction in your Windows Forms or WPF desktop application.
MediaPlayerElementMediaPlayerElement Windows 10 版本 1903Windows 10, version 1903 嵌入用于在 Windows 窗体或 WPF 桌面应用程序中流式传输和呈现媒体内容(如视频)的视图。Embeds a view that streams and renders media content such as video in your Windows Forms or WPF desktop application.
MapControlMapControl Windows 10 版本 1903Windows 10, version 1903 使您能够在 Windows 窗体或 WPF 桌面应用程序中显示符号或照片的照片。Enables you to display a symbolic or photorealistic map in your Windows Forms or WPF desktop application.

有关演示如何使用包装的 UWP 控件的演练,请参阅在 WPF 应用中托管标准 UWP 控件For a walkthrough that demonstrates how to use the wrapped UWP controls, see Host a standard UWP control in a WPF app.

主机控件Host controls

对于超出可用包装控件所涵盖的方案,WPF 和 Windows 窗体应用程序还可以使用 Windows 社区工具包中提供的WindowsXamlHost控件。For scenarios beyond those covered by the available wrapped controls, WPF and Windows Forms applications can also use the WindowsXamlHost control that is available in the Windows Community Toolkit.

控件Control 支持的最低操作系统Minimum supported OS 描述Description
WindowsXamlHostWindowsXamlHost Windows 10 版本 1903Windows 10, version 1903 可以承载从Windows中派生的任何 uwp 控件,包括 Windows SDK 提供的所有第一方 uwp 控件以及自定义控件。Can host any UWP control that derives from Windows.UI.Xaml.UIElement, including any first-party UWP control provided by the Windows SDK as well as custom controls.

有关演示如何使用WindowsXamlHost控件的演练,请参阅在 wpf 应用程序中托管标准 uwp 控件使用 XAML 孤岛在 wpf 应用程序中托管自定义 uwp 控件For walkthroughs that demonstrate how to use the WindowsXamlHost control, see Host a standard UWP control in a WPF app and Host a custom UWP control in a WPF app using XAML Islands.

备注

仅在 WPF 和面向 .NET Core 3 的 Windows 窗体应用中,才支持使用WindowsXamlHost控件托管自定义 UWP 控件。Using the WindowsXamlHost control to host custom UWP controls is supported only in WPF and Windows Forms apps that target .NET Core 3. 以 .NET Framework 或 .NET Core 3 为目标的应用程序支持承载 Windows SDK 提供的第一方 UWP 控件。Hosting first-party UWP controls provided by the Windows SDK is supported in apps that target either the .NET Framework or .NET Core 3.

将项目配置为使用 XAML 岛 .NET 控件Configure your project to use the XAML Island .NET controls

XAML 孤岛 .NET 控件需要 Windows 10 版本1903或更高版本。The XAML Island .NET controls require Windows 10, version 1903, or a later version. 若要使用这些控件,请安装下面列出的一个 NuGet 包。To use these controls, install one of the NuGet packages listed below. 这些包提供了使用 XAML 岛包装控件和宿主控件所需的一切,还包括其他相关的 NuGet 包,这些包也是必需的。These packages provide everything you need to use the XAML Island wrapped controls and host controls, and they include other related NuGet packages that are also required.

控件类型Type of control NuGet 包NuGet package 相关文章Related articles
包装控件Wrapped controls 版本 6.0.0-preview7 或更高版本的这些包:Version 6.0.0-preview7 or later of these packages: 在 WPF 应用程序中托管标准 UWP 控件Host a standard UWP control in a WPF app
主机控件Host control 版本 6.0.0-preview7 或更高版本的这些包:Version 6.0.0-preview7 or later of these packages: 在 WPF 应用程序中托管标准 UWP 控件Host a standard UWP control in a WPF app
在 WPF 应用程序中托管自定义 UWP 控件Host a custom UWP control in a WPF app

请注意以下详细信息:Be aware of the following details:

  • 宿主控件包也包含在包装的控件包中。The host control packages are also included in the wrapped control packages. 如果要使用这两组控件,可以安装已包装的控件包。You can install the wrapped control packages if you want to use both sets of controls.

  • 如果承载的是自定义 UWP 控件,则 WPF 或 Windows 窗体项目必须面向 .NET Core 3。If you're hosting a custom UWP control, your WPF or Windows Forms project must target .NET Core 3. 面向 .NET Framework 的应用程序中不支持承载自定义 UWP 控件。Hosting custom UWP controls is not supported in apps that target the .NET Framework. 还需要执行一些附加步骤来引用自定义控件。You'll also need to perform some additional steps to reference the custom control. 有关详细信息,请参阅使用 XAML 孤岛在 WPF 应用中托管自定义 UWP 控件For more info, see Host a custom UWP control in a WPF app using XAML Islands.

  • 这些说明的早期版本已将 maxversiontested 元素添加到 WPF 或 Windows 窗体项目中的应用程序清单。Earlier versions of these instructions had you add the maxversiontested element to an application manifest in your WPF or Windows Forms project. 只要你使用以上列出的 NuGet 包的最新预览版,就不再需要将此元素添加到清单中。As long as you're using the latest preview versions of the NuGet packages listed above, you no longer need to add this element to your manifest.

XAML 孤岛 .NET 控件的体系结构Architecture of XAML Island .NET controls

下面简要介绍了不同类型的 XAML 岛控件如何组织在 UWP XAML 宿主 API 的顶层。Here's a quick look at how the different types of XAML Island controls are organized architecturally on top of the UWP XAML hosting API.

托管控件体系结构

此图表底部所示的 API 随 Windows SDK 提供。The APIs that appear at the bottom of this diagram ship with the Windows SDK. 已包装的控件和主机控件可通过 Windows 社区工具包中的 NuGet 包获得。The wrapped controls and host controls are available via NuGet packages in the Windows Community Toolkit.

Web 视图控件Web view controls

Windows 社区工具包还提供了以下用于在 WPF 中承载 web 内容和 Windows 窗体应用程序的 .NET 控件。The Windows Community Toolkit also provides the following .NET controls for hosting web content in WPF and Windows Forms applications. 这些控件通常用于类似的桌面应用现代化方案,作为 XAML 岛控件,并在与 XAML 岛控件相同的Microsoft 工具包存储库存储库中进行维护。These controls are often used in similar desktop app modernization scenarios as the XAML Island controls, and they are maintained in the same Microsoft.Toolkit.Win32 repo repo as the XAML Island controls.

控件Control 支持的最低操作系统Minimum supported OS 描述Description
WebViewWebView Windows 10 版本 1803Windows 10, version 1803 使用 Microsoft Edge 呈现引擎显示 web 内容。Uses the Microsoft Edge rendering engine to show web content.
WebViewCompatibleWebViewCompatible Windows 7Windows 7 提供与更多操作系统版本兼容的Web 视图版本。Provides a version of WebView that is compatible with more OS versions. 此控件使用 Microsoft 边缘呈现引擎在 Windows 10 版本1803及更高版本上显示 web 内容,并使用 Internet Explorer 呈现引擎在早期版本的 Windows 10、Windows 8.x 和 Windows 7 上显示 web 内容。This control uses the Microsoft Edge rendering engine to show web content on Windows 10 version 1803 and later, and the Internet Explorer rendering engine to show web content on earlier versions of Windows 10, Windows 8.x, and Windows 7.

若要使用这些控件,请安装以下 NuGet 包之一:To use these controls, install one of these NuGet packages:

C++Win32 应用程序C++ Win32 applications

Win32 应用程序中C++不支持 XAML 岛 .net 控件。The XAML Island .NET controls are not supported in C++ Win32 applications. 这些应用程序必须使用 Windows 10 SDK (版本1903及更高版本)提供的UWP XAML 宿主 APIThese applications must instead use the UWP XAML hosting API provided by the Windows 10 SDK (version 1903 and later).

UWP XAML 宿主 API 包含若干 Windows 运行时类和 COM 接口, C++ Win32 应用程序可使用这些接口来承载派生自WINDOWS的任何 UWP 控件。The UWP XAML hosting API consists of several Windows Runtime classes and COM interfaces that your C++ Win32 application can use to host any UWP control that derives from Windows.UI.Xaml.UIElement. 可以在应用程序中具有关联窗口句柄(HWND)的任何 UI 元素中承载 UWP 控件。You can host UWP controls in any UI element in your application that has an associated window handle (HWND). 有关此 API 的详细信息,包括先决条件,请参阅 C++在 Win32 应用中使用 UWP XAML 宿主 APIFor more information about this API, including prerequisites, see Using the UWP XAML hosting API in a C++ Win32 app.

备注

Windows 社区工具包中的已包装控件和主机控件在内部使用 UWP XAML 宿主 API,并实现你在自行使用 UWP XAML 宿主 API 时需要自行处理的所有行为,包括键盘导航和布局更改。The wrapped controls and host controls in the Windows Community Toolkit use the UWP XAML hosting API internally and implement all of the behavior you would otherwise need to handle yourself if you used the UWP XAML hosting API directly, including keyboard navigation and layout changes. 对于 WPF 和 Windows 窗体应用程序,我们强烈建议您直接使用这些控件而不是 UWP XAML 托管 API,因为它们抽象地消除了使用 API 的许多实现细节。For WPF and Windows Forms applications, we strongly recommend that you use these controls instead of the UWP XAML hosting API directly because they abstract away many of the implementation details of using the API.

功能路线图Feature roadmap

截至 Windows 10 版本1903,Windows 社区工具包中的 XAML 岛 .NET 控件仍处于开发人员预览版中,直到版本1.0 版本的控件可用为止。As of the release of Windows 10, version 1903, the XAML Island .NET controls in the Windows Community Toolkit are still in developer preview until the version 1.0 release of the controls is available.

  • .NET Framework 4.6.2 和更高版本的控件的1.0 版将在工具包的6.0 版本中发布。Version 1.0 of the controls for the .NET Framework 4.6.2 and later are planned to be released in the 6.0 release of the toolkit.
  • 适用于 .NET Core 3 的控件版本1.0 计划在更高版本的工具包中。Version 1.0 of the controls for .NET Core 3 are planned for a later release of the toolkit.
  • 如果要尝试对 .NET Framework 和 .NET Core 3 的这些控件的版本1.0 版本进行最新预览,请参阅UWP 社区工具包库中的版本 6.0.0-preview7 (或更高版本) NuGet 包。If you want to try the latest previews of the version 1.0 releases of these controls for the .NET Framework and .NET Core 3, see the version 6.0.0-preview7 (or later) NuGet packages in the UWP Community Toolkit gallery.

有关更多详细信息,请参阅这篇博客文章For more details, see this blog post.

其他资源Additional resources

有关使用 XAML 孤岛的更多背景信息和教程,请参阅以下文章和资源:For more background information and tutorials about using XAML Islands, see the following articles and resources:

  • 现代化 WPF 应用教程:本教程提供了使用 Windows 社区工具包中的包装控件和主机控件向现有 WPF 业务线应用程序添加 UWP 控件的分步说明。Modernize a WPF app tutorial: This tutorial provides step-by-step instructions for using the wrapped controls and host controls in the Windows Community Toolkit to add UWP controls to an existing WPF line-of-business application. 本教程包含 WPF 应用程序的完整代码,以及该过程中每个步骤的详细说明。This tutorial includes the complete code for the WPF application as well as detailed instructions for each step in the process.
  • XAML 孤岛 v1-更新和路线图:此博客文章讨论了有关 XAML 孤岛的许多常见问题,并提供详细的开发路线图。XAML Islands v1 - Updates and Roadmap: This blog post discusses many common questions about XAML Islands and provides a detailed development roadmap.