Налаштування елементів керування в .NET MAUI

Примітка. Це гостьовий допис у блозі від Microsoft MVP, Педро Хесус. Педро працює програмним інженером у Nareia та є основним розробником .NET MAUI Community Toolkit

Сьогодні я хочу поговорити про те, як можна повністю налаштувати елементи керування в .NET MAUI. Перш ніж дивитися на .NET MAUI, повернімось на пару років назад, до епохи Xamarin.Forms. Тоді у нас було кілька способів налаштувати елементи керування: у нас були Behaviors, які використовувалися, коли вам не потрібен доступ до специфічних для платформи API для налаштування елементів керування; і ми мали Effects, якщо вам потрібно отримати доступ до специфічних для платформи API.

Зупинимося трохи на Effects API. Він був створений через відсутність у Xamarin багатоцільової архітектури. Це означає, що ми не можемо отримати доступ до специфічного для платформи коду на загальному рівні (у .NET Standard csproj). Це спрацювало досить добре і може позбавити вас від створення Custom Renderers.

Сьогодні в .NET MAUI ми можемо використовувати потужність багатоцільової архітектури та отримати доступ до специфічних для платформи API у нашому спільному проєкті. Так нам ще потрібно Effects? Ні, тому що ми маємо доступ до всього коду та API з усіх цільових платформ.

Примітка: .NET MAUI все ще підтримує Effects якщо ви хочете їх використовувати, однак це не рекомендується

Посилання на вихідний код взято з IconTintColor .NET MAUI Community Toolkit.

Налаштування наявного елемента керування

Щоб додати додаткові функції до наявного елемента керування, ми розширюємо його та додаємо потрібні функції.

Давайте створимо новий елемент керування  class ImageTintColor : Image та додамо новий BindableProperty, який ми будемо використовувати для зміни кольору відтінку Image.

Люди, знайомі з Xamarin.Forms, впізнають це; це практично той самий код, який ви будете писати в програмі Xamarin.Forms.

Робота API для платформи .NET MAUI відбуватиметься на делегаті OnTintColorChanged. Подивімось на це.

Оскільки .NET MAUI використовує багатоцільове націлювання, ми можемо отримати доступ до особливостей платформи та налаштувати елементи керування так, як хочемо. Методи ImageExtensions.ApplyColor та ImageExtensions.ClearColor є допоміжними методами, які додають або видаляють відтінок зображення.

Одна річ, яку ви, можливо, помітили, це перевірка null для Handler та PlatformView. Це перший дракон, якого ви можете зустріти на своєму шляху. Коли елемент керування Image створюється, і  PropertyChanged як делегат BindableProperty викликається, Handler може бути null. Отже, без перевірки на нуль код видасть NullReferenceException. Це може здатися помилкою, але насправді це функція! Це дозволяє групі розробників .NET MAUI підтримувати той самий життєвий цикл, який мають елементи керування на Xamarin.Forms, уникаючи деяких руйнівних змін для програм, які будуть мігрувати з Forms на .NET MAUI.

Тепер, коли ми все налаштували, ми можемо використовувати наш елемент керування на нашому ContentPage. У наведеному нижче фрагменті ви можете побачити, як використовувати його в XAML:

Використання Attached Property та PropertyMapper

Інший спосіб налаштувати елемент керування — це використання AttachedProperties, це варіант BindableProperty, коли вам не потрібно прив’язувати його до певного спеціального елемента керування.

Ось як ми можемо створити AttachedProperty для TintColor:

Знову ми маємо шаблон, який ми маємо на Xamarin.Forms для AttachedProperty, але, як бачите, у нас немає делегата PropertyChanged. Щоб обробити зміну властивості, ми будемо використовувати Mapper в ImageHandler. Ви додаєте Mapper на будь-якому рівні, оскільки учасниками є static. Я вирішив зробити це всередині класу TintColorMapper, як ви бачите нижче.

Код майже такий самий, як показано раніше, лише реалізований за допомогою іншого API, у цьому випадку методу AppendToMapping. Якщо ви не бажаєте такої поведінки, скористайтеся CommandMapper натомість, вона буде активована лише тоді, коли змінюється властивість або виконується дія.

