Типы пользовательских элементов управления (Windows Forms .NET) Types of custom controls (Windows Forms .NET)

С помощью Windows Forms можно разрабатывать и реализовывать новые элементы управления. With Windows Forms, you can develop and implement new controls. Можно создать новый пользовательский элемент управления, изменить существующие элементы управления с помощью наследования, а также написать пользовательский элемент управления, который выполняет собственное рисование. You can create a new user control, modify existing controls through inheritance, and write a custom control that does its own painting.

Документация для Руководства по рабочему столу по .NET 5 (и .NET Core) находится в разработке. The Desktop Guide documentation for .NET 5 (and .NET Core) is under construction.

Выбор типа создаваемого элемента управления может быть затруднителен. Deciding which kind of control to create can be confusing. В этой статье описываются различия между типами элементов управления, которые можно использовать для наследования, и рассказывается, как выбрать тип элемента управления для конкретного проекта. This article highlights the differences among the various kinds of controls from which you can inherit, and provides you with information about how to choose a particular type of control for your project.

Если. If .	Создайте. Create a .
— если нужно объединить функциональные возможности нескольких элементов управления Windows Forms в один блок для повторного использования. You want to combine the functionality of several Windows Forms controls into a single reusable unit.	Составной элемент управления путем наследования от System.Windows.Forms.UserControl. Composite control by inheriting from System.Windows.Forms.UserControl.
— если большинство необходимых функций аналогичны функциям уже существующего элемента управления Windows Forms; Most of the functionality you need is already identical to an existing Windows Forms control. — если нестандартный графический интерфейс не требуется или необходимо разработать новый интерфейс для существующего элемента управления. You don’t need a custom graphical user interface, or you want to design a new graphical user interface for an existing control.	Расширенный элемент управления путем наследования от конкретного элемента управления Windows Forms. Extended control by inheriting from a specific Windows Forms control.
— если требуется создать пользовательское графическое представление элемента управления; You want to provide a custom graphical representation of your control. — если требуется реализовать пользовательские функциональные возможности, которые недоступны в стандартных элементах управления. You need to implement custom functionality that isn’t available through standard controls.	Пользовательский элемент управления путем наследования от System.Windows.Forms.Control. Custom control by inheriting from System.Windows.Forms.Control.

Базовый класс элемента управления Base Control Class

Класс Control является базовым классом для элементов управления Windows Forms. The Control class is the base class for Windows Forms controls. Он обеспечивает инфраструктуру, необходимую для визуального отображения элементов управления в приложениях Windows Forms и предоставляет следующие возможности. It provides the infrastructure required for visual display in Windows Forms applications and provides the following capabilities:

• Обеспечивает обработку окон. Exposes a window handle.
• Управляет маршрутизацией сообщений. Manages message routing.
• Предоставляет события мыши и клавиатуры, а также многие другие события пользовательского интерфейса. Provides mouse and keyboard events, and many other user interface events.
• Предоставляет расширенные функции размещения. Provides advanced layout features.
• Содержит множество свойств, характерных для визуального отображения, таких как ForeColor, BackColor, Height и Width. Contains many properties specific to visual display, such as ForeColor, BackColor, Height, and Width.
• Обеспечивает безопасность и поддержку потоков, необходимые для того, чтобы элемент управления Windows Forms действовал как элемент управления Microsoft® ActiveX®. Provides the security and threading support necessary for a Windows Forms control to act as a Microsoft® ActiveX® control.

Поскольку существенная часть инфраструктуры предоставляется базовым классом, разрабатывать собственные элементы управления Windows Forms довольно просто. Because so much of the infrastructure is provided by the base class, it’s relatively easy to develop your own Windows Forms controls.

Составные элементы управления Composite Controls

Составной элемент управления — это коллекция элементов управления Windows Forms, инкапсулированных в общий контейнер. A composite control is a collection of Windows Forms controls encapsulated in a common container. Этот тип элементов управления иногда называют пользовательским элементом управления. This kind of control is sometimes called a user control. Элементы, входящие в составной элемент управления, называются составляющими. The contained controls are called constituent controls.

