هندلرهای سفارشی در .NET MAUI: راهنمای کامل PropertyMapper و توسعه کنترل‌های بومی در ۲۰۲۶

// MauiProgram.cs
using Microsoft.Maui.Handlers;

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

    Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("NoUnderline", (handler, view) =>
    {
#if IOS
        handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
        handler.PlatformView.Layer.BorderWidth = 0;
#elif ANDROID
        handler.PlatformView.BackgroundTintList =
            Android.Content.Res.ColorStateList.ValueOf(
                Android.Graphics.Color.Transparent);
#endif
    });

    return builder.Build();
}

// Controls/ColorPickerView.cs
using Microsoft.Maui.Controls;
using Microsoft.Maui.Graphics;

public interface IColorPickerView : IView
{
    Color SelectedColor { get; set; }
    void OpenPicker();
}

public class ColorPickerView : View, IColorPickerView
{
    public static readonly BindableProperty SelectedColorProperty =
        BindableProperty.Create(
            nameof(SelectedColor),
            typeof(Color),
            typeof(ColorPickerView),
            Colors.Black,
            BindingMode.TwoWay);

    public Color SelectedColor
    {
        get => (Color)GetValue(SelectedColorProperty);
        set => SetValue(SelectedColorProperty, value);
    }

    public event EventHandler<Color>? ColorChanged;

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

    internal void RaiseColorChanged(Color color)
    {
        SelectedColor = color;
        ColorChanged?.Invoke(this, color);
    }
}

// Handlers/ColorPickerViewHandler.cs
using Microsoft.Maui.Handlers;

public partial class ColorPickerViewHandler
{
    public static IPropertyMapper<IColorPickerView, ColorPickerViewHandler> PropertyMapper =
        new PropertyMapper<IColorPickerView, ColorPickerViewHandler>(ViewHandler.ViewMapper)
        {
            [nameof(IColorPickerView.SelectedColor)] = MapSelectedColor
        };

    public static CommandMapper<IColorPickerView, ColorPickerViewHandler> CommandMapper =
        new(ViewHandler.ViewCommandMapper)
        {
            [nameof(IColorPickerView.OpenPicker)] = MapOpenPicker
        };

    public ColorPickerViewHandler() : base(PropertyMapper, CommandMapper) { }
}

// Platforms/iOS/Handlers/ColorPickerViewHandler.cs
using Microsoft.Maui.Handlers;
using UIKit;
using CoreGraphics;

public partial class ColorPickerViewHandler : ViewHandler<IColorPickerView, UIView>
{
    UIColorPickerViewController? _pickerController;

    protected override UIView CreatePlatformView()
    {
        var view = new UIView { BackgroundColor = UIColor.SystemBackground };
        var tap = new UITapGestureRecognizer(OnTapped);
        view.AddGestureRecognizer(tap);
        return view;
    }

    protected override void ConnectHandler(UIView platformView)
    {
        base.ConnectHandler(platformView);
        platformView.Layer.CornerRadius = 8;
        platformView.Layer.BorderWidth = 1;
        platformView.Layer.BorderColor = UIColor.SystemGray4.CGColor;
    }

    protected override void DisconnectHandler(UIView platformView)
    {
        if (_pickerController != null)
        {
            _pickerController.ValueChangedEvent -= OnColorChanged;
            _pickerController.Dispose();
            _pickerController = null;
        }
        base.DisconnectHandler(platformView);
    }

    static void MapSelectedColor(ColorPickerViewHandler handler, IColorPickerView view)
    {
        handler.PlatformView.BackgroundColor = view.SelectedColor.ToPlatform();
    }

    static void MapOpenPicker(ColorPickerViewHandler handler, IColorPickerView view, object? args)
    {
        handler._pickerController = new UIColorPickerViewController
        {
            SupportsAlpha = false,
            SelectedColor = view.SelectedColor.ToPlatform()
        };
        handler._pickerController.ValueChangedEvent += handler.OnColorChanged;

        var root = UIApplication.SharedApplication
            .ConnectedScenes.OfType<UIWindowScene>()
            .SelectMany(s => s.Windows)
            .FirstOrDefault(w => w.IsKeyWindow)?
            .RootViewController;

        root?.PresentViewController(handler._pickerController, true, null);
    }

