ハンドラーを使用してコントロールをカスタマイズする

[アーティクル]
05/05/2023

ハンドラーをカスタマイズして、コントロールの API を通じて可能なカスタマイズを超えて、クロスプラットフォームコントロールの外観と動作を拡張できます。クロスプラットフォームコントロールのネイティブビューを変更するこのカスタマイズは、次のいずれかのメソッドを使用してハンドラーのマッパーを変更することによって実現されます。

PrependToMappingは、.NET MAUI コントロールマッピングが適用される前にハンドラーのマッパーを変更します。
ModifyMappingは、既存のマッピングを変更します。
AppendToMappingは、.NET MAUI コントロールマッピングが適用された後にハンドラーのマッパーを変更します。

これらの各メソッドには、2 つの引数を必要とする同じシグネチャがあります。

ベースの stringキー。 .NET MAUI によって提供されるマッピングの 1 つを変更する場合は、.NET MAUI で使用されるキーを指定する必要があります。 .NET MAUI コントロールマッピングで使用されるキー値は、インターフェイス名とプロパティ名 (例: nameof(IEntry.IsPassword)) に基づいています。各クロスプラットフォームコントロールを抽象化するインターフェイスとそのプロパティについては、こちらを参照してください。それ以外の場合、このキーは、型によって公開されるプロパティの名前に対応する必要のない任意の値にすることができます。たとえば、 MyCustomization はキーとして指定でき、カスタマイズとしてネイティブビューの変更が実行されます。
Actionハンドラーのカスタマイズを実行するメソッドを表す。では Action 、次の 2 つの引数を指定します。
- handlerカスタマイズするハンドラーのインスタンスを提供する引数。
- viewハンドラーが実装するクロスプラットフォームコントロールのインスタンスを提供する引数。

重要

ハンドラーのカスタマイズはグローバルであり、特定のコントロールインスタンスにスコープは設定されません。ハンドラーのカスタマイズは、アプリ内の任意の場所で行うことができます。ハンドラーがカスタマイズされると、その種類のすべてのコントロール (アプリ内のすべての場所) に影響します。

各ハンドラークラスは、そのプロパティを介してクロスプラットフォームコントロールのネイティブビューを PlatformView 公開します。このプロパティにアクセスして、ネイティブビュープロパティの設定、ネイティブビューメソッドの呼び出し、ネイティブビューイベントのサブスクライブを行うことができます。さらに、ハンドラーによって実装されるクロスプラットフォームコントロールは、その VirtualView プロパティを介して公開されます。

ハンドラーは、条件付きコンパイルを使用してプラットフォームごとにカスタマイズし、プラットフォームに基づいてマルチターゲットコードにカスタマイズできます。または、部分クラスを使用して、コードをプラットフォーム固有のフォルダーとファイルに整理することもできます。条件付きコンパイルの詳細については、「条件付きコンパイル」を参照してください。

コントロールをカスタマイズする

.NET MAUI Entry ビューは、インターフェイスを実装 IEntry する 1 行テキスト入力コントロールです。は EntryHandler 、 Entry プラットフォームごとに次のネイティブビューにビューをマップします。

iOS/Mac Catalyst: UITextField
Android: AppCompatEditText
Windows: TextBox

次の図は、を Entry 使用してビューをネイティブビューにマップする方法を EntryHandler示しています。

エントリハンドラーのアーキテクチャ。

クラスのEntryHandlerプロパティマッパーはEntry、クロスプラットフォームコントロールのプロパティをネイティブビュー API にマップします。これにより、で Entryプロパティが設定されると、基になるネイティブビューが必要に応じて更新されます。

プロパティマッパーは、各プラットフォームでカスタマイズ Entry するように変更できます。

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryPage : ContentPage
{
    public CustomizeEntryPage()
    {
        InitializeComponent();
        ModifyEntry();
    }

    void ModifyEntry()
    {
        Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("MyCustomization", (handler, view) =>
        {
#if ANDROID
            handler.PlatformView.SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
            handler.PlatformView.EditingDidBegin += (s, e) =>
            {
                handler.PlatformView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
            };
#elif WINDOWS
            handler.PlatformView.GotFocus += (s, e) =>
            {
                handler.PlatformView.SelectAll();
            };
#endif
        });
    }
}

この例では、カスタマイズは Entry ページクラスで行われます。したがって、のインスタンスCustomizeEntryPageが作成されると、Android、iOS、および Windows 上のすべてのEntryコントロールがカスタマイズされます。カスタマイズは、各プラットフォームのクロスプラットフォームコントロールにマップされるネイティブビューへのアクセスを提供する handlers PlatformView プロパティにアクセスすることによって実行されます。その後、ネイティブコードは、フォーカスが取得されたときに内のすべてのテキストを選択してハンドラーを Entry カスタマイズします。

マッパーの詳細については、「マッパー」を参照してください。