Составной элементе управления содержит все унаследованные функциональные возможности, связанные с каждым входящим в него элементом управления Windows Forms, и позволяет выборочно представлять и связывать их свойства. A composite control holds all of the inherent functionality associated with each of the contained Windows Forms controls and enables you to selectively expose and bind their properties. Кроме того, составной элемент управления предоставляет немало функций для обработки событий клавиатуры по умолчанию, не требуя дополнительной разработки с вашей стороны. A composite control also provides a great deal of default keyboard handling functionality with no extra development effort on your part.

Например, составной элемент управления можно собрать таким образом, чтобы он отображал данные адреса клиента из базы данных. For example, a composite control could be built to display customer address data from a database. Этот элемент управления включает элемент управления DataGridView для отображения полей базы данных, BindingSource для управления привязкой к источнику данных, а также BindingNavigator для перемещения по записям. This control would include a DataGridView control to display the database fields, a BindingSource to handle binding to a data source, and a BindingNavigator control to move through the records. Вы можете выборочно предоставить свойства привязки данных, а также упаковать и повторно использовать весь элемент управления в других приложениях. You could selectively expose data binding properties, and you could package and reuse the entire control from application to application.

Для создания составного элемента следует выполнить наследование от класса UserControl. To author a composite control, derive from the UserControl class. Базовый класс UserControl обеспечивает маршрутизацию клавиатуры для дочерних элементов управления и позволяет им работать сообща. The UserControl base class provides keyboard routing for child controls and enables child controls to work as a group.

Расширенные элементы управления Extended Controls

Элемент управления можно унаследовать от любого существующего элемента управления Windows Forms. You can derive an inherited control from any existing Windows Forms control. Такой подход позволяет сохранить все функциональные возможности, унаследованные от элемента управления Windows Forms, и расширить их путем добавления пользовательских свойств, методов или других функций. With this approach, you can keep all of the inherent functionality of a Windows Forms control, and then extend that functionality by adding custom properties, methods, or other features. С помощью этого параметра можно переопределить логику отрисовки базового элемента управления, а затем расширить его пользовательский интерфейс, изменив его внешний вид. With this option, you can override the base control’s paint logic, and then extend its user interface by changing its appearance.

Например, можно создать элемент управления, производный от элемента управления Button, который будет отслеживать, сколько раз пользователь на него нажал. For example, you can create a control derived from the Button control that tracks how many times a user has clicked it.

В некоторых элементах управления к графическому пользовательскому интерфейсу можно добавить пользовательское оформление путем переопределения метода OnPaint базового класса. In some controls, you can also add a custom appearance to the graphical user interface of your control by overriding the OnPaint method of the base class. Для расширенной кнопки, отслеживающей щелчки, можно переопределить метод OnPaint, чтобы вызвать базовую реализацию OnPaint, а затем отобразить число щелчков в одном углу клиентской области элемента управления Button. For an extended button that tracks clicks, you can override the OnPaint method to call the base implementation of OnPaint, and then draw the click count in one corner of the Button control’s client area.

Пользовательские элементы управления Custom Controls

Другим способом разработки элемента управления является создание его практически с нуля путем наследования от класса Control. Another way to create a control is to create one substantially from the beginning by inheriting from Control. Класс Control обеспечивает всю основную функциональность, необходимую элементам управления (включая обработку событий мыши и клавиатуры), однако не имеет функциональных возможностей для отдельных элементов управления и лишен графического интерфейса. The Control class provides all of the basic functionality required by controls, including mouse and keyboard handling events, but no control-specific functionality or graphical interface.

Создание элемента управления путем наследования от класса Control — гораздо более сложная задача, чем наследование от UserControl или существующего элемента управления Windows Forms. Creating a control by inheriting from the Control class requires much more thought and effort than inheriting from UserControl or an existing Windows Forms control. Поскольку значительную часть реализации вы выполняете сами, ваш элемент управления может быть более гибким, чем составной или расширенный, и вы можете его адаптировать к конкретным задачам. Because a great deal of implementation is left for you, your control can have greater flexibility than a composite or extended control, and you can tailor your control to suit your exact needs.

