在桌面应用中托管 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. 可以通过此功能来增强现有 WPF、Windows 窗体和 C++ Win32 应用程序的外观和功能,并使用只能通过 UWP 控件使用的最新 Windows 10 UI 功能。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. 这意味着,可以在现有的 WPF、Windows 窗体和 C++ Win32 应用程序中使用 UWP 功能(例如 Windows Ink)和支持 Fluent Design System 的控件。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.UI.Xaml.UIElement 的任何 UWP 控件,其中包括:You can host any UWP control that derives from Windows.UI.Xaml.UIElement, including:

  • Windows SDK 提供的任何第一方 UWP 控件。Any first-party UWP control provided by the Windows SDK.
  • 任何自定义 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.

从根本上讲,XAML 岛使用 UWP XAML 托管 API 创建。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.Toolkit.Win32 存储库中创建一个新问题,将你的意见留在那里。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.

要求Requirements

XAML 岛具有以下运行时要求:XAML Islands have these run time requirements:

  • Windows 10 版本 1903 或更高版本。Windows 10, version 1903, or a later release.
  • 如果你的应用程序未打包到 MSIX 包中用于部署,则必须在计算机上安装 Visual C++ 运行时If your application is not packaged in an MSIX package for deployment, the computer must have the Visual C++ Runtime installed.

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.

包装控件Wrapped controls

WPF 和 Windows 窗体应用程序可以使用选定的 XAML 岛控件来包装特定 UWP 控件的界面和功能。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 支持的 OS 的最低版本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 custom controls and other 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 支持的 OS 的最低版本Minimum supported OS 说明Description
WindowsXamlHostWindowsXamlHost Windows 10 版本 1903Windows 10, version 1903 可以托管派生自 Windows.UI.Xaml.UIElement 的任何 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.

备注

只能在以 .NET Core 3 为目标的 WPF 和 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 版或更高版本:Version 6.0.0 or later of these packages: 在 WPF 应用中托管标准 UWP 控件Host a standard UWP control in a WPF app
主机控件Host control 以下包的 6.0.0 版或更高版本:Version 6.0.0 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.

Web 视图控件Web view controls

Windows 社区工具包还提供了以下 .NET 控件,用于在 WPF 和 Windows 窗体应用程序中托管 Web 内容的。The Windows Community Toolkit also provides the following .NET controls for hosting web content in WPF and Windows Forms applications. 这些控件通常以 XAML 岛控件形式用于类似的桌面应用现代化方案,并保留在 XAML 岛控件所在的 Microsoft.Toolkit.Win32 存储库中。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 支持的 OS 的最低版本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 提供与更多 OS 版本兼容的 WebView 版本。Provides a version of WebView that is compatible with more OS versions. 此控件使用 Microsoft Edge 呈现引擎在 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

C++ Win32 应用程序不支持 XAML 岛 .NET 控件。The XAML Island .NET controls are not supported in C++ Win32 applications. 这些应用程序必须改用 Windows 10 SDK(版本 1903 及更高版本)提供的 UWP XAML 托管 API。These 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.UI.Xaml.UIElement 的任何 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 的详细信息,请参阅以下文章。For more information about this API, see the following articles.

备注

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.

XAML 岛的体系结构Architecture of XAML Islands

下面从体系结构方面简要介绍了如何将不同类型的 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.

限制和解决方法Limitations and workarounds

以下各节讨论使用 XAML 岛的桌面应用中某些 UWP 开发方案的限制和解决方法。The following sections discuss limitations and workarounds for certain UWP development scenarios in desktop apps that use XAML Islands.

仅通过使用变通方法支持Supported only with workarounds

✔️XAML 岛的当前版本有条件地支持在 XAML 岛中托管来自 WinUI 2.x 库的控件。Hosting controls from the WinUI 2.x Library in a XAML Island is supported conditionally in the current release of XAML Islands. 如果桌面应用将 MSIX 包用于部署,则可以承载来自 Microsoft.UI.Xaml NugGet 包的预发行版或发行版的 WinUI 控件。If your desktop app uses an MSIX package for deployment, you can host WinUI controls from prerelease or release versions of the Microsoft.UI.Xaml NugGet package. 如果桌面应用不是使用 MSIX 打包的,那么,只有在你安装了 Microsoft.UI.Xaml NuGet 包的预发行版的情况下,才能承载 WinUI 控件。If your desktop app is not packaged using MSIX, you can host WinUI controls only if you install a prerelease version of the Microsoft.UI.Xaml NuGet package. 以后的版本会支持托管来自 WinUI 3.0 库的控件。Support for hosting controls from the WinUI 3.0 Library is coming in a later release.

