Custom Handlers în .NET MAUI 2026: Ghid Complet de Personalizare UI pentru iOS și Android

Actualizat: 20 august 2026

Un custom handler în .NET MAUI este stratul de cod care traduce un control cross-platform (de exemplu Entry sau Button) într-o vizualizare nativă pe fiecare platformă (UITextField pe iOS, AppCompatEditText pe Android) și îți dă control total peste comportamentul lor. Handlers au înlocuit sistemul de custom renderers din Xamarin.Forms cu o arhitectură pe două straturi bazată pe property mappers, care este mai rapidă, mai testabilă și mult mai simplu de întreținut la scală. Am migrat trei aplicații de producție de pe custom renderers pe handlers, iar diferența în timpul de startup și consumul de memorie a fost imediat vizibilă.

• Handlers folosesc o arhitectură pe două straturi: un control cross-platform (Virtual View) și o vizualizare nativă (Platform View) conectate printr-un mapper de proprietăți.
• În 90% din cazuri nu ai nevoie de un handler nou. Modifici un mapping existent cu Mapper.AppendToMapping(), fără să pierzi comportamentul implicit.
• Handlers sunt de 2–3 ori mai rapizi la instantiere decât custom renderers din Xamarin.Forms pentru că nu mai instanțiază un WeakReference wrapper pentru fiecare control.
• Migrarea de la custom renderers Xamarin.Forms se face cu Microsoft.Maui.Controls.Compatibility ca punte temporară, dar recomand rescrierea completă în 6–12 luni.
• Memory leaks apar aproape întotdeauna din event handlers native neînregistrați în DisconnectHandler(), așa că implementează-l pe toate handler-urile custom.
• Un handler bine scris rulează identic pe iOS, Android, Windows și macOS Catalyst fără #if platform, cu excepția implementărilor din Platforms/.

Ce sunt handlers în .NET MAUI?

Un handler este obiectul intermediar care unește un control cross-platform definit în XAML sau C# cu implementarea sa nativă pe fiecare platformă. Când scrii <Entry Text="Salut" />, .NET MAUI creează în spate un EntryHandler. Pe iOS, acest handler instanțiază un MauiTextField (o clasă care extinde UITextField); pe Android, un AppCompatEditText; pe Windows, un TextBox. Handler-ul este responsabil să sincronizeze proprietățile controlului virtual (VirtualView) cu proprietățile controlului nativ (PlatformView) în ambele direcții.

Această arhitectură este radical diferită de Xamarin.Forms. Acolo aveai un renderer care era el însuși un UIView sau Android.Views.View. Cu alte cuvinte, renderer-ul era vizualizarea nativă. În .NET MAUI, handler-ul este doar o punte: platform view-ul este o proprietate a lui, nu o clasă de bază. Rezultatul e că poți schimba complet vizualizarea nativă la runtime, poți testa handler-ul independent de UI-ul nativ și eviți penalitățile de moștenire multiplă. Documentația oficială Microsoft despre handlers descrie separarea pe două straturi ca fiind cel mai important câștig arhitectural al MAUI.

Fiecare handler expune două primitive esențiale: un PropertyMapper (un dicționar de tip proprietate → acțiune de sincronizare) și un CommandMapper (pentru evenimente și comenzi imperative precum focus). Aceste mappers sunt static, ceea ce înseamnă că modifici comportamentul global al unui control într-o singură linie în MauiProgram.cs. Este exact opusul modelului Xamarin, unde trebuia să înlocuiești complet renderer-ul cu [assembly: ExportRenderer].

Handlers vs Custom Renderers: de ce s-a schimbat arhitectura

Am scris zeci de custom renderers în Xamarin.Forms și, uitându-mă înapoi, cele mai multe erau workaround-uri pentru limitările modelului. Un custom renderer trebuia să moștenească din clasa de renderer implicită, să suprascrie OnElementChanged și să duplice mare parte din logica default doar ca să schimbe o culoare sau un font. Fiecare renderer aducea cu el un lanț de moștenire adânc (uneori 5–6 nivele) și un ciclu de viață greu de urmărit între Element și Control.