    void OnTapped() => (VirtualView as ColorPickerView)?.OpenPicker();

    void OnColorChanged(object? sender, EventArgs e)
    {
        if (_pickerController == null) return;
        var color = _pickerController.SelectedColor.ToColor();
        (VirtualView as ColorPickerView)?.RaiseColorChanged(color);
    }
}

// Platforms/Android/Handlers/ColorPickerViewHandler.cs
using Android.App;
using Android.Content;
using Android.Graphics.Drawables;
using Android.Views;
using Android.Widget;
using Microsoft.Maui.Handlers;
using Microsoft.Maui.Platform;

public partial class ColorPickerViewHandler : ViewHandler<IColorPickerView, Android.Views.View>
{
    AlertDialog? _dialog;

    protected override Android.Views.View CreatePlatformView()
    {
        var context = Context ?? throw new InvalidOperationException("Context is null");
        var view = new Android.Views.View(context);
        view.Click += OnClick;
        return view;
    }

    protected override void ConnectHandler(Android.Views.View platformView)
    {
        base.ConnectHandler(platformView);
        var shape = new GradientDrawable();
        shape.SetCornerRadius(16f);
        shape.SetStroke(2, Android.Graphics.Color.LightGray);
        platformView.Background = shape;
    }

    protected override void DisconnectHandler(Android.Views.View platformView)
    {
        platformView.Click -= OnClick;
        _dialog?.Dispose();
        _dialog = null;
        base.DisconnectHandler(platformView);
    }

    static void MapSelectedColor(ColorPickerViewHandler handler, IColorPickerView view)
    {
        if (handler.PlatformView.Background is GradientDrawable drawable)
        {
            drawable.SetColor(view.SelectedColor.ToPlatform());
        }
    }

    static void MapOpenPicker(ColorPickerViewHandler handler, IColorPickerView view, object? args)
    {
        var context = handler.Context;
        if (context == null) return;

        var seekR = new SeekBar(context) { Max = 255, Progress = view.SelectedColor.ToPlatform().R };
        var seekG = new SeekBar(context) { Max = 255, Progress = view.SelectedColor.ToPlatform().G };
        var seekB = new SeekBar(context) { Max = 255, Progress = view.SelectedColor.ToPlatform().B };

        var layout = new LinearLayout(context) { Orientation = Orientation.Vertical };
        layout.SetPadding(48, 32, 48, 32);
        layout.AddView(seekR);
        layout.AddView(seekG);
        layout.AddView(seekB);

        handler._dialog = new AlertDialog.Builder(context)
            .SetTitle("انتخاب رنگ")
            .SetView(layout)
            .SetPositiveButton("تایید", (s, e) =>
            {
                var color = Microsoft.Maui.Graphics.Color.FromRgb(
                    seekR.Progress, seekG.Progress, seekB.Progress);
                (handler.VirtualView as ColorPickerView)?.RaiseColorChanged(color);
            })
            .SetNegativeButton("انصراف", (s, e) => { })
            .Create();

        handler._dialog.Show();
    }

    void OnClick(object? sender, EventArgs e) => (VirtualView as ColorPickerView)?.OpenPicker();
}

// MauiProgram.cs
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
        })
        .ConfigureMauiHandlers(handlers =>
        {
            handlers.AddHandler<ColorPickerView, ColorPickerViewHandler>();
        });

#if DEBUG
    builder.Logging.AddDebug();
#endif

    // فعال‌سازی رفتار خودکار DisconnectHandler برای جلوگیری از نشت حافظه
    Microsoft.Maui.Handlers.HandlerDisconnectPolicy = HandlerDisconnectPolicy.Automatic;

    return builder.Build();
}

[Fact]
public void SelectedColor_Updates_PlatformView_Background()
{
    var handler = new StubColorPickerViewHandler();
    var view = new ColorPickerView { SelectedColor = Colors.Red };
    view.Handler = handler;

    handler.UpdateValue(nameof(IColorPickerView.SelectedColor));

    Assert.Equal(Colors.Red, handler.LastAppliedColor);
}