Xamarin.Forms カスタムレンダラーを .NET MAUI ハンドラーに移行する

[アーティクル]
10/31/2024

Xamarin.Forms では、カスタムレンダラーを使用してコントロールの外観と動作をカスタマイズし、新しいクロスプラットフォームコントロールを作成できます。各カスタムレンダラーにはクロスプラットフォームコントロールへの参照があり、多くの場合、INotifyPropertyChanged に依存してプロパティ変更通知を送信します。 .NET マルチプラットフォームアプリ UI (.NET MAUI) では、カスタムレンダラーを使用するのではなく、ハンドラーと呼ばれる新しい概念が導入されています。

ハンドラーを使用すると、カスタムレンダラーよりもパフォーマンスがさらに向上します。 Xamarin.Forms では、ViewRenderer クラスが親の要素を作成します。たとえば、Android では、補助的な位置決めタスクに使用される ViewGroup が作成されます。 .NET MAUI では、ViewHandler<TVirtualView,TPlatformView> クラスは親の要素を作成しないため、ビジュアル階層のサイズを小さくし、アプリのパフォーマンスを向上させることができます。また、ハンドラーはプラットフォームコントロールをフレームワークから切り離します。プラットフォームコントロールは、フレームワークのニーズを処理するだけで済みます。これはより効率的であるだけでなく、必要に応じて簡単に拡張またはオーバーライドすることができます。ハンドラーは、Comet や Fabulous などの他のフレームワークによる再利用にも適しています。ハンドラーの詳細については、「ハンドラー」をご覧ください。

Xamarin.Forms では、カスタムレンダラーの OnElementChanged メソッドによってプラットフォームコントロールが作成され、既定値が初期化され、イベントがサブスクライブされ、レンダラーがアタッチされていた Xamarin.Forms 要素 (OldElement) とレンダラーがアタッチされている要素 (NewElement) が処理されます。さらに、単一の OnElementPropertyChanged メソッドは、クロスプラットフォームコントロールでプロパティの変更が発生したときに呼び出す操作を定義します。 .NET MAUI では、このアプローチを簡略化し、すべてのプロパティ変更が個別のメソッドによって処理されるようにし、プラットフォームコントロールを作成し、コントロールのセットアップを実行し、コントロールクリーンアップを実行するコードを個別のメソッドに分離します。

各プラットフォームのカスタムレンダラーによってサポートされる Xamarin.Forms カスタムコントロールを、各プラットフォームのハンドラーによってサポートされる .NET MAUI カスタムコントロールに移行するプロセスは次のとおりです。

コントロールのパブリック API を提供するクロスプラットフォームコントロールのクラスを作成します。詳細については、「クロスプラットフォームのコントロールを作成する」をご覧ください。
partial ハンドラークラスを作成します。詳細については、「ハンドラーを作成する」をご覧ください。
ハンドラークラスで、PropertyMapper ディクショナリを作成します。これは、クロスプラットフォームのプロパティ変更が発生したときに実行するアクションを定義します。詳細については、「プロパティマッパーを作成する」をご覧ください。
クロスプラットフォームコントロールを実装するネイティブビューを作成する各プラットフォームの partial ハンドラークラスを作成します。詳細については、「プラットフォームコントロールを作成する」をご覧ください。
アプリの MauiProgram クラスの ConfigureMauiHandlers メソッドと AddHandler メソッドを使用してハンドラーを登録します。詳細については、「ハンドラーを登録する」をご覧ください。

その後、クロスプラットフォームコントロールを使用できます。詳細については、「クロスプラットフォームコントロールを使用する」をご覧ください。

あるいは、Xamarin.Forms コントロールをカスタマイズするカスタムレンダラーを変換して、.NET MAUI ハンドラーを変更することもできます。詳細については、「ハンドラーを使用してコントロールをカスタマイズする」をご覧ください。

クロスプラットフォームコントロールを作成する

クロスプラットフォームコントロールを作成するには、View から派生するクラスを作成する必要があります。