Handlers rezolvă asta prin decuplare. Iată comparația directă:

Aspect	Custom Renderer (Xamarin.Forms)	Handler (.NET MAUI)
Modificarea unei proprietăți	Subclasare completă a renderer-ului	O linie: Mapper.AppendToMapping()
Timp de instantiere	~2–3ms per control (Android)	~0.6–1ms per control
Testabilitate	Necesită UI runtime	Handler pur testabil în isolate
Arhitectură	Moștenire (renderer este nativul)	Compoziție (handler are nativul)
Înregistrare	[assembly: ExportRenderer]	ConfigureMauiHandlers()
Memory leaks	Frecvente prin ciclu Element↔Renderer	Controlabile prin DisconnectHandler()
Suport #if platform	Cod în proiecte separate	Cod unificat cu foldere Platforms/

Diferența practică cea mai mare, pe care am simțit-o cel mai tare într-o aplicație cu peste 1200 de Entry-uri într-un CollectionView vertical, este timpul de instantiere. Am măsurat cu Android Studio Profiler o reducere de 42% la startup după migrarea de la renderers la handlers. Câștigul vine din faptul că handler-ul nu creează un obiect nativ decât la ConnectHandler(), iar unele controluri sunt virtualizate. Practic, CollectionView le refolosește fără reinstantiere. Pentru o discuție detaliată despre optimizarea acestui tip de UI, vezi ghidul complet de optimizare a performanței în .NET MAUI.

Cum modifici un control existent fără custom handler

Regula pe care o dau echipei mele e simplă: înainte să scrii un handler nou, întreabă-te dacă poți modifica cel existent. În 90% din cazuri răspunsul e „da” și scapi de sute de linii de cod duplicat. Modificarea se face prin PropertyMapper.AppendToMapping(), care adaugă o acțiune peste comportamentul implicit, sau ModifyMapping(), care înlocuiește complet acțiunea pentru o proprietate.

Să luăm un exemplu concret. Vreau ca toate Entry-urile din aplicație să nu mai afișeze linia de subliniere pe Android și să nu mai afișeze bara de sugestii pe iOS. În Xamarin ar fi însemnat două custom renderers separate. În .NET MAUI, e un singur bloc de cod în MauiProgram.cs:

using Microsoft.Maui.Handlers;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder.UseMauiApp<App>();

    // Modifică toate Entry-urile din aplicație
    EntryHandler.Mapper.AppendToMapping("NoUnderline", (handler, view) =>
    {
#if ANDROID
        // Elimină linia inferioară pe Android
        handler.PlatformView.BackgroundTintList =
            Android.Content.Res.ColorStateList.ValueOf(
                Android.Graphics.Color.Transparent);
#elif IOS
        // Dezactivează bara de sugestii pe iOS 17+
        handler.PlatformView.InlinePredictionType =
            UIKit.UITextInlinePredictionType.No;
#endif
    });

    return builder.Build();
}

Trei observații importante despre codul de mai sus. Primul: cheia „NoUnderline” este un string arbitrar folosit pentru identificare. Dacă vrei ulterior să elimini modificarea, o poți face prin Mapper.PrependToMapping() cu aceeași cheie. Al doilea: handler.PlatformView este tipizat corect pentru fiecare platformă datorită directivelor de compilare, adică pe Android e AppCompatEditText, iar pe iOS e MauiTextField. Al treilea: modificarea rulează pentru fiecare instanță de Entry din aplicație, deci dacă vrei să afecteze doar unele controluri, folosește o subclasă și verifică if (view is MyBrandedEntry).

Pentru cazuri și mai simple, cum ar fi schimbarea unei culori sau a unui font pentru toate butoanele, poți folosi stiluri XAML implicite. Handlers sunt necesare doar când comportamentul dorit nu este expus ca proprietate a controlului virtual.

Cum creezi un custom handler complet pas cu pas

Când controlul de care ai nevoie nu are echivalent în MAUI (de exemplu un video player custom, un widget de semnătură sau un control 3D), trebuie să construiești un handler de la zero. Procesul are trei pași: definești o clasă cross-platform (Virtual View), definești interfața handler-ului și implementezi handler-ul pe fiecare platformă.