Для реализации настраиваемого элемента управления необходимо написать код для события OnPaint элемента управления, а также код для нужных вам функций. To implement a custom control, you must write code for the OnPaint event of the control, as well as any feature-specific code you need. Можно также переопределить метод WndProc и обрабатывать сообщения Windows напрямую. You can also override the WndProc method and handle windows messages directly. Это самый эффективный способ создания элементов управления, однако для того, чтобы использовать его эффективно, необходимо знание API Microsoft Win32®. This is the most powerful way to create a control, but to use this technique effectively, you need to be familiar with the Microsoft Win32® API.

Примером нестандартного элемента управления служит элемент управления «Часы», который выглядит и действует как часы со стрелками. An example of a custom control is a clock control that duplicates the appearance and behavior of an analog clock. Вы можете применить пользовательское оформление, чтобы заставить стрелки часов двигаться при наступлении событий Tick внутреннего компонента Timer. Custom painting is invoked to cause the hands of the clock to move in response to Tick events from an internal Timer component.

Элементы управления ActiveX ActiveX Controls

Несмотря на то что инфраструктура Windows Forms оптимизирована для размещения элементов управления Windows Forms, элементы управления ActiveX также можно использовать. Although the Windows Forms infrastructure has been optimized to host Windows Forms controls, you can still use ActiveX controls. Эта задача поддерживается в Visual Studio. There’s support for this task in Visual Studio.

Элементы управления без окон Windowless Controls

Технологии Microsoft Visual Basic® 6.0 и ActiveX поддерживают элементы управления без окон. The Microsoft Visual Basic® 6.0 and ActiveX technologies support windowless controls. В Windows Forms элементы управления без окон не поддерживаются. Windowless controls aren’t supported in Windows Forms.

Пользовательская среда разработки Custom Design Experience

Если вам требуется пользовательская среда разработки, вы можете создать свой собственный конструктор. If you need to implement a custom design-time experience, you can author your own designer. Для составных элементов управления следует наследовать класс пользовательского конструктора от классов ParentControlDesigner или DocumentDesigner. For composite controls, derive your custom designer class from the ParentControlDesigner or the DocumentDesigner classes. Для расширенных и настраиваемых элементов управления создайте класс пользовательского конструктора из класса ControlDesigner. For extended and custom controls, derive your custom designer class from the ControlDesigner class.

Используйте DesignerAttribute, чтобы связать элемент управления с конструктором. Use the DesignerAttribute to associate your control with your designer.

Следующие сведения устарели, но могут помочь вам. The following information is out of date but may help you.

Размещение элементов управления WinRT XAML в классических приложениях (XAML Islands) Host WinRT XAML controls in desktop apps (XAML Islands)

Начиная с Windows 10 версии 1903, вы можете размещать элементы управления WinRT XAML в классических приложениях, созданных не на платформе UWP, с помощью функции, называемой XAML Island. Starting in Windows 10, version 1903, you can host WinRT XAML controls in non-UWP desktop applications using a feature called XAML Islands. Эта функция позволяет улучшить внешний вид и функции имеющихся приложений (WPF, Windows Forms и Win32 на C++) с помощью последних функций пользовательского интерфейса Windows 10, которые доступны только через элементы управления WinRT XAML. 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 WinRT XAML controls. Это означает, что в имеющихся приложениях WPF, Windows Forms и Win32 на C++ можно использовать такие функции UWP, как Windows Ink, и элементы управления, которые поддерживают систему Fluent Design. 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.

Вы можете разместить любой элемент управления WinRT XAML, производный от Windows.UI.Xaml.UIElement, в том числе: You can host any WinRT XAML control that derives from Windows.UI.Xaml.UIElement, including:

• Любой основной элемент управления WinRT XAML, предоставляемый пакетом Windows SDK и библиотекой WinUI версии 2.x. Any first-party WinRT XAML control provided by the Windows SDK or the WinUI 2.x library.
• Любой настраиваемый элемент управления WinRT XAML (например, элемент, состоящий из нескольких элементов управления WinRT XAML, которые работают совместно). Any custom WinRT XAML control (for example, a user control that consists of several WinRT XAML controls that work together). Чтобы скомпилировать пользовательский элемент управления с приложением, требуется его исходный код. You must have the source code for the custom control so you can compile it with your application.