✔️若要访问 XAML 岛中 XAML 内容树的根元素并获取在其中托管它的上下文的相关信息,请勿使用 CoreWindowApplicationViewWindow 类。To access the root element of a tree of XAML content in a XAML Island and get related information about the context in which it is hosted, do not use the CoreWindow, ApplicationView, and Window classes. 相反,请使用 XamlRoot 类。Instead, use the XamlRoot class. 有关详情,请参阅本部分For more information, see this section.

✔️若要支持来自 WPF、Windows 窗体或 C++ Win32 应用的共享协定,应用必须使用 IDataTransferManagerInterop 接口获取 DataTransferManager 对象,以便为特定窗口启动共享操作。To support the Share contract from a WPF, Windows Forms, or C++ Win32 app, your app must use the IDataTransferManagerInterop interface to get the DataTransferManager object to initiate the share operation for a specific window. 有关演示如何在 WPF 应用中使用此接口的示例,请参阅 ShareSource 示例For a sample that demonstrates how to use this interface in a WPF app, see the ShareSource sample.

✔️不支持在 XAML 岛中使用具有托管控件的 x:BindUsing x:Bind with hosted controls in XAML Islands is not supported. 必须在 .NET 标准库中声明数据模型。You'll have to declare the data model in a .NET Standard library.

不支持Not supported

🚫使用 WindowsXamlHost 控件在面向 .NET Framework 的 WPF 和 Windows 窗体应用中托管基于 C# 的第三方 UWP 控件。Using the WindowsXamlHost control to host C#-based third-party UWP controls in WPF and Windows Forms apps that target the .NET Framework. 面向 .NET Core 3 的应用不支持此方案。This scenario is only supported in apps that target .NET Core 3.

🚫XAML 岛中的 UWP XAML 内容在运行时不响应 Windows 主题从深到浅的变化,反之亦然。UWP XAML content in XAML Islands doesn't respond to Windows theme changes from dark to light or vice versa at run time. 内容会响应运行时的高对比度更改。Content does respond to high contrast changes at run time.

🚫将 WebView 控件添加到自定义用户控件(无论是线程上、线程下还是进程外)。Adding a WebView control to a custom user control (either on-thread, off-thread, or out of process).

🚫在全屏模式下不支持 MediaPlayer 控件和 MediaPlayerElement 主机控件。The MediaPlayer control and MediaPlayerElement host control are not supported in full screen mode.

🚫带手写视图的文本输入。Text input with the handwriting view. 有关此功能的详细信息,请参阅本文For more information about this feature, see this article.

🚫使用 @Places@People 内容链接的文本控件。Text controls that use @Places and @People content links. 有关此功能的详细信息,请参阅本文For more information about this feature, see this article.

🚫XAML Islands 不支持托管一个包含接受文本输入的控件(例如 TextBoxRichEditBoxAutoSuggestBox)的 ContentDialogXAML Islands do not support hosting a ContentDialog that contains a control that accepts text input, such as a TextBox, RichEditBox, or AutoSuggestBox. 如果你托管了这样的 ContentDialog,输入控件将无法正确响应按键操作。If you do this, the input control will not properly respond to key presses. 若要使用 XAML Islands 实现类似的功能,建议托管一个包含输入控件的 PopupTo achieve similar functionality using a XAML Island, we recommend that you host a Popup that contains the input control.

🚫XAML 岛目前不支持在承载的 Windows.UI.Xaml.Controls.Image 控件中或通过使用 Windows.UI.Xaml.Media.Imaging.SvgImageSourc 对象显示 SVG 文件。XAML Islands do not currently support displaying SVG files in a hosted Windows.UI.Xaml.Controls.Image control or by using an Windows.UI.Xaml.Media.Imaging.SvgImageSource object. 作为一种解决方法,请将要显示的图像文件转换为基于光栅的格式,如 JPG 或 PNG。As a workaround, convert the image files you want to display to raster-based formats such as JPG or PNG.