Pasul 1: Definește Virtual View-ul

Această clasă e ce vor folosi dezvoltatorii în XAML. Trăiește în proiectul principal, nu în Platforms/.

// Controls/SignaturePad.cs
using Microsoft.Maui.Controls;

public interface ISignaturePad : IView
{
    Color StrokeColor { get; }
    float StrokeWidth { get; }
    void Clear();
    Task<byte[]> ExportPngAsync();
}

public class SignaturePad : View, ISignaturePad
{
    public static readonly BindableProperty StrokeColorProperty =
        BindableProperty.Create(nameof(StrokeColor), typeof(Color),
            typeof(SignaturePad), Colors.Black);

    public static readonly BindableProperty StrokeWidthProperty =
        BindableProperty.Create(nameof(StrokeWidth), typeof(float),
            typeof(SignaturePad), 3f);

    public Color StrokeColor
    {
        get => (Color)GetValue(StrokeColorProperty);
        set => SetValue(StrokeColorProperty, value);
    }

    public float StrokeWidth
    {
        get => (float)GetValue(StrokeWidthProperty);
        set => SetValue(StrokeWidthProperty, value);
    }

    public void Clear() => Handler?.Invoke(nameof(Clear));

    public Task<byte[]> ExportPngAsync()
    {
        var tcs = new TaskCompletionSource<byte[]>();
        Handler?.Invoke(nameof(ExportPngAsync), tcs);
        return tcs.Task;
    }
}

Pasul 2: Definește handler-ul cross-platform

Handler-ul definește ce se sincronizează între virtual view și platform view. Fișierul este împărțit între o parte comună și fișiere per-platformă cu clase parțiale.

// Handlers/SignaturePadHandler.cs (partial în proiectul principal)
using Microsoft.Maui.Handlers;

public partial class SignaturePadHandler
{
    public static IPropertyMapper<ISignaturePad, SignaturePadHandler> Mapper =
        new PropertyMapper<ISignaturePad, SignaturePadHandler>(ViewHandler.ViewMapper)
        {
            [nameof(ISignaturePad.StrokeColor)] = MapStrokeColor,
            [nameof(ISignaturePad.StrokeWidth)] = MapStrokeWidth,
        };

    public static CommandMapper<ISignaturePad, SignaturePadHandler> CommandMapper =
        new(ViewHandler.ViewCommandMapper)
        {
            [nameof(ISignaturePad.Clear)] = MapClear,
            [nameof(ISignaturePad.ExportPngAsync)] = MapExportPng,
        };

    public SignaturePadHandler() : base(Mapper, CommandMapper) { }
    public SignaturePadHandler(IPropertyMapper mapper, CommandMapper commandMapper)
        : base(mapper, commandMapper) { }
}

Pasul 3: Implementare Android

Această clasă parțială merge în Platforms/Android/Handlers/SignaturePadHandler.Android.cs. Aici creezi platform view-ul concret și implementezi mapper-ii.

using Android.Graphics;
using Android.Views;
using Microsoft.Maui.Handlers;
using AView = Android.Views.View;

public partial class SignaturePadHandler : ViewHandler<ISignaturePad, MauiSignatureView>
{
    protected override MauiSignatureView CreatePlatformView() =>
        new MauiSignatureView(Context);

    protected override void ConnectHandler(MauiSignatureView platformView)
    {
        base.ConnectHandler(platformView);
        platformView.Touch += OnTouch;
    }

    protected override void DisconnectHandler(MauiSignatureView platformView)
    {
        platformView.Touch -= OnTouch;
        platformView.Dispose();
        base.DisconnectHandler(platformView);
    }

    void OnTouch(object? sender, AView.TouchEventArgs e) =>
        e.Handled = ((MauiSignatureView)sender!).HandleTouch(e.Event!);

    static void MapStrokeColor(SignaturePadHandler h, ISignaturePad v) =>
        h.PlatformView.PaintColor = v.StrokeColor.ToPlatform();

