MAUI中创建PageHandler显示iOS原生UITableViewController遇错求助

我已将iOS原生SDK绑定到MAUI中使用，该SDK提供的方法会返回一个UITableViewController。尝试创建PageHandler将此原生iOS UITableViewController转换为MAUI Page以在应用中使用，但遇到了异常问题。

MAUI Page代码 #

public class SignatureSettingsPage : Page
{
    public SignatureSettingsPage()
    {
    }
}

Platforms.iOS中的PageHandler代码 #

public class SignatureSettingsPageHandler : PageHandler
{
    UITableViewController NativeUITableViewController;

    public void SetNativeUITableViewController(UITableViewController controller)
    {
        this.NativeUITableViewController = controller;
    }

    protected override Microsoft.Maui.Platform.ContentView CreatePlatformView()
    {
        _ = VirtualView ?? throw new InvalidOperationException($"{nameof(VirtualView)} must be set to create a LayoutView");
        _ = MauiContext ?? throw new InvalidOperationException($"{nameof(MauiContext)}} cannot be null");

        if (ViewController == null)
            ViewController = this.NativeUITableViewController;

        if (ViewController is PageViewController pc && pc.CurrentPlatformView is Microsoft.Maui.Platform.ContentView pv)
            return pv;

        if (ViewController.View is Microsoft.Maui.Platform.ContentView cv)
            return cv;

        throw new InvalidOperationException($"NativeUITableViewController.View must be a {nameof(Microsoft.Maui.Platform.ContentView)}");
    }
}

Platforms.iOS中获取控制器并创建MAUI Page的代码 #

public SignatureSettingsPage GetSignatureSettingsPage()
{
    UITableViewController nativeController = NativeSDK.GetUITableViewController();

    SignatureSettingsPageHandler mauiHandler = new SignatureSettingsPageHandler();
    mauiHandler.SetNativeUITableViewController(nativeController);

    SignatureSettingsPage mauiPage = new SignatureSettingsPage();
    mauiPage.Handler = mauiHandler;

    return mauiPage;
}

遇到的异常 #

1. 保留VirtualView和MauiContext验证时，抛出InvalidCastException：

System.InvalidCastException: Specified cast is not valid.
at Microsoft.Maui.Handlers.ViewHandler`2[[Microsoft.Maui.IContentView, Microsoft.Maui, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null],[Microsoft.Maui.Platform.ContentView, Microsoft.Maui, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null]].get_VirtualView()

2. 注释掉验证后，抛出InvalidOperationException：

System.InvalidOperationException: NativeUITableViewController.View must be a ContentView

已确认NativeSDK返回的控制器非空且状态正常，但CreatePlatformView中的MauiContext为null，推测PageHandler的实现存在问题，需要修正。

问题根源分析 #

1. VirtualView类型不匹配：PageHandler的泛型基类关联IContentView，但自定义SignatureSettingsPage继承自Page（对应IPage接口），直接继承PageHandler会导致类型转换异常。
2. MauiContext未初始化：手动创建Handler时未传入MauiContext，缺少原生平台上下文信息。
3. 原生View类型不兼容：原生UITableViewController的View是UITableView，无法直接转换为Microsoft.Maui.Platform.ContentView。

修正后的代码实现 #

1. 自定义Page（无需额外修改，确保继承Page即可）

public class SignatureSettingsPage : Page
{
    public SignatureSettingsPage()
    {
    }
}

2. 重写PageHandler实现

将原生控制器的View嵌入到MAUI的ContentView容器中，而非直接替换ViewController：

public class SignatureSettingsPageHandler : PageHandler
{
    private UITableViewController _nativeController;

    public SignatureSettingsPageHandler(IPropertyMapper mapper, CommandMapper commandMapper = null) 
        : base(mapper, commandMapper)
    {
    }

    public void SetNativeController(UITableViewController controller)
    {
        _nativeController = controller;
    }

    protected override void ConnectHandler(Microsoft.Maui.Platform.ContentView platformView)
    {
        base.ConnectHandler(platformView);
        
        if (_nativeController != null && MauiContext != null)
        {
            // 将原生View添加到MAUI容器中
            platformView.AddSubview(_nativeController.View);
            // 设置约束让原生View充满容器
            _nativeController.View.TranslatesAutoresizingMaskIntoConstraints = false;
            NSLayoutConstraint.ActivateConstraints(new[]
            {
                _nativeController.View.TopAnchor.ConstraintEqualTo(platformView.TopAnchor),
                _nativeController.View.BottomAnchor.ConstraintEqualTo(platformView.BottomAnchor),
                _nativeController.View.LeadingAnchor.ConstraintEqualTo(platformView.LeadingAnchor),
                _nativeController.View.TrailingAnchor.ConstraintEqualTo(platformView.TrailingAnchor)
            });
            // 同步控制器生命周期
            _nativeController.WillMoveToParentViewController(MauiContext.ViewController);
        }
    }

    protected override Microsoft.Maui.Platform.ContentView CreatePlatformView()
    {
        // 创建MAUI标准ContentView作为容器
        return base.CreatePlatformView();
    }
}

3. 正确创建Page与Handler关联

必须传入MauiContext初始化Handler：

public SignatureSettingsPage GetSignatureSettingsPage(MauiContext mauiContext)
{
    UITableViewController nativeController = NativeSDK.GetUITableViewController();
    var mauiPage = new SignatureSettingsPage();

    // 用MauiContext初始化Handler并关联VirtualView
    var handler = new SignatureSettingsPageHandler(PageHandler.Mapper)
    {
        MauiContext = mauiContext,
        VirtualView = mauiPage
    };
    handler.SetNativeController(nativeController);

    mauiPage.Handler = handler;
    return mauiPage;
}

4. 注册Handler（关键步骤）

在MauiProgram.cs中注册自定义Page和对应的Handler：

builder.ConfigureMauiHandlers(handlers =>
{
#if IOS
    handlers.AddHandler(typeof(SignatureSettingsPage), typeof(SignatureSettingsPageHandler));
#endif
});

关键说明 #

• 不要直接替换PageHandler的ViewController，通过容器嵌入的方式能保证MAUI生命周期管理正常。
• MauiContext是MAUI与原生控件交互的核心，必须正确传入。
• 手动注册Handler是让MAUI识别自定义Page的原生处理逻辑，不可省略。

内容的提问来源于stack exchange，提问作者Maxime Esprit