namespace MyMauiControl.Controls
{
    public class CustomEntry : View
    {
        public static readonly BindableProperty TextProperty =
            BindableProperty.Create(nameof(Text), typeof(string), typeof(CustomEntry), null);

        public static readonly BindableProperty TextColorProperty =
            BindableProperty.Create(nameof(TextColor), typeof(Color), typeof(CustomEntry), null);

        public string Text
        {
            get { return (string)GetValue(TextProperty); }
            set { SetValue(TextProperty, value); }
        }

        public Color TextColor
        {
            get { return (Color)GetValue(TextColorProperty); }
            set { SetValue(TextColorProperty, value); }
        }
    }
}

コントロールは、ハンドラーによってアクセスされ、コンシューマーを制御するパブリック API を提供する必要があります。クロスプラットフォームコントロールは、画面にレイアウトとビューを配置するために使用されるビジュアル要素を表す View から派生する必要があります。

ハンドラーを作成する

クロスプラットフォームコントロールを作成したら、ハンドラーの partial クラスを作成する必要があります。

#if IOS || MACCATALYST
using PlatformView = Microsoft.Maui.Platform.MauiTextField;
#elif ANDROID
using PlatformView = AndroidX.AppCompat.Widget.AppCompatEditText;
#elif WINDOWS
using PlatformView = Microsoft.UI.Xaml.Controls.TextBox;
#elif (NETSTANDARD || !PLATFORM) || (NET6_0_OR_GREATER && !IOS && !ANDROID)
using PlatformView = System.Object;
#endif
using MyMauiControl.Controls;
using Microsoft.Maui.Handlers;

namespace MyMauiControl.Handlers
{
    public partial class CustomEntryHandler
    {
    }
}

ハンドラークラスは部分クラスであり、その実装は追加の部分クラスを使用して各プラットフォームで完了します。

条件付き using ステートメントは、各プラットフォームの PlatformView タイプを定義します。最後の条件付き using ステートメントは、PlatformView が System.Object に等しいと定義します。これは、PlatformView 型をハンドラー内で使用してすべてのプラットフォームで使用できるようにするために必要です。別の方法としては、条件付きコンパイルを使用して、プラットフォームごとに 1 回 PlatformView プロパティを定義する必要があります。

プロパティマッパーを作成する

通常、各ハンドラーはプロパティマッパーを提供します。これは、クロスプラットフォームコントロールでプロパティの変更が発生したときに実行するアクションを定義します。 PropertyMapper 型は、クロスプラットフォームコントロールのプロパティを関連するアクションにマッピングする Dictionary です。

Note

プロパティマッパーは、Xamarin.Forms カスタムレンダラーの OnElementPropertyChanged メソッドに代わるものです。

PropertyMapper は .NET MAUI の ViewHandler<TVirtualView,TPlatformView> クラスで定義されており、2 つのジェネリック引数を指定する必要があります。

View から派生するクロスプラットフォームコントロールのクラス。
ハンドラーのクラス。

次のコード例は、PropertyMapper 定義により拡張された CustomEntryHandler クラスを示しています。

public partial class CustomEntryHandler
{
    public static PropertyMapper<CustomEntry, CustomEntryHandler> PropertyMapper = new PropertyMapper<CustomEntry, CustomEntryHandler>(ViewHandler.ViewMapper)
    {
        [nameof(CustomEntry.Text)] = MapText,
        [nameof(CustomEntry.TextColor)] = MapTextColor
    };

    public CustomEntryHandler() : base(PropertyMapper)
    {
    }
}

PropertyMapper は Dictionary で、そのキーは string で、その値はジェネリック Action です。 string はクロスプラットフォームコントロールのプロパティ名を表し、Action は、引数としてハンドラーとクロスプラットフォームコントロールを必要とする static メソッドを表します。例えば、MapText メソッドのシグネチャは public static void MapText(CustomEntryHandler handler, CustomEntry view) です。

