Размещение элементов управления WinRT XAML в классических приложениях (XAML Islands)
Внимание
В этом разделе используются или упоминаются типы из репозитория CommunityToolkit/Microsoft.Toolkit.Win32 GitHub. Дополнительные сведения о поддержке XAML Islands см . в уведомлении о xaml Islands в этом репозитории.
Начиная с Windows 10 версии 1903, вы можете размещать элементы управления WinRT XAML в классических приложениях, созданных не на платформе UWP, с помощью функции, называемой XAML Island. С ее помощью вы можете улучшить внешний вид и возможности существующих классических приложений WPF, Windows Forms и C++ (Win32), используя последние функции пользовательского интерфейса Windows, которые доступны только через элементы управления WinRT XAML. Это означает, что в существующих классических приложениях WPF, Windows Forms и C++ можно использовать такие функции UWP, как Windows Ink, а также элементы управления, которые поддерживают систему Fluent Design.
Вы можете разместить любой элемент управления WinRT XAML, производный от Windows.UI.Xaml.UIElement, в том числе:
- Большинство основных элементов управления WinRT XAML, предоставляемых пакетом Windows SDK и библиотекой WinUI версии 2 (исключения описаны здесь).
- Любой настраиваемый элемент управления WinRT XAML (например, элемент, состоящий из нескольких элементов управления WinRT XAML, которые работают совместно). Чтобы скомпилировать пользовательский элемент управления с приложением, требуется его исходный код.
По сути, объекты XAML Island создаются с помощью API размещения WinRT XAML. Этот API состоит из нескольких классов среды выполнения Windows и COM-интерфейсов, которые появились в пакете SDK для Windows 10 версии 1903. Мы также предоставляем в наборе средств сообщества Windows подмножество элементов управления XAML Island .NET, которые используют API размещения WinRT XAML на внутреннем уровне и обеспечивают более удобную среду для разработки приложений WPF и Windows Forms.
Способ использования XAML Islands зависит от типа приложения и типов элементов управления WinRT XAML, которые требуется разместить.
Примечание.
Если вы хотите поделиться мнением об XAML Island, создайте запрос в репозитории Microsoft.Toolkit.Win32 и оставьте свои комментарии.
Требования
Для XAML Islands действуют следующие требования к среде выполнения:
- ОС Windows 10 версии 1903 или более поздней.
- Если приложение не упаковано для развертывания в пакет MSIX, на компьютере должна быть установлена среда выполнения Visual C++.
Приложения WPF и Windows Forms
Примечание.
Использование XAML Islands для размещения элементов управления WinRT XAML в приложениях WPF и Windows Forms сейчас поддерживают только приложения, предназначенные для .NET Core 3.x. XAML Islands пока не поддерживают приложения, предназначенные для .NET, или предложения для любой версии .NET Framework.
Рекомендуется, чтобы приложения WPF и Windows Forms использовали элементы управления XAML Island .NET, доступные в наборе средств сообщества Windows. Эти элементы управления предоставляют объектную модель, которая имитирует свойства, методы и события соответствующих элементов управления WinRT XAML или предоставляет доступ к ним. Они также поддерживают такие действия, как навигация с помощью клавиатуры и изменение раскладки.
Существует два набора элементов управления XAML Island для приложений WPF и Windows Forms: заключенные в оболочку элементы управления и элементы управления ведущего приложения.
Заключенные в оболочку элементы управления
Приложения WPF и Windows Forms могут использовать набор элементов управления XAML Island, которые заключают интерфейс и функциональные возможности определенного элемента управления WinRT XAML в оболочку. Можно добавить эти элементы управления напрямую в область проектирования вашего проекта WPF или Windows Forms, а затем использовать их как и любой другой элемент управления WPF или Windows Forms в конструкторе.
Приведенные ниже заключенные в оболочку элементы управления WinRT XAML в настоящее время доступны в наборе средств сообщества Windows.
| Элемент управления | Минимальная поддерживаемая версия ОС | Description |
|---|---|---|
| InkCanvas InkToolbar |
Windows 10 версии 1903 | Предоставляет поверхность и соответствующие панели инструментов для взаимодействия с пользователем на основе Windows Ink в классическом приложении Windows Forms или WPF. |
| MediaPlayerElement | Windows 10 версии 1903 | Внедряет представление, которое выполняет потоковую передачу и визуализацию мультимедийного содержимого, например видео, в классическом приложении Windows Forms или WPF. |
| MapControl | Windows 10 версии 1903 | Позволяет отображать символьную или фотореалистичную карту в классическом приложении Windows Forms или WPF. |
Пошаговое руководство, в котором демонстрируется использование заключенных в оболочку элементов управления WinRT XAML, см. в статье Использование XAML Islands для размещения элемента управления XAML UWP в приложении WPF на C#.
Элементы управления ведущего приложения
Для пользовательских элементов управления и других сценариев, не поддерживаемых заключенными в оболочку элементами управления, приложения WPF и Windows Forms могут также использовать элемент управления WindowsXamlHost, доступный в наборе средств сообщества Windows.
| Элемент управления | Минимальная поддерживаемая версия ОС | Description |
|---|---|---|
| WindowsXamlHost | Windows 10 версии 1903 | Может размещать любой элемент управления WinRT XAML, производный от Windows.UI.Xaml.UIElement, включая любой основной элемент управления WinRT XAML, предоставляемый в пакете Windows SDK, а также пользовательские элементы управления. |
Пошаговые руководства, демонстрирующие использование элемента управления WindowsXamlHost, можно найти в статьях Использование XAML Islands для размещения элемента управления XAML UWP в приложении WPF на C# и Размещение пользовательского элемента управления WinRT XAML в приложении WPF с помощью XAML Islands.
Настройка проекта для использования элементов управления XAML Island .NET
Для элементов управления XAML Island .NET требуется Windows 10 версии 1903 или более поздней. Чтобы использовать эти элементы управления, установите один из перечисленных ниже пакетов NuGet. Эти пакеты предоставляют все требуемые компоненты для использования заключенных в оболочку элементов управления XAML Island и элементов управления ведущего приложения и содержат другие связанные пакеты NuGet, которые также необходимы.
| Тип элемента управления | Пакет NuGet | Связанные статьи |
|---|---|---|
| Заключенные в оболочку элементы управления | Версия 6.0.0 или более поздней версии этих пакетов:
|
Использование XAML Islands для размещения элемента управления XAML UWP в приложении WPF на C# |
| Элемент управления ведущего приложения | Версия 6.0.0 или более поздней версии этих пакетов:
|
Использование XAML Islands для размещения элемента управления XAML UWP в приложении WPF на C# Размещение пользовательского элемента управления WinRT XAML в приложении WPF |
Учтите следующие аспекты.
Пакеты элементов управления ведущего приложения также включены в пакеты заключенных в оболочку элементов управления. Если необходимо использовать оба набора элементов управления, можно установить пакеты элементов управления, заключенных в оболочку.
Если вы размещаете пользовательский элемент управления WinRT XAML, вам также потребуется выполнить некоторые дополнительные действия, чтобы сослаться на пользовательский элемент управления. Дополнительные сведения см. в статье Размещение пользовательского элемента управления WinRT XAML в приложение WPF с помощью объектов XAML Island.
Элементы управления для просмотра веб-содержимого
Набор средств сообщества Windows Community также предоставляет следующие элементы управления .NET для размещения веб-содержимого в приложениях WPF и Windows Forms. Эти элементы управления часто используются в аналогичных сценариях модернизации классических приложений, как элементы управления XAML Island, и они поддерживаются в том же репозитории Microsoft.Toolkit.Win32, что и элементы управления XAML Island.
| Элемент управления | Минимальная поддерживаемая версия ОС | Description |
|---|---|---|
| Веб-представление | Windows 10 версии 1803 | Использует механизм визуализации Microsoft Edge для отображения веб-содержимого. |
| WebViewCompatible | Windows 7 | Предоставляет версию WebView, которая совместима с другими версиями ОС. Этот элемент управления использует механизм визуализации Microsoft Edge для отображения веб-содержимого в Windows 10 версии 1803 и более поздних и механизм визуализации Internet Explorer для отображения веб-содержимого в более ранних версиях Windows 10, Windows 8.x и Windows 7. |
Чтобы использовать эти элементы управления, установите один из следующих пакетов NuGet:
- WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
- Windows Forms: Microsoft.Toolkit.Forms.UI.Controls.WebView
Классические приложения C++ (Win32)
Элементы управления XAML Islands .NET не поддерживаются в классических приложениях C++. Вместо этого такие приложения должны использовать API размещения WinRT XAML, предоставляемый пакетом SDK для Windows 10 (версии 1903 и более поздних версий).
API размещения WinRT XAML включает в себя несколько классов среды выполнения Windows и COM-интерфейсы, которые классическое приложение C++ может использовать для размещения любого элемента управления WinRT XAML, производного от Windows.UI.Xaml.UIElement. Элементы управления WinRT XAML можно размещать в любом элементе пользовательского интерфейса в приложении с соответствующим дескриптором окна (HWND). Дополнительные сведения об этом API доступны в следующих статьях:
- Использование API размещения WinRT XAML в классическом приложении C++
- Размещение стандартного элемента управления WinRT XAML в классическом приложении C++
- Размещение настраиваемого элемента управления WinRT XAML в классическом приложении C++
Примечание.
Заключенные в оболочку элементы управления и элементы управления ведущего приложения в наборе средств сообщества Windows используют API размещения WinRT XAML на внутреннем уровне и реализуют все типы поведения, которые при использовании API размещения WinRT XAML напрямую пришлось бы реализовать самостоятельно, включая навигацию с помощью клавиатуры и изменение раскладки. Для приложений WPF и Windows Forms мы настоятельно рекомендуем применять эти элементы управления, а не использовать API размещения WinRT XAML напрямую, так как они устраняют множество сложностей реализации, возникающих при задействовании API.
Архитектура объектов XAML Island
Вот краткий обзор различных типов элементов управления XAML Island с точки зрения архитектуры с базой в виде API размещения WinRT XAML.
API-интерфейсы, представленные в нижней части этой схемы, входят в состав пакета Windows SDK. Заключенные в оболочку элементы управления и элементы управления ведущего приложения доступны в пакетах NuGet в наборе средств сообщества Windows.
Ограничения и методы обхода
В следующих разделах описаны ограничения и обходные решения для некоторых сценариев разработки UWP в классических приложениях, использующих XAML Islands.
Поддерживаются только при использовании обходных решений
✔️ В текущем выпуске XAML Islands размещение элементов управления из библиотеки WinUI 2 поддерживается условно. Если классическое приложение использует пакет MSIX для развертывания, можно разместить элементы управления WinUI из предварительной или окончательной версии пакета NuGet Microsoft.UI.Xaml. Если классическое приложение не упаковано с помощью MSIX, вы сможете разместить элементы управления WinUI, если только установите последнюю предварительную версию пакета NuGet Microsoft.UI.Xaml или будете использовать API динамических зависимостей. Поддержка размещения элементов управления из библиотеки WinUI 3.0 будет реализована в более позднем выпуске.
✔️ Для доступа к корневому элементу дерева содержимого XAML в XAML Islands и получения связанных сведений о контексте, в котором он размещен, не используйте классы CoreWindow, ApplicationView и Window. Вместо этого используйте класс XamlRoot. Дополнительные сведения см. в этом разделе.
✔️ Чтобы обеспечить поддержку контракта отправки данных в классическом приложении WPF, Windows Forms или Win32 на C++, оно должно использовать интерфейс IDataTransferManagerInterop для получения объекта DataTransferManager, чтобы инициировать операцию общего доступа для определенного окна. Использование этого интерфейса в приложении WPF демонстрируется в примере ShareSource.
✔️ Использование x:Bind с размещенными элементами управления в XAML Islands не поддерживается. Вам необходимо объявить модель данных в библиотеке .NET Standard.
Не поддерживается
🚫 Использование XAML Islands в приложениях WPF и Windows Forms, предназначенных для .NET Framework. XAML Islands поддерживаются только в приложениях, предназначенных для .NET Core версии 3.x.
🚫 Содержимое XAML UWP в XAML Islands во время выполнения не реагирует на изменения темы Windows с темной на светлую или обратно. Но содержимое реагирует во время выполнения на изменение режима высокой контрастности.
🚫Добавление элемента управления Windows.UI.Xaml.WebView. Ознакомьтесь с этими альтернативами для приложений WPF и WinForms.
🚫 Элемент управления MediaPlayer и основной элемент управления MediaPlayerElement не поддерживаются в полноэкранном режиме.
🚫 Ввод текста в представлении рукописного ввода. Дополнительные сведения об этой возможности см. в этой статье.
🚫 Текстовые элементы управления, которые используют ссылки на содержимое @Places и @People. Дополнительные сведения об этой возможности см. в этой статье.
🚫 XAML Islands не поддерживают размещение класса ContentDialog который содержит элемент управления, принимающий ввод текста, например TextBox, RichEditBox или AutoSuggestBox. В этом случае элемент управления для ввода не будет правильно реагировать на нажатие клавиш. Для реализации подобной функциональности с помощью XAML Island мы рекомендуем разместить класс Popup, содержащий элемент управления для ввода.
🚫 Сейчас XAML Islands не поддерживает отображение SVG-файлов в размещенном элементе управления Windows.UI.Xaml.Controls.Image или с помощью объекта Windows.UI.Xaml.Media.Imaging.SvgImageSource. В качестве решения преобразуйте файлы изображений, которые требуется отобразить, в растровые форматы, такие как JPG или PNG.
Контекст узла с окном для объектов XAML Island
При размещении объектов XAML Island в классическом приложении можно одновременно использовать несколько деревьев содержимого XAML, выполняющихся в одном и том же потоке. Для доступа к корневому элементу дерева содержимого XAML в XAML Island и получения связанных сведений о контексте, в котором он размещен, используйте класс XamlRoot. Классы CoreWindow, ApplicationView и Window не предоставляют правильную информацию об объектах XAML Island. Объекты CoreWindow и Window существуют в потоке и доступны для приложения, но они не возвращают значимые границы или видимость (они всегда невидимы и имеют размер 1 x 1). Дополнительные сведения см. в этом разделе.
Например, чтобы получить ограничивающий прямоугольник окна, содержащего элемент управления WinRT XAML, размещенный в XAML Island, используйте свойство XamlRoot.Size элемента управления. Поскольку каждый элемент управления WinRT XAML, который может размещаться в XAML Island, является производным от Windows.UI.Xaml.UIElement, для доступа к объекту XamlRoot можно использовать свойство XamlRoot элемента управления.
Size windowSize = myUWPControl.XamlRoot.Size;
Не используйте свойство CoreWindows.Bounds для получения ограничивающего прямоугольника.
// This will return incorrect information for a WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;
Таблицу рекомендуемых замен XamlRoot и распространенных, связанных с окнами API-интерфейсов, использования которых следует избегать в контексте объектов XAML Island, см. в этом разделе.
Использование этого интерфейса в приложении WPF демонстрируется в примере ShareSource.
Дополнительные ресурсы
Дополнительные сведения и учебники по использованию элементов управления XAML Island см. в следующих статьях и ресурсах:
- Модернизация руководства по приложению WPF. В этом руководстве приведены пошаговые инструкции по использованию упакованных элементов управления и элементов управления узлами в наборе средств сообщества Windows для добавления элементов управления WinRT XAML в существующее бизнес-приложение WPF. В этом учебнике приведен полный код для приложения WPF, а также подробные инструкции по каждому этапу процесса.
- Примеры кода объектов XAML Islands. Этот репозиторий содержит примеры для классических приложений Windows Forms, WPF и C++ (Win32), в которых показано, как использовать объекты XAML Islands.
- XAML Islands версии 1 — обновления и стратегия развития. В этой записи блога рассматриваются многие распространенные вопросы о XAML Islands и приведен подробный план разработки.
Windows developer