По сути, объекты XAML Island создаются с помощью API размещения UWP XAML. Fundamentally, XAML Islands are created by using the UWP XAML hosting API. Этот API состоит из нескольких классов среды выполнения Windows и COM-интерфейсов, которые появились в пакете SDK для Windows 10 версии 1903. This API consists of several Windows Runtime classes and COM interfaces that were introduced in the Windows 10, version 1903 SDK. Мы также предоставляем в наборе средств сообщества Windows подмножество элементов управления XAML Island .NET, которые используют API размещения UWP XAML на внутреннем уровне и обеспечивают более удобную среду для разработки приложений WPF и Windows Forms. 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 Islands зависит от типа приложения и типов элементов управления WinRT XAML, которые требуется разместить. The way you use XAML Islands depends on your application type and the types of WinRT XAML controls you want to host.

Если вы хотите поделиться мнением об XAML Island, создайте запрос в репозитории 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.

Требования Requirements

Для XAML Islands действуют следующие требования к среде выполнения: 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 Forms WPF and Windows Forms applications

Использование XAML Islands для размещения элементов управления WinRT XAML в приложениях WPF и Windows Forms сейчас поддерживают только приложения, предназначенные для .NET Core 3.x. Using XAML Islands to host WinRT XAML controls in WPF and Windows Forms apps is currently supported only in apps that target .NET Core 3.x. XAML Islands пока не поддерживают приложения, предназначенные для .NET 5, или предложения для любой версии .NET Framework. XAML Islands are not yet supported in apps that target .NET 5, or in apps that any version of the .NET Framework.

Рекомендуется, чтобы приложения WPF и Windows Forms использовали элементы управления XAML Island .NET, доступные в наборе средств сообщества Windows. We recommend that WPF and Windows Forms applications use the XAML Island .NET controls that are available in the Windows Community Toolkit. Эти элементы управления предоставляют объектную модель, которая имитирует свойства, методы и события соответствующих элементов управления WinRT XAML или предоставляет доступ к ним. These controls provide an object model that mimics (or provides access to) the properties, methods, and events of the corresponding WinRT XAML controls. Они также поддерживают такие действия, как навигация с помощью клавиатуры и изменение раскладки. They also handle behavior such as keyboard navigation and layout changes.

Существует два набора элементов управления XAML Island для приложений WPF и Windows Forms: заключенные в оболочку элементы управления и элементы управления ведущего приложения. There are two sets of XAML Island controls for WPF and Windows Forms applications: wrapped controls and host controls.

Заключенные в оболочку элементы управления Wrapped controls

Приложения WPF и Windows Forms могут использовать набор элементов управления XAML Island, которые заключают интерфейс и функциональные возможности определенного элемента управления WinRT XAML в оболочку. WPF and Windows Forms applications can use a selection of XAML Island controls that wrap the interface and functionality of a specific WinRT XAML control. Можно добавить эти элементы управления напрямую в область проектирования вашего проекта WPF или Windows Forms, а затем использовать их как и любой другой элемент управления WPF или Windows Forms в конструкторе. 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.

Приведенные ниже заключенные в оболочку элементы управления WinRT XAML в настоящее время доступны в наборе средств сообщества Windows. The following wrapped WinRT XAML controls are currently available in the Windows Community Toolkit.

Элемент Control	Минимальная поддерживаемая версия ОС Minimum supported OS	Описание Description
InkCanvas InkCanvas InkToolbar InkToolbar	Windows 10 версии 1903 Windows 10, version 1903	Предоставляет поверхность и соответствующие панели инструментов для взаимодействия с пользователем на основе Windows Ink в классическом приложении Windows Forms или WPF. Provide a surface and related toolbars for Windows Ink-based user interaction in your Windows Forms or WPF desktop application.
MediaPlayerElement MediaPlayerElement	Windows 10 версии 1903 Windows 10, version 1903	Внедряет представление, которое выполняет потоковую передачу и визуализацию мультимедийного содержимого, например видео, в классическом приложении Windows Forms или WPF. Embeds a view that streams and renders media content such as video in your Windows Forms or WPF desktop application.
MapControl MapControl	Windows 10 версии 1903 Windows 10, version 1903	Позволяет отображать символьную или фотореалистичную карту в классическом приложении Windows Forms или WPF. Enables you to display a symbolic or photorealistic map in your Windows Forms or WPF desktop application.