各プラットフォームハンドラーは、ネイティブビュー API を操作するアクションの実装を提供する必要があります。これにより、クロスプラットフォームコントロールでプロパティが設定されると、基になるネイティブビューが必要に応じて更新されます。このアプローチの利点は、クロスプラットフォームコントロールコンシューマーがサブクラス化せずにプロパティマッパーを変更できるため、クロスプラットフォームコントロールのカスタマイズを簡単にできることです。詳細については、「ハンドラーを使用してコントロールをカスタマイズする」をご覧ください。

プラットフォームコントロールの作成

ハンドラーのマッパーを作成した後、すべてのプラットフォームでハンドラーの実装を提供する必要があります。これを実現するには、プラットフォーム フォルダーの子フォルダーに部分クラスハンドラーの実装を追加します。または、ファイル名ベースのマルチターゲット、フォルダーベースのマルチターゲット、またはその両方をサポートするようにプロジェクトを構成することもできます。

ファイル名ベースのマルチターゲットは、次の XML を <Project> ノードの子としてプロジェクトファイルに追加して構成されます。

<!-- Android -->
<ItemGroup Condition="$(TargetFramework.StartsWith('net8.0-android')) != true">
  <Compile Remove="**\*.Android.cs" />
  <None Include="**\*.Android.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<!-- iOS and Mac Catalyst -->
<ItemGroup Condition="$(TargetFramework.StartsWith('net8.0-ios')) != true AND $(TargetFramework.StartsWith('net8.0-maccatalyst')) != true">
  <Compile Remove="**\*.MaciOS.cs" />
  <None Include="**\*.MaciOS.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

<!-- Windows -->
<ItemGroup Condition="$(TargetFramework.Contains('-windows')) != true ">
  <Compile Remove="**\*.Windows.cs" />
  <None Include="**\*.Windows.cs" Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
</ItemGroup>

マルチターゲットの構成の詳細については、「マルチターゲットの構成」をご覧ください。

各プラットフォームハンドラークラスは部分クラスで、 ViewHandler<TVirtualView,TPlatformView> クラスから派生する必要があります。これには 2 つの型引数が必要です。

View から派生するクロスプラットフォームコントロールのクラス。
プラットフォームでクロスプラットフォームコントロールを実装するネイティブビューの型。これは、ハンドラー内の PlatformView プロパティの型と同じである必要があります。

重要

ViewHandler<TVirtualView,TPlatformView> クラスは、VirtualView プロパティと PlatformView プロパティを提供します。 VirtualView プロパティは、ハンドラーからクロスプラットフォームコントロールにアクセスするために使用されます。 PlatformView プロパティは、クロスプラットフォームコントロールを実装する各プラットフォームのネイティブビューにアクセスするために使用されます。

プラットフォームハンドラーの実装はそれぞれ、次のメソッドをオーバーライドする必要があります。

CreatePlatformView は、クロスプラットフォームコントロールを実装するネイティブビューを作成して返す必要があります。
ConnectHandler は、ネイティブビューの初期化やイベントサブスクリプションの実行など、ネイティブビューのセットアップを実行する必要があります。
DisconnectHandler は、イベントからのサブスクライブ解除やオブジェクトの破棄など、ネイティブビューのクリーンアップを実行する必要があります。このメソッドは、.NET MAUI によって意図的に呼び出されません。代わりに、アプリのライフサイクル内の適切な場所から自分で呼び出す必要があります。詳細については、「ネイティブビューのクリーンアップ」をご覧ください。

CreatePlatformView は、クロスプラットフォームコントロールを実装するネイティブビューを作成して返す必要があります。
ConnectHandler は、ネイティブビューの初期化やイベントサブスクリプションの実行など、ネイティブビューのセットアップを実行する必要があります。
DisconnectHandler は、イベントからのサブスクライブ解除やオブジェクトの破棄など、ネイティブビューのクリーンアップを実行する必要があります。このメソッドは既定で .NET MAUI によって自動的に呼び出されますが、この動作は変更できます。詳細については、「 Control ハンドラーの切断」を参照してください。

Note

CreatePlatformView、ConnectHandler、DisconnectHandler オーバーライドは、Xamarin.Forms カスタムレンダラーの OnElementChanged メソッドに代わるものです。

