MAUI的跨平台能力建立在XAML和平台抽象之上，但很多时候业务需求会依赖某个平台独有的控件，比如Android的Material组件库里的自定义View，或者iOS上某个第三方图表控件。这种场景下，与其重新用MAUI的绘制API去模拟一个效果，不如直接把原生View嵌入到页面中，保留原生性能与交互，同时共享大部分UI结构。实现这一点的关键在于MAUI的Handler机制，它负责把跨平台控件映射到具体的平台视图。

Handler是MAUI从Xamarin.Forms的Renderer演变而来的架构，每一个跨平台控件（如Button、Entry）都会在启动时注册对应的平台Handler。我们可以通过自定义Handler来替换或扩展某个控件的原生实现，也可以直接创建一个全新的跨平台控件，并为它在Android和iOS上分别提供平台视图。后者的自由度更高，适合嵌入任意类型的原生View。

创建可嵌入原生View的跨平台控件

要嵌入一个原生View，第一步是定义一个跨平台控件类。这个类继承自View，它的作用只是作为一个占位符，在共享层表示“这里有一个原生控件”。比如我们要嵌入一个Android上的自定义饼图控件PieChartView，以及iOS上的UICircularProgressView，就可以创建下面的类：

namespace NativeEmbeddingDemo.Controls
{
    public class NativeChartView : View
    {
        // 可以添加可绑定属性，用于向原生控件传递数据
        public static readonly BindableProperty ProgressProperty =
            BindableProperty.Create(nameof(Progress), typeof(double), typeof(NativeChartView), 0.0);
        public double Progress
        {
            get => (double)GetValue(ProgressProperty);
            set => SetValue(ProgressProperty, value);
        }
    }
}

View基类本身没有平台外观，真正负责渲染的是各平台上的Handler。在MAUI中，Handler通过MauiProgram中的ConfigureMauiHandlers方法进行注册。我们需要创建两个平台Handler类，分别处理Android和iOS的视图创建。

Android的Handler需要实现IViewHandler接口，但更简单的方式是继承ViewHandler<TView, TNativeView>。其中TView是跨平台控件类型，TNativeView是Android平台上的原生View类型（例如Android.Views.View的子类）。在CreatePlatformView方法中返回原生View实例，并在ConnectHandler和DisconnectHandler中处理事件或资源。

在Android平台嵌入原生View

假设我们要嵌入一个Android平台的自定义View，它的完整类名是com.example.nativewidgets.PieChartView。由于MAUI项目默认使用.NET for Android，我们可以直接引用Java类或通过绑定库引入。这里为了演示，我们假定已经有一个对应的C#包装类AndroidNativePieChart，它继承自Android.Views.View，并暴露了SetProgress方法。

Android Handler的实现如下：

using Android.Content;
using Microsoft.Maui.Handlers;
using NativeEmbeddingDemo.Controls;
using NativeEmbeddingDemo.Platforms.Android.NativeControls;
namespace NativeEmbeddingDemo.Platforms.Android.Handlers
{
    public class NativeChartViewHandler : ViewHandler<NativeChartView, AndroidNativePieChart>
    {
        public static IPropertyMapper<NativeChartView, NativeChartViewHandler> PropertyMapper =
            new PropertyMapper<NativeChartView, NativeChartViewHandler>(ViewHandler.ViewMapper)
            {
                [nameof(NativeChartView.Progress)] = MapProgress
            };
        public NativeChartViewHandler() : base(PropertyMapper)
        {
        }
        protected override AndroidNativePieChart CreatePlatformView()
        {
            return new AndroidNativePieChart(Context);
        }
        protected override void ConnectHandler(AndroidNativePieChart platformView)
        {
            base.ConnectHandler(platformView);
            // 可以在这里订阅原生控件的事件
        }
        protected override void DisconnectHandler(AndroidNativePieChart platformView)
        {
            // 取消订阅
            base.DisconnectHandler(platformView);
        }
        private static void MapProgress(NativeChartViewHandler handler, NativeChartView view)
        {
            handler.PlatformView?.SetProgress((float)view.Progress);
        }
    }
}

注册Handler是在MauiProgram.cs中完成的。在CreateMauiApp方法里，调用ConfigureMauiHandlers并添加我们的处理器：

using Microsoft.Extensions.Logging;
using NativeEmbeddingDemo.Controls;
using NativeEmbeddingDemo.Platforms.Android.Handlers;
namespace NativeEmbeddingDemo
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                })
                .ConfigureMauiHandlers(handlers =>
                {
#if ANDROID
                    handlers.AddHandler<NativeChartView, NativeChartViewHandler>();
#endif
                });
            return builder.Build();
        }
    }
}

注意上面的条件编译指令#if ANDROID确保了这段注册代码只在Android平台生效。实际上，如果我们在iOS上也有对应的Handler，可以去掉条件编译，让两个平台都在同一个配置块中注册。但通常的做法是把平台Handler放在各自的平台项目或平台文件夹中，通过条件编译引用。