特定のコントロールインスタンスをカスタマイズする

ハンドラーはグローバルであり、コントロールのハンドラーをカスタマイズすると、同じ種類のすべてのコントロールがアプリでカスタマイズされます。ただし、特定のコントロールインスタンスのハンドラーは、コントロールをサブクラス化してから、コントロールがサブクラス化された型の場合にのみ基本コントロール型のハンドラーを変更することによってカスタマイズできます。たとえば、複数Entryのコントロールを含むページで特定Entryのコントロールをカスタマイズするには、まずコントロールをサブクラス化するEntry必要があります。

namespace CustomizeHandlersDemo.Controls
{
    internal class MyEntry : Entry
    {
    }
}

その後、プロパティマッパーを使用してを EntryHandlerカスタマイズして、インスタンスにのみ必要な変更を MyEntry 実行できます。

Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("MyCustomization", (handler, view) =>
{
    if (view is MyEntry)
    {
#if ANDROID
        handler.PlatformView.SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
        handler.PlatformView.EditingDidBegin += (s, e) =>
        {
            handler.PlatformView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
        };
#elif WINDOWS
        handler.PlatformView.GotFocus += (s, e) =>
        {
            handler.PlatformView.SelectAll();
        };
#endif
    }
});

ハンドラーのカスタマイズがクラスで App 実行される場合、アプリ内のすべての MyEntry インスタンスは、ハンドラーの変更に従ってカスタマイズされます。

ハンドラーのライフサイクルを使用してコントロールをカスタマイズする

すべてのハンドラーベースの .NET MAUI コントロールでは、サポートとHandlerChangedイベントがサポートHandlerChangingされます。クロス HandlerChanged プラットフォームコントロールを実装するネイティブビューが使用可能で初期化されると、イベントが発生します。イベントは HandlerChanging 、コントロールのハンドラーがクロスプラットフォームコントロールから削除されるときに発生します。ハンドラーライフサイクルイベントの詳細については、「ハンドラーのライフサイクル」を参照してください。

ハンドラーのライフサイクルを使用して、ハンドラーのカスタマイズを実行できます。たとえば、ネイティブビューイベントをサブスクライブしてサブスクライブ解除するには、カスタマイズするクロスプラットフォームコントロールのイベントと HandlerChanging イベントのイベントハンドラーHandlerChangedを登録する必要があります。

<Entry HandlerChanged="OnEntryHandlerChanged"
       HandlerChanging="OnEntryHandlerChanging" />

ハンドラーは、条件付きコンパイルを使用するか、部分クラスを使用してプラットフォーム固有のフォルダーとファイルにコードを整理することで、プラットフォームごとにカスタマイズできます。各アプローチについて順番に説明します。次に、を Entry カスタマイズして、フォーカスを取得したときにすべてのテキストが選択されるようにします。

条件付きコンパイル

イベントと HandlerChanging イベントのイベントハンドラーHandlerChangedを含む分離コードファイルを、条件付きコンパイルを使用する次の例に示します。

#if ANDROID
using AndroidX.AppCompat.Widget;
#elif IOS || MACCATALYST
using UIKit;
#elif WINDOWS
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml;
#endif

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryHandlerLifecyclePage : ContentPage
{
    public CustomizeEntryHandlerLifecyclePage()
    {
        InitializeComponent();
    }

    void OnEntryHandlerChanged(object sender, EventArgs e)
    {
        Entry entry = sender as Entry;
#if ANDROID
        (entry.Handler.PlatformView as AppCompatEditText).SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
        (entry.Handler.PlatformView as UITextField).EditingDidBegin += OnEditingDidBegin;
#elif WINDOWS
        (entry.Handler.PlatformView as TextBox).GotFocus += OnGotFocus;
#endif
    }

    void OnEntryHandlerChanging(object sender, HandlerChangingEventArgs e)
    {
        if (e.OldHandler != null)
        {
#if IOS || MACCATALYST
            (e.OldHandler.PlatformView as UITextField).EditingDidBegin -= OnEditingDidBegin;
#elif WINDOWS
            (e.OldHandler.PlatformView as TextBox).GotFocus -= OnGotFocus;
#endif
        }
    }

#if IOS || MACCATALYST                   
    void OnEditingDidBegin(object sender, EventArgs e)
    {
        var nativeView = sender as UITextField;
        nativeView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
    }
#elif WINDOWS
    void OnGotFocus(object sender, RoutedEventArgs e)
    {
        var nativeView = sender as TextBox;
        nativeView.SelectAll();
    }
#endif
}