XAML 岛的窗口宿主上下文Window host context for XAML Islands

在桌面应用中托管 XAML 岛时,可以同时在同一线程上运行多个 XAML 内容树。When you host XAML Islands in a desktop app, you can have multiple trees of XAML content running on the same thread at the same time. 若要访问 XAML 岛中 XAML 内容树的根元素并获取在其中托管它的上下文的相关信息,请使用 XamlRoot 类。To access the root element of a tree of XAML content in a XAML Island and get related information about the context in which it is hosted, use the XamlRoot class. CoreWindowApplicationViewWindow 类不会为 XAML 岛提供正确的信息。The CoreWindow, ApplicationView, and Window classes won't provide the correct information for XAML Islands. CoreWindowWindow 对象在线程上存在并且可供应用访问,但它们不会返回有意义的边界或可见性(它们始终不可见且大小为 1x1)。CoreWindow and Window objects do exist on the thread and are accessible to your app, but they won't return meaningful bounds or visibility (they are always invisible and have a size of 1x1). 有关详细信息,请参阅窗口化宿主For more information, see Windowing hosts.

例如,若要获取包含 XAML 岛中托管的 UWP 控件的窗口的边界矩形,请使用控件的 XamlRoot.Size 属性。For example, to get the bounding rectangle of the window that contains a UWP control that is hosted in a XAML Island, use the XamlRoot.Size property of the control. 由于可以在 XAML 岛中托管的每个 UWP 控件都派生自 Windows.UI.Xaml.UIElement,因此可以使用控件的 XamlRoot 属性来访问 XamlRoot 对象。Because every UWP control that can be hosted in a XAML Island derives from Windows.UI.Xaml.UIElement, you can use the XamlRoot property of the control to access the XamlRoot object.

Size windowSize = myUWPControl.XamlRoot.Size;

不要使用 CoreWindows.Bounds 属性来获取边界矩形。Do not use the CoreWindows.Bounds property to get the bounding rectangle.

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

如果需要一个表,其中包含与窗口化相关的常见 API(应避免在 XAML 岛的上下文中使用)以及建议的 XamlRoot 替换项,请查看此部分中的表。For a table of common windowing-related APIs that you should avoid in the context of XAML Islands and the recommended XamlRoot replacements, see the table in this section.

有关演示如何在 WPF 应用中使用此接口的示例,请参阅 ShareSource 示例For a sample that demonstrates how to use this interface in a WPF app, see the ShareSource sample.

功能路线图Feature roadmap

下面是与 XAML 岛相关的功能的当前状态:Here is the current state of XAML Islands-related features:

  • C++ Win32 应用: 从 Windows 10 版本 1903 开始推出的 UWP XAML 托管 API 被视为 1.0 版。C++ Win32 apps: The UWP XAML hosting API is considered version 1.0 as of Windows 10, version 1903.
  • 以 .NET Framework 4.6.2 及更高版本为目标的托管应用: 对于以 .NET Framework 4.6.2 及更高版本为目标的应用,在 6.0.0 版 NuGet 包中提供的 XAML 岛控件被视为 1.0 版。Managed apps that target .NET Framework 4.6.2 and later: The XAML Island controls that are available in the version 6.0.0 NuGet packages are considered version 1.0 for apps that target the .NET Framework 4.6.2 and later.
  • 以 .NET Core 3.0 及更高版本为目标的托管应用: 对于以 .NET Core 3.0 及更高版本为目标的应用,在 6.0.0 版 NuGet 包中提供的控件仍为开发者预览版。Managed apps that target .NET Core 3.0 and later: The controls that are available in the version 6.0.0 NuGet packages are still in developer preview for apps that target the .NET Core 3.0 and later. 用于 .NET Core 3.0 及更高版本的这些控件的 1.0 发布版计划用于更高版本。The version 1.0 release of these controls for .NET Core 3.0 and later are planned for a later release.

其他资源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 岛代码示例:此存储库包含的 Windows 窗体、WPF 和 C++/Win32 示例演示了如何使用 XAML 岛。XAML Islands code samples: This repo contains Windows Forms, WPF, and C++/Win32 samples that demonstrate how to use XAML Islands.
  • XAML Islands v1 - Updates and Roadmap(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.