完成注册后，在XAML中就可以直接使用NativeChartView了，它会被渲染成原生的饼图控件。所有Android端的手势、动画和绘制都由原生控件处理，性能与原生应用一致。

在iOS平台嵌入原生View

iOS端的实现思路类似，但要针对UIView的子类。假设我们有一个iOS上的UICircularProgressView（一个自定义的圆形进度条），我们需要创建一个iOS Handler，返回该UIView实例，并处理属性映射。

首先在iOS平台项目中定义或引用UICircularProgressView。然后在Handlers文件夹下创建NativeChartViewHandler.cs：

using Microsoft.Maui.Handlers;
using NativeEmbeddingDemo.Controls;
using NativeEmbeddingDemo.Platforms.iOS.NativeControls;
using UIKit;
namespace NativeEmbeddingDemo.Platforms.iOS.Handlers
{
    public class NativeChartViewHandler : ViewHandler<NativeChartView, UICircularProgressView>
    {
        public static IPropertyMapper<NativeChartView, NativeChartViewHandler> PropertyMapper =
            new PropertyMapper<NativeChartView, NativeChartViewHandler>(ViewHandler.ViewMapper)
            {
                [nameof(NativeChartView.Progress)] = MapProgress
            };
        public NativeChartViewHandler() : base(PropertyMapper)
        {
        }
        protected override UICircularProgressView CreatePlatformView()
        {
            return new UICircularProgressView();
        }
        protected override void ConnectHandler(UICircularProgressView platformView)
        {
            base.ConnectHandler(platformView);
            // 可添加手势或事件
        }
        protected override void DisconnectHandler(UICircularProgressView platformView)
        {
            base.DisconnectHandler(platformView);
        }
        private static void MapProgress(NativeChartViewHandler handler, NativeChartView view)
        {
            handler.PlatformView?.SetProgress((float)view.Progress, animated: true);
        }
    }
}

同样需要在MauiProgram.cs中注册iOS的Handler，可以使用条件编译避免冲突。实际上，如果两个平台的Handler类都放在各自的平台文件夹中，且命名空间相同，那么可以在同一个ConfigureMauiHandlers中同时注册，但要注意类名不能冲突（通常使用条件编译或部分类来区分）。最常见的做法是在共享的MauiProgram.cs中只保留handlers.AddHandler<NativeChartView, NativeChartViewHandler>();，然后通过条件编译确保在每个平台上NativeChartViewHandler指向各自平台实现。例如：

#if ANDROID
using NativeEmbeddingDemo.Platforms.Android.Handlers;
#elif IOS
using NativeEmbeddingDemo.Platforms.iOS.Handlers;
#endif

这样代码更简洁。

注意iOS的UICircularProgressView内部可能使用了Auto Layout，在嵌入MAUI的布局系统时可能需要处理尺寸约束。MAUI的ViewHandler默认会尝试设置Frame，但在某些复杂布局下，你可能需要重写GetDesiredSize方法或者调整Layout相关的映射，以确保原生控件正确填充或适应容器。

跨平台封装与布局注意事项

原生嵌入并非毫无代价。第一个问题是尺寸测量：MAUI的布局系统使用基于约束的测量流程，而Android的View和iOS的UIView有一些默认的测量行为。如果不处理GetDesiredSize，控件可能会显示为0尺寸或异常大小。通常我们可以重写Handler的GetDesiredSize方法，返回一个合理的默认大小，或者根据原生控件的固有尺寸来计算。

第二个问题是属性同步。跨平台控件上定义的BindableProperty需要映射到原生控件的对应方法。上面的示例用了PropertyMapper来映射Progress属性，但真实项目中可能会有更多属性，比如颜色、数据源等。需要确保每一个属性变化都能触发原生控件的更新，避免UI与数据不一致。

第三个问题是平台特定代码的隔离。虽然Handler已经将平台代码分离到各自平台文件夹，但共享层仍然需要知道跨平台控件的存在。这是合理的，因为共享层本来就要描述UI结构。但切忌在共享层直接使用#if ANDROID获取原生控件并操作，那样会破坏可维护性。正确的做法是定义好可绑定属性和事件，通过MAUI的绑定机制与原生控件交互。

还有一个实际场景：当需要嵌入的原生View非常复杂，甚至需要原生生命周期管理时，可以考虑使用ContentView作为容器，在代码后台动态创建原生视图并添加到布局中。这种方式不需要自定义Handler，但失去了XAML的声明式优势。对于简单控件，Handler方案更优雅。

最后要提醒的是，原生嵌入增加了测试复杂度，因为不同平台的表现可能不同。建议在共享层编写单元测试时用模拟的原生视图替换，在真机或模拟器上再做集成测试。掌握这些技巧后，你就可以放心地在MAUI项目中复用已有的原生控件库，显著提升开发效率。