このイベントは HandlerChanged 、クロスプラットフォームコントロールを実装するネイティブビューが作成および初期化された後に発生します。そのため、そのイベントハンドラーでは、ネイティブイベントサブスクリプションを実行する必要があります。これには、ネイティブイベントに PlatformView アクセスできるように、ハンドラーのプロパティをネイティブビューの型 (基本型) にキャストする必要があります。この例では、iOS、Mac Catalyst、および Windows では、 OnHandlerChanged ゲインフォーカスを実装するネイティブビューで発生するネイティブビューイベントにイベントが Entry サブスクライブされます。

イベントハンドラーと OnGotFocus イベントハンドラーはOnEditingDidBegin、それぞれのプラットフォームののEntryネイティブビューにアクセスし、内のすべてのテキストを選択しますEntry。

イベントは HandlerChanging 、クロスプラットフォームコントロールから既存のハンドラーが削除される前、およびクロスプラットフォームコントロールの新しいハンドラーが作成される前に発生します。そのため、そのイベントハンドラーは、ネイティブイベントサブスクリプションを削除し、他のクリーンアップを実行する必要がある場所です。 HandlerChangingEventArgsこのイベントに付随するオブジェクトにはおよび NewHandler プロパティがありOldHandler、それぞれ古いハンドラーと新しいハンドラーに設定されます。この例では、イベントによって OnHandlerChanging 、iOS、Mac Catalyst、および Windows のネイティブビューイベントへのサブスクリプションが削除されます。

部分クラス

条件付きコンパイルを使用するのではなく、部分クラスを使用して、コントロールのカスタマイズコードをプラットフォーム固有のフォルダーとファイルに整理することもできます。この方法では、カスタマイズコードはクロスプラットフォーム部分クラスとプラットフォーム固有の部分クラスに分離されます。次の例は、クロスプラットフォーム部分クラスを示しています。

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryPartialMethodsPage : ContentPage
{
    public CustomizeEntryPartialMethodsPage()
    {
        InitializeComponent();
    }

    partial void ChangedHandler(object sender, EventArgs e);
    partial void ChangingHandler(object sender, HandlerChangingEventArgs e);

    void OnEntryHandlerChanged(object sender, EventArgs e) => ChangedHandler(sender, e);
    void OnEntryHandlerChanging(object sender, HandlerChangingEventArgs e) => ChangingHandler(sender, e);
}

重要

クロスプラットフォーム部分クラスは、プロジェクトのどの Platforms 子フォルダーにも配置しないでください。

この例では、2 つのイベントハンドラーは、と ChangingHandlerという名前ChangedHandlerの部分メソッドを呼び出します。このメソッドのシグネチャはクロスプラットフォーム部分クラスで定義されています。その後、部分メソッドの実装はプラットフォーム固有の部分クラスで定義されます。これは、ビルドシステムが特定のプラットフォーム用にビルドするときにネイティブコードのビルドのみを試行するように、適切な Platforms 子フォルダーに配置する必要があります。たとえば、次のコードは、プロジェクトの CustomizeEntryPartialMethodsPagePlatforms>Windows フォルダー内のクラスを示しています。

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;

namespace CustomizeHandlersDemo.Views
{
    public partial class CustomizeEntryPartialMethodsPage : ContentPage
    {
        partial void ChangedHandler(object sender, EventArgs e)
        {
            Entry entry = sender as Entry;
            (entry.Handler.PlatformView as TextBox).GotFocus += OnGotFocus;
        }

        partial void ChangingHandler(object sender, HandlerChangingEventArgs e)
        {
            if (e.OldHandler != null)
            {
                (e.OldHandler.PlatformView as TextBox).GotFocus -= OnGotFocus;
            }
        }

        void OnGotFocus(object sender, RoutedEventArgs e)
        {
            var nativeView = sender as TextBox;
            nativeView.SelectAll();
        }
    }
}

この方法の利点は、条件付きコンパイルは必要なく、部分メソッドを各プラットフォームに実装する必要ができないことです。実装がプラットフォームで提供されていない場合、メソッドとメソッドのすべての呼び出しはコンパイル時に削除されます。部分メソッドの詳細については、「 Partial メソッド」を参照してください。

.NET MAUI プロジェクトの Platforms フォルダーの編成については、「部分クラスとメソッド」を参照してください。プラットフォームコードを Platforms フォルダーのサブフォルダーに配置する必要がないようにマルチターゲットを構成する方法については、「マルチターゲットの構成」を参照してください。

ハンドラーを使用してコントロールをカスタマイズする

コントロールをカスタマイズする

特定のコントロールインスタンスをカスタマイズする

ハンドラーのライフサイクルを使用してコントロールをカスタマイズする

条件付きコンパイル

部分クラス

その他のリソース

その他のリソース

ハンドラーを使用してコントロールをカスタマイズする

コントロールをカスタマイズする

特定のコントロール インスタンスをカスタマイズする

ハンドラーのライフサイクルを使用してコントロールをカスタマイズする

条件付きコンパイル

部分クラス

その他のリソース

その他のリソース

特定のコントロールインスタンスをカスタマイズする