Майте на увазі, що коли ми обробляємо з Mapper і CommandMapper, ми додаємо цю поведінку для всіх елементів керування, які використовують цей обробник у проекті. У цьому випадку всі елементи керування Image запускатимуть цей код. У деяких випадках це не те, що ви хочете, якщо ви щось потребуєте щось більш конкретне, використання PlatformBehavior ідеально підійде.

Отже, тепер, коли ми все налаштували, ми можемо використовувати наш елемент керування на нашій сторінці, у фрагменті нижче ви можете побачити, як використовувати його в XAML.

Використання PlatformBehavior

PlatformBehavior це новий API, створений на .NET MAUI, щоб полегшити завдання налаштування елементів керування, коли вам потрібно отримати доступ до специфічних для платформи API безпечним способом (безпечним, оскільки він гарантує, що  Handler та PlatformView не є  null). Він має два методи override: OnAttachedTo та OnDetachedFrom. Цей API існує, щоб замінити API Effect від Xamarin.Forms і скористатися перевагами багатоцільової архітектури.

У цьому прикладі ми будемо використовувати partial class для реалізації специфічних для платформи API:

Наведений вище код буде скомпільовано всіма цільовими платформами.

Тепер давайте подивимося код для платформи Android:

А ось код для платформи iOS:

Як бачите, нам не потрібно піклуватися про те, чи є Handler, null, тому що PlatformBehavior робить це для нас.

Ми можемо вказати тип API для конкретної платформи, який охоплює ця поведінка. Якщо ви хочете застосувати елемент керування для кількох типів, вам не потрібно вказувати тип перегляду платформи (наприклад, використовуйте PlatformBehavior); ви, ймовірно, захочете застосувати свою  Behavior у кількох елементах керування, у такому випадку platformView буде PlatformBehavior на Android і PlatformBehavior на iOS.

І використання стане ще кращим, вам просто потрібно викликати Behavior:

Висновок

У цьому дописі в блозі ми обговорили різні способи налаштування елементів керування та взаємодії з API певної платформи. Немає жодного right або wrong способу, усі ці рішення є правильними, вам просто потрібно побачити, яке краще підійде для вашого випадку. Я б сказав, що в більшості випадків ви захочете використовувати, PlatformBehavior оскільки він розроблений для роботи з багатоцільовим підходом і гарантує очищення ресурсів, коли елемент керування більше не використовується. Щоб дізнатися більше, перегляньте документацію щодо спеціальних елементів керування.

Source

На конференции Microsoft Build было объявлено, что Windows 10 May 2019 Update (версия 1903) будет включать XAML Islands v1.

Ниже Вы можете ознакомиться с более подробной информацией плана выпуска и двух рабочих направлений в процессе разработки: .NET обертки и поддержка Visual Studio 2019.

Что такое XAML Islands?

XAML Islands позволяют .NET и нативным Win32 приложениям размещать элементы управления UWP XAML. Вы можете расширить возможности и функциональность Ваших существующих десктопных приложений с помощью последних инноваций пользовательского интерфейса, ранее доступных только для UWP приложений. Например, Вы можете использовать такие элементы управления, как ColorPicker, InkCanvas, CalendarView и NavigationView, в Ваших существующих C ++ Win32, Windows Forms и WPF приложениях.

С XAML Islands Вы можете модернизировать Ваше приложение в собственном стиле без необходимости переписывать его заново – просто используйте элементы управления UWP XAML.

Как использовать XAML Islands?

Первый компонент – API  UWP XAML хостинг. Это набор API Windows 10 (Windows Runtime классы и COM интерфейсы), которые поставляются на Windows 10 в версии 1903. Если у Вас есть нативное C ++ Win32 приложение, использующее Common Controls библиотеку (Comctl32.dll) или MFC, и Вам необходимо модернизировать Ваш интерфейс, смело используйте эти API.

Второй компонент состоит из обернутых .NET элементов управления и элементов управления хоста. Это набор оберток API  UWP XAML хостинга в Windows Community Toolkit как для Windows Forms, так и для WPF разработчиков.

Каковы требования для использования XAML Islands в Ваших приложениях?

