Встраивание элементов управления XAML UWP в настольные приложения (Острова XAML UWP)

Начиная с Windows 10 версии 1903 вы можете размещать элементы управления XAML UWP в классических приложениях, отличных от UWP, с помощью функции UWP XAML Islands. Эта функция позволяет улучшить внешний вид, интерфейс и функциональные возможности существующих WPF, Windows Forms и классических приложений C++ (Win32) с помощью функций пользовательского интерфейса Windows, доступных только с помощью элементов управления XAML UWP. Это означает, что вы можете использовать такие функции UWP, как Windows Ink и элементы управления, поддерживающие Fluent Design System в существующих классических приложениях WPF, Windows Forms и C++.

Вы можете разместить любой элемент управления XAML UWP, производный от Windows.UI.Xaml.UIElement, включая:

• Большинство сторонних элементов управления XAML UWP, предоставляемые пакетом SDK Windows или библиотекой WinUI для UWP (см. exceptions).
• Любой пользовательский элемент управления XAML UWP (например, пользовательский элемент управления, состоящий из нескольких элементов управления XAML UWP, которые работают вместе). Чтобы скомпилировать пользовательский элемент управления с приложением, требуется его исходный код.

По сути, острова XAML UWP создаются с помощью API размещения XAML UWP. Этот API состоит из нескольких классов среда выполнения Windows и COM-интерфейсов, представленных в пакете SDK Windows 10 версии 1903. Кроме того, мы предоставляем набор элементов управления XAML Island .NET в Windows Community Toolkit, который использует API размещения XAML UWP внутри и обеспечивает более удобный опыт разработки для приложений WPF и Windows Forms.

Способ использования островов XAML UWP зависит от типа приложения и типов элементов управления UWP XAML, которые требуется разместить.

Требования

Для островов XAML UWP требуются следующие требования к среде выполнения:

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

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

Мы рекомендуем приложениям WPF и Windows Forms использовать элементы управления XAML Island .NET, доступные в Windows Community Toolkit. Эти элементы управления предоставляют объектную модель, которая имитирует (или предоставляет доступ) к свойствам, методам и событиям соответствующих элементов управления XAML UWP. Они также поддерживают такие действия, как навигация с помощью клавиатуры и изменение раскладки.

Существует два набора элементов управления XAML Island для приложений WPF и приложений Windows Forms: обернутые элементы управления и хост-элементы управления.

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

WPF и Windows Forms приложения могут использовать выбор элементов управления XAML Island, которые упаковывают интерфейс и функциональные возможности определенного элемента управления XAML UWP. Эти элементы управления можно добавить непосредственно на поверхность дизайна вашего проекта WPF или Windows Forms, а затем использовать их как любые другие элементы управления WPF или Windows Forms в конструкторе.

В настоящее время перечисленные ниже элементы управления UWP XAML доступны в наборе средств сообщества Windows.

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

Средства управления хостом

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

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

Настройте проект для использования элементов управления XAML Island .NET

Для элементов управления XAML Island .NET требуется Windows 10 версии 1903 или более поздняя. Чтобы использовать эти элементы управления, установите один из перечисленных ниже пакетов NuGet. Эти пакеты предоставляют все требуемые компоненты для использования заключенных в оболочку элементов управления XAML Island и элементов управления ведущего приложения и содержат другие связанные пакеты NuGet, которые также необходимы.

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

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

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

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

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

Чтобы использовать эти элементы управления, установите один из следующих пакетов NuGet:

• WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
• Windows Forms: Microsoft. Toolkit.Forms.UI.Controls.WebView

Настольные приложения C++ (Win32)

Элементы управления XAML Island .NET не поддерживаются в настольных приложениях C++. Вместо этого эти приложения должны использовать API размещения XAML UWP XAML предоставляемый пакетом SDK Windows 10 (версия 1903 и более поздние версии).

API размещения XAML UWP состоит из нескольких классов среда выполнения Windows и COM-интерфейсов, которые ваше классическое приложение C++ может использовать для размещения любого элемента управления XAML UWP, наследуемого от Windows.UI.Xaml.UIElement. Элементы управления XAML UWP можно разместить в любом элементе пользовательского интерфейса в приложении с соответствующим дескриптором окна (HWND). Дополнительные сведения об этом API доступны в следующих статьях:

• Использование API размещения XAML UWP в классическом приложении C++
• Размещение стандартного элемента управления XAML UWP в классическом приложении C++
• Размещение пользовательского элемента управления XAML UWP в классическом приложении C++

Архитектура XAML-островов UWP

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

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

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

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

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

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

✔️ Чтобы получить доступ к корневому элементу дерева содержимого XAML в XAML Island и получить связанные сведения о контексте, в котором он размещен, не используйте классы CoreWindow, ApplicationView и Window. Вместо этого используйте класс XamlRoot. Дополнительные сведения см. в этом разделе.

✔️ Чтобы поддерживать контракт Share из WPF, Windows Forms или приложения C++ класса Win32, ваше приложение должно использовать интерфейс IDataTransferManagerInterop, чтобы получить объект DataTransferManager для запуска операции общего доступа для конкретного окна. Пример использования этого интерфейса в приложении WPF см. в примере ShareSource.

✔️ Использование x:Bind с встроенными элементами управления в UWP XAML Islands не поддерживается. Необходимо объявить модель данных в .NET стандартной библиотеке.

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

🚫 Использование XAML Islands UWP в приложениях WPF и Windows Forms, ориентированных на .NET Framework. Острова XAML UWP поддерживаются только в приложениях, предназначенных для .NET Core 3.x.

🚫 содержимое XAML UWP в XAML Islands не реагирует на изменения темы Windows с темной на светлую или наоборот во время выполнения. Но содержимое реагирует во время выполнения на изменение режима высокой контрастности.

🚫Добавление элемента управления Windows.UI.Xaml.WebView. Сведения о приложениях WPF и WinForms см. в статье these alternatives.

🚫 Элементы управления MediaPlayer и MediaPlayerElement не поддерживаются в полноэкранном режиме.

🚫 Ввод текста в режиме рукописного ввода. Дополнительные сведения об этой возможности см. в этой статье.

🚫 Текстовые элементы управления, которые используют ссылки на содержимое @Places и @People. Дополнительные сведения об этой возможности см. в этой статье.

🚫 ОСТРОВА XAML UWP не поддерживают размещение ContentDialog, содержащего элемент управления, принимающий ввод текста, например TextBox, RichEditBox или AutoSuggestBox. В этом случае элемент управления для ввода не будет правильно реагировать на нажатие клавиш. Для реализации подобной функциональности с помощью XAML Island мы рекомендуем разместить класс Popup, содержащий элемент управления для ввода.

🚫 В настоящее время острова UWP XAML не поддерживают отображение файлов SVG в размещенном элементе управления Windows.UI.Xaml.Controls.Image или с использованием объекта Windows.UI.Xaml.Media.Imaging.SvgImageSource. В качестве решения преобразуйте файлы изображений, которые требуется отобразить, в растровые форматы, такие как JPG или PNG.

Контекст окна для XAML Islands

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

Например, чтобы получить ограничивающий прямоугольник окна, содержащего элемент управления XAML UWP, размещенный на острове XAML, используйте свойство XamlRoot.Size элемента управления. Так как каждый элемент управления XAML UWP, который можно разместить в XAML Island, является производным от Windows.UI.Xaml.UIElement, можно использовать свойство XamlRoot элемента управления для доступа к объекту XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

Не используйте свойство CoreWindows.Bounds для получения ограничивающего прямоугольника.

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

Интерфейсы API, связанные с окнами, которых следует избегать в контексте XAML Islands UWP, и рекомендуемые замены XamlRoot см. в таблице в этом разделе.

Пример использования этого интерфейса в приложении WPF см. в примере ShareSource.

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

Дополнительные справочные сведения и руководства по использованию островов XAML UWP см. в следующих статьях и ресурсах:

• Примеры кода UWP XAML Islands: Этот репозиторий содержит примеры для Windows Forms, WPF и настольных приложений на C++ (Win32), демонстрирующие использование XAML Islands UWP.
• Острова XAML UWP версии 1 — обновления и стратегия. В этой записи блога рассматривается множество распространенных вопросов о островах XAML UWP и предоставляет подробную стратегию разработки.