各プラットフォームハンドラーは、マッパーディクショナリで定義されているアクションも実装する必要があります。さらに、各プラットフォームハンドラーは、プラットフォームにクロスプラットフォームコントロールの機能を実装するために、必要に応じてコードを提供する必要もあります。または、より複雑なコントロールの場合は、追加の型で提供できます。

次の例は Android での CustomEntryHandler の実装を示しています。

#nullable enable
using AndroidX.AppCompat.Widget;
using Microsoft.Maui.Handlers;
using Microsoft.Maui.Platform;
using MyMauiControl.Controls;

namespace MyMauiControl.Handlers
{
    public partial class CustomEntryHandler : ViewHandler<CustomEntry, AppCompatEditText>
    {
        protected override AppCompatEditText CreatePlatformView() => new AppCompatEditText(Context);

        protected override void ConnectHandler(AppCompatEditText platformView)
        {
            base.ConnectHandler(platformView);

            // Perform any control setup here
        }

        protected override void DisconnectHandler(AppCompatEditText platformView)
        {
            // Perform any native view cleanup here
            platformView.Dispose();
            base.DisconnectHandler(platformView);
        }

        public static void MapText(CustomEntryHandler handler, CustomEntry view)
        {
            handler.PlatformView.Text = view.Text;
            handler.PlatformView?.SetSelection(handler.PlatformView?.Text?.Length ?? 0);
        }

        public static void MapTextColor(CustomEntryHandler handler, CustomEntry view)
        {
            handler.PlatformView?.SetTextColor(view.TextColor.ToPlatform());
        }
    }
}

CustomEntryHandler は ViewHandler<TVirtualView,TPlatformView> クラスから派生し、ジェネリック CustomEntry 引数はクロスプラットフォームコントロール型を指定し、AppCompatEditText 引数はネイティブコントロールの型を指定します。

CreatePlatformView オーバーライドによって AppCompatEditText オブジェクトが作成され、返されます。 ConnectHandler オーバーライドは、必要なネイティブビューのセットアップを実行する場所です。 DisconnectHandler オーバーライドは、ネイティブビューのクリーンアップを実行する場所であるため、 AppCompatEditText インスタンスで Dispose メソッドを呼び出します。

ハンドラーは、プロパティマッパーディクショナリで定義されているアクションも実装します。各アクションは、クロスプラットフォームコントロールでのプロパティの変更に応答して実行され、引数としてハンドラーとクロスプラットフォームコントロールインスタンスを必要とする static メソッドです。いずれの場合も、アクションはネイティブコントロールで定義されているメソッドを呼び出します。

ハンドラーの登録

カスタムコントロールとそのハンドラーは、アプリを使用する前に登録する必要があります。これは、アプリプロジェクトの MauiProgram クラス内の CreateMauiApp メソッド (アプリのクロスプラットフォームエントリポイント) で発生する必要があります。

using Microsoft.Extensions.Logging;
using MyMauiControl.Controls;
using MyMauiControl.Handlers;

namespace MyMauiControl;

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 =>
      {
        handlers.AddHandler(typeof(CustomEntry), typeof(CustomEntryHandler));
      });

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

    return builder.Build();
  }
}

ハンドラは ConfigureMauiHandlers と AddHandler メソッドで登録されます。 AddHandler メソッドの最初の引数はクロスプラットフォームコントロール型で、2 番目の引数はそのハンドラー型です。

Note

この登録方法により、低速でコストがかかる Xamarin.Forms のアセンブリスキャンを回避できます。

クロスプラットフォームコントロールを使用する

ハンドラーをアプリに登録したら、クロスプラットフォームコントロールを使用できるようになります。

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:controls="clr-namespace:MyMauiControl.Controls"
             x:Class="MyMauiControl.MainPage">
    <Grid>
        <controls:CustomEntry Text="Hello world"
                              TextColor="Blue" />
    </Grid>
</ContentPage>

ネイティブビューのクリーンアップ