• Windows 10 версии 1903 и выше: Независимо от того, есть ли у Вас Win32 или .NET приложение, текущая версия XAML Islands работает только с приложениями для Windows 10 версии 1903 и выше.
• Windows 10 SDK версия 1903 (10.0.18362): этот SDK содержит заголовки, библиотеки, метаданные и инструменты для сборки Windows 10 приложений, используя XAML Islands.
• Упакованное десктопное приложение: Десктопные приложения можно упаковать в MSIX для доступа к определенным Windows 10 API, таким как живые тайлы и уведомления. Для упаковки Вашего приложения необходимо использовать Windows Application Packaging Project. Упаковка Вашего приложения не означает, что оно будет работать в изолированной программной среде с ограниченными UWP привилегиями. Вместо этого Ваше упакованное Win32 приложение будет работать в режиме полного доверия. Упакованные с XAML Islands приложения будут оптимизированы для разработчиков, которые работают с Visual Studio 2019.

Обратите внимание: В этом выпуске неупакованные приложения будут иметь ограниченную поддержку, но возможны некоторые сценарии.

• Visual Studio 2019: только Visual Studio 2019 будет иметь набор инструментов, необходимый для сборки десктопных приложений с использованием XAML Islands.
• .NET Core 3.0: эта среда полностью поддерживается для .NET приложений. Некоторые сценарии также будут работать в приложениях, предназначенных для .NET Framework 4.7.2, но для этих приложений существуют некоторые ограничения, например использование управляемых сторонних элементов управления.