Пошаговое руководство, в котором демонстрируется использование заключенных в оболочку элементов управления WinRT XAML, см. в статье Размещение стандартного элемента управления WinRT XAML в приложении WPF с помощью объектов XAML Island. For a walkthrough that demonstrates how to use the wrapped WinRT XAML controls, see Host a standard WinRT XAML control in a WPF app.

Элементы управления ведущего приложения Host controls

Для пользовательских элементов управления и других сценариев, не поддерживаемых заключенными в оболочку элементами управления, приложения WPF и Windows Forms могут также использовать элемент управления WindowsXamlHost, доступный в наборе средств сообщества Windows. 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	Минимальная поддерживаемая версия ОС Minimum supported OS	Описание Description
WindowsXamlHost WindowsXamlHost	Windows 10 версии 1903 Windows 10, version 1903	Может размещать любой элемент управления WinRT XAML, производный от Windows.UI.Xaml.UIElement, включая любой основной элемент управления WinRT XAML, предоставляемый в пакете Windows SDK, а также пользовательские элементы управления. Can host any WinRT XAML control that derives from Windows.UI.Xaml.UIElement, including any first-party WinRT XAML control provided by the Windows SDK as well as custom controls.

Пошаговые руководства, демонстрирующие использование элемента управления WindowsXamlHost, можно найти в статьях о размещении стандартного и пользовательского элемента управления WinRT XAML в приложении WPF с помощью объектов XAML Island. For walkthroughs that demonstrate how to use the WindowsXamlHost control, see Host a standard WinRT XAML control in a WPF app and Host a custom WinRT XAML control in a WPF app using XAML Islands.

Настройка проекта для использования элементов управления XAML Island .NET Configure your project to use the XAML Island .NET controls

Для элементов управления XAML Island .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 Island и элементов управления ведущего приложения и содержат другие связанные пакеты 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: Microsoft.Toolkit.Wpf.UI.Controls; WPF: Microsoft.Toolkit.Wpf.UI.Controls Windows Forms: Microsoft.Toolkit.Forms.UI.Controls. Windows Forms: Microsoft.Toolkit.Forms.UI.Controls	Размещение стандартного элемента управления WinRT XAML в приложении WPF Host a standard WinRT XAML control in a WPF app
Элемент управления ведущего приложения Host control	Версия 6.0.0 этих пакетов или более поздняя: Version 6.0.0 or later of these packages: WPF: Microsoft.Toolkit.Wpf.UI.XamlHost; WPF: Microsoft.Toolkit.Wpf.UI.XamlHost Windows Forms: Microsoft.Toolkit.Forms.UI.XamlHost. Windows Forms: Microsoft.Toolkit.Forms.UI.XamlHost	Размещение стандартного элемента управления WinRT XAML в приложении WPF Host a standard WinRT XAML control in a WPF app Размещение пользовательского элемента управления WinRT XAML в приложении WPF Host a custom WinRT XAML 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.

Если вы размещаете пользовательский элемент управления WinRT XAML, вам также потребуется выполнить некоторые дополнительные действия, чтобы сослаться на пользовательский элемент управления. If you’re hosting a custom WinRT XAML control, you’ll also need to perform some additional steps to reference the custom control. Дополнительные сведения см. в статье Размещение пользовательского элемента управления WinRT XAML в приложение WPF с помощью объектов XAML Island. For more info, see Host a custom WinRT XAML control in a WPF app using XAML Islands.

Элементы управления для просмотра веб-содержимого Web view controls