    static void MapStrokeWidth(SignaturePadHandler h, ISignaturePad v) =>
        h.PlatformView.PaintWidth = v.StrokeWidth;

    static void MapClear(SignaturePadHandler h, ISignaturePad v, object? arg) =>
        h.PlatformView.ClearCanvas();

    static void MapExportPng(SignaturePadHandler h, ISignaturePad v, object? arg)
    {
        if (arg is TaskCompletionSource<byte[]> tcs)
            tcs.TrySetResult(h.PlatformView.ToPng());
    }
}

Pasul 4: Implementare iOS (similar)

Fișierul Platforms/iOS/Handlers/SignaturePadHandler.iOS.cs urmează exact aceeași structură cu UIView ca platform view. Nu-l reproduc integral aici (din motive de spațiu), dar arhitectura este identică: CreatePlatformView(), ConnectHandler(), DisconnectHandler() și mapper-i statici.

Pasul 5: Înregistrează handler-ul în MauiProgram

builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<SignaturePad, SignaturePadHandler>();
});

Handler lifecycle și DisconnectHandler explicat

Ciclul de viață al unui handler are patru puncte critice: CreatePlatformView(), ConnectHandler(), DisconnectHandler() și dispose-ul implicit. Ordinea este: MAUI apelează CreatePlatformView exact o dată, apoi ConnectHandler când virtual view-ul este atașat, apoi mapper-ii pentru fiecare proprietate în ordinea din dicționar, iar la final DisconnectHandler când virtual view-ul este detașat (nu neapărat când e distrus).

Punctul cel mai important este DisconnectHandler. Spre deosebire de Xamarin.Forms, unde curățarea se făcea automat prin Dispose, în MAUI trebuie să te înregistrezi manual pentru curățarea event handler-ilor. MAUI nu apelează DisconnectHandler implicit, așa că trebuie să configurezi asta explicit în MauiProgram.cs:

#if IOS || ANDROID
Microsoft.Maui.Handlers.ViewHandler.ViewMapper.ModifyMapping(
    "DisconnectPolicy",
    (handler, view, action) => { /* setup automat */ });
#endif

// Sau, mai bine, apelează DisconnectHandler manual când e potrivit:
protected override void OnDisappearing()
{
    base.OnDisappearing();
    mySignaturePad.Handler?.DisconnectHandler();
}

Sincer, am debugat un memory leak de 40MB per navigare într-o aplicație în producție și cauza era exact asta: un handler care se abona la SensorManager pe Android și nu se dezabona niciodată. Fiecare pagină deschisă și închisă lăsa în memorie tot lanțul de obiecte (page → view → handler → sensor → activity). Fix-ul a fost două linii: dezabonarea în DisconnectHandler. Pentru diagnosticarea sistematică a leak-urilor recomand documentația Microsoft despre profilarea performanței MAUI.

Migrare de la Custom Renderers din Xamarin.Forms

Migrarea nu trebuie făcută dintr-o dată. .NET MAUI include Microsoft.Maui.Controls.Compatibility, un pachet care permite ca renderers Xamarin existenți să funcționeze aproape neschimbați. Pentru un proiect cu 40+ renderers, strategia pe care am aplicat-o cu succes de trei ori este:

1. Săptămâna 1: portezi codul cu compatibility layer activ. Renderers rămân neatinși. Aplicația trebuie să compileze și să ruleze pe iOS și Android.
2. Săptămânile 2–4: identifici cele 5–10 renderers cu impact maxim (cele apelate frecvent în listări, formulare) și le rescrii ca handlers. Măsori impactul cu Profiler.
3. Lunile 2–6: rescrii progresiv restul. Prioritate mare pentru cele care aveau leak-uri sau probleme cunoscute în Xamarin.
4. Lunile 6–12: elimini pachetul de compatibility. Punctul acesta este important, pentru că, atât timp cât îl păstrezi, ai două arhitecturi paralele și dublezi mental cost-ul de întreținere.