• Если сторонний WinRT компонент является нативным (написан на C ++ / WinRT), пользовательский элемент управления может использоваться как .NET Framework 4.7.2, так и как NET Core 3.
• Если сторонний WinRT компонент является управляемым (например, написан на C#), пользовательский элемент управления может использоваться только на .NET Core 3. Полная версия .NET Framework не полностью поддерживается в этом сценарии, и она требует некоторой кросс-компиляции для того, чтобы работать на всех.

Таблица поддержки платформы для XAML Islands в1:

Если Ваше приложение нацелено на .NET Core 3, независимо от того, является ли сторонний WinRT компонент, который Вы размещаете, нативным или управляемым, Вы получите оптимизированный опыт работы. Если Ваше приложение нацелено на полную .NET Framework версию, Вы получите оптимизированный опыт, только если Ваш сторонний WinRT компонент является нативным.

Как использовать XAML Islands в Вашем нативном C ++ Win32 приложении?

Если Вы C ++ разработчик, Вам нужно использовать API UWP XAML хостинга. Вот одни из основных шагов:

• Сначала инициализируется UWP XAML структура в текущем потоке (Вы можете использовать статический InitializeForCurrentThread метод для WindowsXamlManager класса).
• Создайте DesktopWindowXamlSource объект, который требует HWND от Вашего приложения. DesktopWindowXamlSource создаст ChildWindow, где Вы сможете разместить XAML контент.
• Вам нужно позаботиться о фокусировке клавиатуры, когда пользователи переходят на XAML Islands и выходят из них. Этот DesktopWindowXamlSource объект предоставляет событие для распределения фокусировки клавиатуры.

Вы можете ознакомиться с более подробной информацией здесь: https://docs.microsoft.com/en-us/windows/apps/desktop/modernize/using-the-xaml-hosting-api

Как использовать XAML Islands в Вашем .NET приложении?

Windows Community Toolkit версии 6.0.0 (на данный момент в preview-версии) предоставляет несколько NuGet пакетов для Windows Forms и WPF, которые Вы можете добавить в Ваш проект.

Элемент управления WindowXamlHost является хост-элементом, в котором можно размещать все типы UWP XAML контента.

Обернутые элементы управления создаются для работы с большинством событий и свойств небольшого набора определенных UWP элементов в WPF и Windows Forms элементы. В настоящее время предоставляются следующие упакованные элементы управления:

• InkCanvas оборачивает UWP InkCanvas и InkToolbar и предоставляет поверхность и панели инструментов для взаимодействия с Ink пользователем.
• MediaPlayerElement позволяет Вашим .NET приложениям использовать современные аудио- и видео-кодеки и предоставляет более высокую производительность для потоковой передачи и воспроизведения медиа контента.
• MapControl позволяет использовать в Ваших приложениях последние инновации картографической платформы, например, больше фотореалистичных карт.
• SwapChainPanel (preview-версия) позволяет добавлять DirectX 12 контент в Ваше приложение.

Какие современные веб элементы доступны для десктопных приложений?

Windows Forms и WPF приложения используют элемент управления WebBrowser, который использует рендеринг Internet Explorer и поэтому не поддерживает HTML5 и другие функции. Windows Community Toolkit содержит Windows Forms и WPF обертки для UWP WebView элемента, который использует Edge в качестве инструмента рендеринга, поэтому эти приложения могут размещать веб-контент, который требуюется на HTML5.

Windows Community Toolkit также содержит элемент управления WebViewCompatible. Этот элемент использует либо WebBrowser, либо WebView рендеринг, в зависимости от Windows версии, на которой работает приложение:

• Приложения для Windows 10 версии 1803 и выше будут использовать текущий инструмент WebView рендеринга.
• Приложения для более ранних Windows версий, таких как Windows 8.1, будут использовать более старый инструмент WebBrowser рендеринга.

Используют ли XAML Islands другой поток?

Нет. XAML Islands работают в том же потоке пользовательского интерфейса Вашего десктопного приложения. Вы можете сразу получить доступ ко всем UWP XAML объектам из Вашего кода. Это отличается от Windows Forms и WPF технологий.

Есть ли инструкции?

XAML Islands Lab предоставляет пошаговые инструкции по использованию обернутых элементов управления и хост-элементов в Windows Community Toolkit для добавления UWP элементов управления в уже существующее WPF приложение. Эта работа включает в себя полный код для WPF приложения, а также подробные инструкции для каждого этапа.

Этот C ++ Win32 образец демонстрирует полную реализацию размещения пользовательского UWP элемента управления в неупакованном C ++ Win32 приложении (то есть приложении, которое не встроено в MSIX пакет).

Для WPF .NET Core 3 приложения, которое использует UWP проект в User Control, Вы можете использовать следующее:

• https://aka.ms/xamlislandssamples 

Windows Community Toolkit содержит демонстрационные версии для проверки обернутого элемента управления и хост-элемента.

• https://github.com/windows-toolkit/Microsoft.Toolkit.Win32

Каков план выпуска XAML Islands в1?

1. Windows 10 May 2019 Update содержит первый выпуск XAML Islands (в1).

2. Windows Community Toolkit, версии 6.0, будет содержать WindowsXamlHost и упакованные элементы управления для .NET Framework.

• Это запланировано на лето 2019 года.
• Будет preview-версия 6.1, которая будет содержать WindowsXamlHost .NET Core 3 версию и упакованные элементы управления. Это обновление будет выпущено вместе с .NET Core 3 – во второй половине 2019 года.

3. Visual Studio 2019 обновится во второй половине 2019 года вместе с .NET Core 3, который будет поддерживать XAML Islands в1. Помните, что только с упакованными приложениями Вы получите оптимизированный опыт работы.

Каков план выпуска XAML Islands в2?

XAML Islands в2 будет поставляться в составе WinUI 3.0. Следовательно, вторая версия будет поддерживать те же Windows 10 версии, что и WinUI 3.0. Основной выпуск WinUI v3 запланирован на первую половину 2020 года. WinUI – это проект с открытым исходным кодом, и Вы можете следить за последними событиями здесь: https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md 

Где оставить отзыв о XAML Islands?

• Основной канал – GitHub: https://github.com/microsoft/microsoft-ui-XAML
• Вы также можете написать на XAML Islands Feedback@microsoft.com
• Или твитнуть на странице @windowsui
• Если у Вас возникнут трудности с .NET обертками, Вы также можете связаться со службой поддержки по адресу https://github.com/windows-toolkit/Microsoft.Toolkit.Win32

Visifire – это набор элементов управления для визуального отображения данных в Silverlight и WPF приложениях. Они позволяют создавать диаграммы для различного вида приложений используя один и тот же API. Элементы управления Visifire для Silverlight могут быть легко встроены в веб страницу как стандартное Silverlight приложение. Visifire не зависимое от серверной части решение и может использоваться вместе с ASP, ASP.Net, SharePoint, PHP, JSP, ColdFusion, Python, Ruby или только простым HTML.

Сейчас это решение можно использовать и в приложениях для Windows Phone 7.

Описание как использовать решение в Windows Phone 7 приложениях читайте здесь