Набор средств сообщества Windows Community также предоставляет следующие элементы управления .NET для размещения веб-содержимого в приложениях WPF и Windows Forms. The Windows Community Toolkit also provides the following .NET controls for hosting web content in WPF and Windows Forms applications. Эти элементы управления часто используются в тех же сценариях модернизации классических приложений, что и элементы управления XAML Island, и они хранятся в том же репозитории (Microsoft.Toolkit.Win32), что и элементы управления XAML Island. 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
WebView WebView	Windows 10 версии 1803 Windows 10, version 1803	Использует механизм визуализации Microsoft Edge для отображения веб-содержимого. Uses the Microsoft Edge rendering engine to show web content.
WebViewCompatible WebViewCompatible	Windows 7 Windows 7	Предоставляет версию WebView, которая совместима с другими версиями ОС. Provides a version of WebView that is compatible with more OS versions. Этот элемент управления использует механизм визуализации Microsoft Edge для отображения веб-содержимого в Windows 10 версии 1803 и более поздних и механизм визуализации Internet Explorer для отображения веб-содержимого в более ранних версиях Windows 10, Windows 8.x и Windows 7. 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:

Приложения Win32 на C++ C++ Win32 applications

Элементы управления XAML Island .NET не поддерживаются в приложениях Win32 на C++. The XAML Island .NET controls are not supported in C++ Win32 applications. Вместо этого такие приложения должны использовать API размещения UWP XAML, предоставляемый пакетом SDK для Windows 10 (версии 1903 и более поздних). These applications must instead use the UWP XAML hosting API provided by the Windows 10 SDK (version 1903 and later).

API размещения UWP XAML состоит из нескольких классов среды выполнения Windows и COM-интерфейсов, которые приложение Win32 на C++ может использовать для размещения любого элемента управления WinRT XAML, производного от Windows.UI.Xaml.UIElement. The UWP XAML hosting API consists of several Windows Runtime classes and COM interfaces that your C++ Win32 application can use to host any WinRT XAML control that derives from Windows.UI.Xaml.UIElement. Элементы управления WinRT XAML можно размещать в любом элементе пользовательского интерфейса в приложении с соответствующим дескриптором окна (HWND). You can host WinRT XAML 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 используют API размещения UWP XAML на внутреннем уровне и реализуют все типы поведения, которые при использовании API размещения UWP XAML напрямую пришлось бы реализовать самостоятельно, включая навигацию с помощью клавиатуры и изменение раскладки. 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 Forms мы настоятельно рекомендуем применять эти элементы управления, а не использовать API размещения UWP XAML напрямую, так как они устраняют множество сложностей реализации, возникающих при задействовании 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 Island Architecture of XAML Islands

Вот краткий обзор различных типов элементов управления XAML Island с точки зрения архитектуры с базой в виде API размещения UWP XAML. 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. Заключенные в оболочку элементы управления и элементы управления ведущего приложения доступны в пакетах NuGet в наборе средств сообщества Windows. The wrapped controls and host controls are available via NuGet packages in the Windows Community Toolkit.

Ограничения и обходные решения Limitations and workarounds

В следующих разделах описаны ограничения и обходные решения для некоторых сценариев разработки UWP в классических приложениях, использующих XAML Islands. The following sections discuss limitations and workarounds for certain UWP development scenarios in desktop apps that use XAML Islands.

Поддерживаются только при использовании обходных решений Supported only with workarounds

✔️ В текущем выпуске XAML Islands размещение элементов управления из библиотеки 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 для развертывания, можно разместить элементы управления WinUI из предварительной или окончательной версии пакета NugGet Microsoft.UI.Xaml. 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, вы сможете разместить элементы управления WinUI, если только установите последнюю предварительную версию пакета NuGet Microsoft.UI.Xaml. 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 и получения связанных сведений о контексте, в котором он размещен, не используйте классы CoreWindow, ApplicationView и Window. 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 Forms или Win32 на C++, оно должно использовать интерфейс 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.

✔️ Использование x:Bind с размещенными элементами управления в XAML Islands не поддерживается. Using x:Bind with hosted controls in XAML Islands is not supported. Вам необходимо объявить модель данных в библиотеке .NET Standard. You’ll have to declare the data model in a .NET Standard library.

Не поддерживается Not supported

