Размещение элементов управления WinRT XAML в настольных приложениях (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, предоставляемые пакетом SDK для Windows или библиотекой WinUI для UWP (см. исключения).
• Любой настраиваемый элемент управления WinRT XAML (например, элемент, состоящий из нескольких элементов управления WinRT XAML, которые работают совместно). Чтобы скомпилировать пользовательский элемент управления с приложением, требуется его исходный код.

По сути, острова XAML создаются с помощью 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 Islands действуют следующие требования к среде выполнения:

• ОС Windows 10 версии 1903 или более поздней.
• Если приложение не упаковано для развертывания в пакет MSIX, на компьютере должна быть установлена среда выполнения Visual C++.

Приложения WPF и Windows Forms

Рекомендуется, чтобы приложения 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.

Пошаговое руководство, в котором демонстрируется использование заключенных в оболочку элементов управления WinRT XAML, см. в статье Использование XAML Islands для размещения элемента управления XAML UWP в приложении WPF на C#.

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

Для пользовательских элементов управления и других сценариев, не поддерживаемых заключенными в оболочку элементами управления, приложения WPF и Windows Forms могут также использовать элемент управления WindowsXamlHost, доступный в наборе средств сообщества Windows.

Пошаговые руководства, демонстрирующие использование элемента управления 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, которые также необходимы.

Учтите следующие аспекты.

• Пакеты управления хост-системы также включены в упакованные пакеты управления. Если необходимо использовать оба набора элементов управления, можно установить пакеты элементов управления, заключенных в оболочку.

• Если вы размещаете пользовательский элемент управления WinRT XAML, вам также потребуется выполнить некоторые дополнительные действия, чтобы сослаться на пользовательский элемент управления. Дополнительные сведения см. в статье Размещение пользовательского элемента управления WinRT XAML в приложении WPF с помощью XAML Islands.

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

Набор средств сообщества Windows Community также предоставляет следующие элементы управления .NET для размещения веб-содержимого в приложениях WPF и Windows Forms. Эти элементы управления часто используются в аналогичных сценариях модернизации классических приложений, как элементы управления XAML Island, и они поддерживаются в том же репозитории Microsoft.Toolkit.Win32, что и элементы управления XAML Island.

Чтобы использовать эти элементы управления, установите один из следующих пакетов 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++

Архитектура XAML Islands

Вот краткий обзор архитектурной организации различных типов управляющих элементов XAML Island на основе API размещения WinRT XAML.

API-интерфейсы, представленные в нижней части этой схемы, входят в состав пакета Windows SDK. Оболоченные элементы управления и хост-элементы управления доступны в пакетах NuGet в пакете Windows Community Toolkit.

Ограничения и методы обхода

В следующих разделах описаны ограничения и обходные решения для некоторых сценариев разработки UWP в классических приложениях, использующих XAML Islands.

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

✔️ Элементы управления размещением из библиотеки WinUI для UWP на острове XAML поддерживаются условно в текущем выпуске XAML Islands. Если настольное приложение использует пакет MSIX для развертывания, можно разместить элементы управления WinUI из предварительных или окончательных версий пакета NuGet Microsoft.UI.Xaml. Если ваше настольное приложение не упаковано с помощью MSIX, вы можете разместить элементы управления WinUI, только если установите предварительную версию пакета NuGet Microsoft.UI.Xaml или используете API динамических зависимостей. Поддержка элементов управления размещением из библиотеки WinUI.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 Islands

При размещении XAML Islands в классическом приложении можно одновременно использовать несколько деревьев содержимого XAML, выполняющихся в одном и том же потоке. Для доступа к корневому элементу дерева содержимого XAML в XAML Island и получения связанных сведений о контексте, в котором он размещен, используйте класс XamlRoot. Классы CoreWindow, ApplicationView и Window не предоставляют правильную информацию об объектах XAML Island. Объекты CoreWindow и Window существуют в потоке и доступны для приложения, но они не возвращают значимые границы или видимость (они всегда невидимы и имеют размер 1 x 1). Дополнительные сведения см. в Windowing hosts.

Например, чтобы получить ограничивающий прямоугольник окна, содержащего элемент управления 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 Islands см. в следующих статьях и ресурсах:

• Модернизация приложения WPF - руководство: В этом руководстве приведены пошаговые инструкции по использованию обёрнутых элементов управления и хост-контролов в Windows Community Toolkit для добавления элементов управления WinRT XAML в существующее бизнес-приложение WPF. В этом учебнике приведен полный код для приложения WPF, а также подробные инструкции по каждому этапу процесса.
• Примеры кода объектов XAML Islands. Этот репозиторий содержит примеры для классических приложений Windows Forms, WPF и C++ (Win32), в которых показано, как использовать объекты XAML Islands.
• XAML Islands версии 1 — обновления и стратегия развития. В этой записи блога рассматриваются многие распространенные вопросы о XAML Islands и приведен подробный план разработки.