Размещение элементов управления WinRT XAML в настольных приложениях (XAML Islands)

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

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

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

По сути, острова XAML создаются с помощью API размещения WinRT XAML. Этот API состоит из нескольких классов Windows Runtime и COM-интерфейсов, представленных в пакете SDK Windows 10 версии 1903. Кроме того, мы предоставляем набор элементов управления XAML Island .NET в Windows Community Toolkit, которые используют API размещения XAML WinRT и обеспечивают более удобный опыт разработки для приложений 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 Community Toolkit. Эти элементы управления предоставляют объектную модель, которая имитирует свойства, методы и события соответствующих элементов управления 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 также предоставляет следующие элементы управления .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 WinRT XAML, предоставляемый пакетом SDK Windows 10 (версия 1903 и более поздние версии).

API размещения WinRT XAML состоит из нескольких классов Windows Runtime и 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 динамических зависимостей.

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

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

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

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

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

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

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

🚫 Элементы управления 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 см. в следующих статьях и ресурсах:

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