maui-custom-handlers

.NET MAUI 自定义处理程序

决策：自定义现有控件还是创建新控件

场景	方案
更改内置控件在某个平台上的外观或行为	自定义 — 使用 AppendToMapping / PrependToMapping
只需要更改控件的某些实例	自定义 — 派生控件子类 + 在映射器中进行类型检查
需要一个带有原生实现的全新跨平台控件	使用分部类创建新处理程序

⚠️ 优先使用 AppendToMapping，而不是 ModifyMapping。ModifyMapping 会完全替换默认映射器操作——如果框架在未来版本中添加了行为，你的重写会悄无声息地将其丢弃。

---

注意事项与常见错误

映射器自定义会全局生效

控件的每个实例都会受到影响。要实现针对特定实例的行为，请使用子类检查进行保护：

// ❌ Removes borders from EVERY Entry in the app
EntryHandler.Mapper.AppendToMapping("NoBorder", (handler, view) =>
{
#if ANDROID
    handler.PlatformView.Background = null;
#endif
});

// ✅ Only affects BorderlessEntry instances
EntryHandler.Mapper.AppendToMapping("NoBorder", (handler, view) =>
{
    if (view is not BorderlessEntry) return;
#if ANDROID
    handler.PlatformView.Background = null;
#endif
});

在 HandlerChanging 中取消订阅原生事件

未能移除原生事件处理程序会导致内存泄漏，因为原生视图的生命周期可能长于托管包装器。

// ❌ Subscribes but never unsubscribes — leaks
entry.HandlerChanged += (s, e) =>
{
#if ANDROID
    ((Entry)s!).Handler!.PlatformView.As<Android.Widget.EditText>()!
        .FocusChange += OnNativeFocusChange;
#endif
};

// ✅ Pair subscribe in HandlerChanged with unsubscribe in HandlerChanging
entry.HandlerChanged += OnHandlerChanged;
entry.HandlerChanging += OnHandlerChanging;

分部类名称／命名空间不匹配

共享处理程序文件和每个平台文件中的命名空间与类名必须完全一致。不匹配会悄无声息地创建独立的类——不会出现编译错误，只会导致处理程序在该平台上不起作用。

条件 using 的位置

using PlatformView = ... 别名必须位于共享处理程序文件的顶部（而不是平台文件中），这样 ViewHandler<TControl, TPlatformView> 基类泛型才能根据平台正确解析。

// ✅ Top of Handlers/VideoPlayerHandler.cs
#if ANDROID
using PlatformView = Android.Widget.VideoView;
#elif IOS || MACCATALYST
using PlatformView = AVKit.AVPlayerViewController;
#elif WINDOWS
using PlatformView = Microsoft.UI.Xaml.Controls.MediaPlayerElement;
#endif

缺少 CreatePlatformView()

每个平台的分部类都必须重写 CreatePlatformView()。省略此方法会导致编译错误——但错误信息指向的是基类，而不是你的处理程序，因此很难排查。

---

映射器方法的选择

方法	风险	使用场景
AppendToMapping	低 — 在默认行为之后运行	添加行为而不破坏默认行为
PrependToMapping	低 — 在默认行为之前运行	设置可能被默认行为覆盖的初始状态
ModifyMapping	⚠️ 高 — 替换默认行为	你有意要抑制框架的映射器逻辑

---

PropertyMapper 与 CommandMapper

映射器	用途	模式
PropertyMapper	将可绑定属性同步到原生视图	每当属性值更改时运行
CommandMapper	从控件触发到处理程序的即发即弃操作	每次调用运行一次，不返回值

⚠️ 不要将属性同步逻辑放入 CommandMapper——属性更改时它不会重新运行，导致原生视图状态过时。

---

清单 — 新建处理程序

• 跨平台控件继承自 View（或适当的基类）
• 共享处理程序文件包含条件 using PlatformView = ... 别名
• 处理程序继承自 ViewHandler<TControl, PlatformView>
• PropertyMapper 映射每个可绑定属性
• 每个平台的分部类都重写 CreatePlatformView()
• 所有分部文件中的命名空间和类名完全相同
• 通过 ConfigureMauiHandlers 在 MauiProgram.cs 中注册处理程序
• 在 HandlerChanging 中清理原生事件订阅