各プラットフォームのハンドラー実装は、DisconnectHandler 実装をオーバーライドします。この実装は、イベントのサブスクライブ解除やオブジェクトの破棄など、ネイティブビューのクリーンアップを実行するために使用されます。ただし、このオーバーライドは、.NET MAUI によって意図的に呼び出されません。代わりに、アプリのライフサイクル内の適切な位置から自分で呼び出す必要があります。コントロールを含むページから移動したときなどがこれに該当し、その結果、ページの Unloaded イベントが発生します。

ページの Unloaded イベントのイベントハンドラーを XAML に登録できます。

<ContentPage ...
             xmlns:controls="clr-namespace:MyMauiControl.Controls"
             Unloaded="ContentPage_Unloaded">
    <Grid>
        <controls:CustomEntry x:Name="customEntry"
                              ... />
    </Grid>
</ContentPage>

その結果、Unloaded イベントのイベントハンドラーは、その Handler インスタンスに対して DisconnectHandler メソッドを呼び出すことができます。

void ContentPage_Unloaded(object sender, EventArgs e)
{
    customEntry.Handler?.DisconnectHandler();
}

コントロールハンドラーの切断

各プラットフォームのハンドラー実装は、DisconnectHandler 実装をオーバーライドします。この実装は、イベントのサブスクライブ解除やオブジェクトの破棄など、ネイティブビューのクリーンアップを実行するために使用されます。既定では、ハンドラーは、アプリ内で後方に移動するときなど、可能な場合は自動的にコントロールから切断されます。

一部のシナリオでは、ハンドラーがコントロールから切断されるタイミングを制御する必要があります。これは、 HandlerProperties.DisconnectPolicy 添付プロパティを使用して実現できます。このプロパティには、次の値を定義する列挙体を含む HandlerDisconnectPolicy 引数が必要です。

Automaticは、ハンドラーが自動的に切断されることを示します。これは HandlerProperties.DisconnectPolicy 添付プロパティの既定値です。
Manualは、 DisconnectHandler() 実装を呼び出すことによってハンドラーを手動で切断する必要があることを示します。

次の例では、HandlerProperties.DisconnectPolicy 添付プロパティを設定しています。

<controls:CustomEntry x:Name="customEntry"
                      Text="Hello world"
                      TextColor="Blue"
                      HandlerProperties.DisconnectPolicy="Manual" />

HandlerProperties.DisconnectPolicy添付プロパティをManualに設定するときは、アプリのライフサイクル内の適切な場所からハンドラーのDisconnectHandler実装を自分で呼び出す必要があります。これは、 customEntry.Handler?.DisconnectHandler();を呼び出すことによって実現できます。

さらに、特定の IView からハンドラーを切断する DisconnectHandlers 拡張メソッドがあります。

video.DisconnectHandlers();

切断すると、完了するか、手動ポリシーを設定してあるコントロールに到達するまで、DisconnectHandlers メソッドがコントロールツリー内を伝達されていきます。

次の方法で共有

Xamarin.Forms カスタムレンダラーを .NET MAUI ハンドラーに移行する

クロスプラットフォームコントロールを作成する

ハンドラーを作成する

プロパティマッパーを作成する

プラットフォームコントロールの作成

ハンドラーの登録

クロスプラットフォームコントロールを使用する

ネイティブビューのクリーンアップ

コントロールハンドラーの切断

関連項目

その他のリソース

次の方法で共有

Xamarin.Forms カスタム レンダラーを .NET MAUI ハンドラーに移行する

クロスプラットフォーム コントロールを作成する

ハンドラーを作成する

プロパティ マッパーを作成する

プラットフォーム コントロールの作成

ハンドラーの登録

クロスプラットフォーム コントロールを使用する

ネイティブ ビューのクリーンアップ

コントロール ハンドラーの切断

関連項目

その他のリソース

Xamarin.Forms カスタムレンダラーを .NET MAUI ハンドラーに移行する

クロスプラットフォームコントロールを作成する

プロパティマッパーを作成する

プラットフォームコントロールの作成

クロスプラットフォームコントロールを使用する

ネイティブビューのクリーンアップ

コントロールハンドラーの切断