🚫 Использование XAML Islands в приложениях WPF и Windows Forms, предназначенных для .NET Framework. Using XAML Islands in WPF and Windows Forms apps that target the .NET Framework. XAML Islands поддерживаются только в приложениях, предназначенных для .NET Core версии 3.x. XAML Islands are supported only in apps that target .NET Core 3.x.

🚫 Содержимое XAML UWP в XAML Islands во время выполнения не реагирует на изменения темы 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 не поддерживают размещение класса ContentDialog, который содержит элемент управления, который принимает ввод текста, например TextBox, RichEditBox или AutoSuggestBox. XAML Islands do not support hosting a ContentDialog that contains a control that accepts text input, such as a TextBox, RichEditBox, or AutoSuggestBox. В этом случае элемент управления для ввода не будет правильно реагировать на нажатие клавиш. If you do this, the input control will not properly respond to key presses. Для реализации подобной функциональности с помощью XAML Island мы рекомендуем разместить класс Popup, содержащий элемент управления для ввода. To achieve similar functionality using a XAML Island, we recommend that you host a Popup that contains the input control.

🚫 Сейчас XAML не поддерживает отображение SVG-файлов в размещенном элементе управления Windows.UI.Xaml.Controls.Image или с помощью объекта Windows.UI.Xaml.Media.Imaging.SvgImageSource. 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 Island Window host context for XAML Islands

При размещении объектов XAML Island в классическом приложении можно одновременно использовать несколько деревьев содержимого 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 Island и получения связанных сведений о контексте, в котором он размещен, используйте класс 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. Классы CoreWindow, ApplicationView и Window не предоставляют правильную информацию об объектах XAML Island. The CoreWindow, ApplicationView, and Window classes won’t provide the correct information for XAML Islands. Объекты CoreWindow и Window существуют в потоке и доступны для приложения, но они не возвращают значимые границы или видимость (они всегда невидимы и имеют размер 1 x 1). 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 1×1). Дополнительные сведения см. в этом разделе. For more information, see Windowing hosts.

Например, чтобы получить ограничивающий прямоугольник окна, содержащего элемент управления WinRT XAML, размещенный в XAML Island, используйте свойство XamlRoot.Size элемента управления. For example, to get the bounding rectangle of the window that contains a WinRT XAML control that is hosted in a XAML Island, use the XamlRoot.Size property of the control. Поскольку каждый элемент управления WinRT XAML, который может размещаться в XAML Island, является производным от Windows.UI.Xaml.UIElement, для доступа к объекту XamlRoot можно использовать свойство XamlRoot элемента управления. Because every WinRT XAML 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.

Не используйте свойство CoreWindows.Bounds для получения ограничивающего прямоугольника. Do not use the CoreWindows.Bounds property to get the bounding rectangle.

Таблицу рекомендуемых замен XamlRoot и распространенных, связанных с окнами API-интерфейсов, использования которых следует избегать в контексте объектов XAML Island, см. в этом разделе. 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.

Дополнительные ресурсы Additional resources

Дополнительные сведения и учебники по использованию элементов управления XAML Island см. в следующих статьях и ресурсах: For more background information and tutorials about using XAML Islands, see the following articles and resources:

• Учебник по модернизации приложения WPF. В этом учебнике содержатся пошаговые инструкции о том, как использовать заключенные в оболочку элементы управления и элементы управления размещения в наборе средств сообщества Windows, чтобы добавить элементы управления WinRT XAML в существующее бизнес-приложение WPF. 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 WinRT XAML 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 Island. Этот репозиторий содержит примеры для Windows Forms, WPF и C++/Win32, в которых демонстрируется использование объектов XAML Island. XAML Islands code samples: This repo contains Windows Forms, WPF, and C++/Win32 samples that demonstrate how to use XAML Islands.
• Обновления и стратегия развития элементов XAML Island версии 1. В этой записи блога рассматриваются многие распространенные вопросы об объектах XAML Island, а также приведена подробная схема разработки. XAML Islands v1 — Updates and Roadmap: This blog post discusses many common questions about XAML Islands and provides a detailed development roadmap.

—>