Un pattern util în timpul migrării este să folosești ghidul complet de migrare Xamarin.Forms la .NET MAUI ca listă de referință. Combină-l cu articolul despre MVVM în .NET MAUI 9 cu CommunityToolkit.Mvvm ca să-ți restructurezi ViewModel-urile în timp ce reconstruiești handlers. Sunt schimbări care se potrivesc bine împreună.

Best practices și greșeli comune în producție

După ce am dus trei aplicații în producție cu handlers custom, iată lecțiile care contează cel mai mult. Sunt în ordinea impactului real, nu a frecvenței cu care apar în bloguri.

1. Nu subclasa handler-ele native, modifică mapper-ul

Cel mai frecvent antipattern pe care îl văd este dezvoltatori care fac public class MyEntryHandler : EntryHandler doar ca să suprascrie o metodă. Aproape întotdeauna soluția corectă este EntryHandler.Mapper.ModifyMapping(). Subclasarea te leagă de detalii interne ale MAUI care se pot schimba între versiuni minore.

2. Nu accesa Handler.PlatformView din ViewModel

Am văzut cod care făcea await ((MyPage)Application.Current.MainPage).myEntry.Handler.PlatformView.SomeMethod(). E o încălcare directă a MVVM și dovada că API-ul virtual view-ului este insuficient. Extinde interfața controlului cu o metodă și expune-o prin CommandMapper.

3. Testează handler-ul izolat

Handlers pot fi testate fără UI real folosind HandlerStub din pachetul de test MAUI. Un test unitar de handler rulează în milisecunde și prinde regresii pe care testele UI nu le detectează. Am integrat asta cu setup-ul din ghidul de testing în .NET MAUI 2026.

4. Fii atent la thread-uri

Mapper-ii rulează întotdeauna pe UI thread. Dacă chemi ceva blocant acolo, blochezi întreaga aplicație. Folosește MainThread.BeginInvokeOnMainThread pentru callback-uri din operații asincrone care actualizează platform view-ul.

5. Documentează cheile mapping-ului

Cheile pentru AppendToMapping() sunt string-uri. Când ai 15 modificări globale pe EntryHandler, e imposibil să știi ce face fiecare fără o convenție. Folosesc format "Domain_Feature", de exemplu "Branding_NoUnderline" sau "A11y_LargerFont".

Întrebări frecvente

Care este diferența dintre handlers și custom renderers?

Custom renderers din Xamarin.Forms erau clase care moșteneau vizualizarea nativă și trebuiau înlocuite complet ca să modifici comportamentul. Handlers din .NET MAUI sunt obiecte separate care conțin vizualizarea nativă și pot fi modificate prin mappers statici fără subclasare. Rezultatul este cod mai rapid, mai puțin duplicat și mai ușor de testat.

Pot folosi în continuare custom renderers din Xamarin.Forms în .NET MAUI?

Da, prin pachetul Microsoft.Maui.Controls.Compatibility. Este util în timpul migrării, dar Microsoft nu adaugă funcționalități noi în acel layer, iar performanța este semnificativ mai mică decât la handlers native. Recomandarea mea este să-l folosești maxim 6–12 luni.

Când trebuie să creez un custom handler și când e suficient un mapping?

Modifică un mapping existent când vrei să schimbi comportamentul unui control care există deja (Entry, Button, Editor etc.). Creează un handler nou doar când controlul de care ai nevoie nu are echivalent MAUI, cum ar fi un semnătură pad, un player video custom sau un chart nativ.

De ce apare memory leak după navigarea între pagini?

Cauza este aproape întotdeauna un event handler nativ înregistrat în ConnectHandler() și niciodată dezabonat în DisconnectHandler(). .NET MAUI nu apelează automat DisconnectHandler, deci trebuie să-l apelezi manual în OnDisappearing sau să configurezi politica de disconnect global.

Handlers funcționează la fel pe Windows și macOS Catalyst?

Da, arhitectura este identică. Diferența este că PlatformView devine FrameworkElement pe Windows și UIView pe Mac Catalyst (același ca iOS). Implementezi handler-ele în Platforms/Windows/ și Platforms/MacCatalyst/ cu aceeași structură partial class.