ハンドラー

.NET Multi-platform App UI (.NET MAUI) には、データの表示、アクションの開始、アクティビティの表示、コレクションの表示、データの選択などを行うために使用できるクロスプラットフォーム コントロールのコレクションが用意されています。 各コントロールには、コントロールを抽象化するインターフェイス表現があります。 これらのインターフェイスを実装するクロスプラットフォーム コントロールは、仮想ビューと呼ばれます。 ハンドラーは、これらの仮想ビューを、ネイティブ ビューと呼ばれる各プラットフォーム上のコントロールにマップします。 ハンドラーは、基になるネイティブ ビューをインスタンス化し、クロスプラットフォーム コントロール API をネイティブ ビュー API にマップする役割も担います。 たとえば、iOS では、ハンドラーを使用して .NET MAUI の Button を iOS の UIButton にマップします。 Android では、Button を AppCompatButton にマップします。

.NET MAUI ハンドラーには、コントロール固有のインターフェイス (Button の IButton など) を通じてアクセスします。 これにより、クロスプラットフォーム コントロールがハンドラーを参照したり、ハンドラーがクロスプラットフォーム コントロールを参照したりする必要がなくなります。

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

ネイティブ ビューから各プラットフォームに実装されるクロスプラットフォーム コントロールを作成する場合は、クロスプラットフォーム コントロール API をネイティブ ビュー API にマップするハンドラーを実装する必要があります。 詳細については、「ハンドラーを使用してカスタム コントロールを作成する」を参照してください。

また、ハンドラーをカスタマイズして、コントロールの API を通じて可能なカスタマイズを超えて、既存のクロスプラットフォーム コントロールの外観と動作を強化することもできます。 このようにハンドラーをカスタマイズすると、クロスプラットフォーム コントロールのネイティブ ビューが変更されます。 ハンドラーはグローバルであり、コントロールのハンドラーをカスタマイズすると、アプリ内の同じタイプのすべてのコントロールがカスタマイズされます。 詳細については、「ハンドラーを使用して .NET MAUI コントロールをカスタマイズする」を参照してください。

マッパー

.NET MAUI ハンドラーの主な概念は、マッパーです。 各ハンドラーは通常、クロスプラットフォーム コントロールの API をネイティブ ビューの API にマップするプロパティ マッパー (場合によってはコマンド マッパー) を提供します。

プロパティ マッパーは、クロスプラットフォーム コントロールでプロパティの変更が発生したときに実行するアクションを定義します。 これは、クロスプラットフォーム コントロールのプロパティを、関連するアクションにマップする Dictionary です。 その後、各プラットフォーム ハンドラーは、ネイティブ ビュー API を操作するアクションの実装を提供します。 これにより、クロスプラットフォーム コントロールでプロパティが設定されると、基になるネイティブ ビューが必要に応じて更新されます。

コマンド マッパーは、クロスプラットフォーム コントロールがネイティブ ビューにコマンドを送信するときに実行するアクションを定義します。 プロパティ マッパーに似ていますが、追加のデータを渡すことができます。 ここでのコマンドは、ICommand 実装のことではありません。 コマンドは単なる命令であり、必要に応じてそのデータをネイティブ ビューに送信できます。 コマンド マッパーは、クロスプラットフォーム コントロールのコマンドを、関連するアクションにマップする Dictionary です。 各ハンドラーを使用して、ネイティブ ビュー API を操作するアクションを実装できます。 これにより、クロスプラットフォーム コントロールがネイティブ ビューにコマンドを送信すると、必要に応じてネイティブ ビューが更新されます。 たとえば、ScrollView がスクロールされると、ScrollViewHandler はコマンド マッパーを使用して、スクロール位置の引数を受け入れるアクションを呼び出します。 次に、アクションは、その位置までスクロールするように、基になるネイティブ ビューに指示します。

マッパーを使用してネイティブ ビューを更新する利点は、ネイティブ ビューをクロスプラットフォーム コントロールから切り離すことができる点です。 これにより、クロスプラットフォーム コントロールのイベントのサブスクライブとサブスクライブ解除を、ネイティブ ビューで行う必要がなくなります。 また、サブクラス化せずにマッパーを変更できるため、カスタマイズが簡単になります。

ハンドラーのライフサイクル

ハンドラー ベースの .NET MAUI コントロールはすべて、次の 2 つのハンドラー ライフサイクル イベントをサポートしています。

• HandlerChanging は、クロスプラットフォーム コントロールに新しいハンドラーが作成されるときや、クロスプラットフォーム コントロールから既存のハンドラーが削除されるときに発生します。 このイベントに付随する HandlerChangingEventArgs オブジェクトには、IElementHandler 型の NewHandler プロパティと OldHandler プロパティがあります。 NewHandler プロパティが null ではない場合、このイベントは、クロスプラットフォーム コントロールに新しいハンドラーが作成されることを示します。 OldHandler プロパティが null ではない場合、このイベントは、既存のネイティブ コントロールがクロスプラットフォーム コントロールから削除されることを示しているため、ネイティブ イベントはすべて未接続で、他のクリーンアップを実行する必要があります。
• HandlerChanged は、クロスプラットフォーム コントロールのハンドラーが作成された後に発生します。 このイベントは、クロスプラットフォーム コントロールを実装するネイティブ コントロールが使用可能であり、クロスプラットフォーム コントロールに設定されているすべてのプロパティ値がネイティブ コントロールに適用されていることを示します。

Note

HandlerChanging イベントは、HandlerChanged イベントの前にクロスプラットフォーム コントロールで発生します。

これらのイベントに加えて、各クロスプラットフォーム コントロールには、HandlerChanging イベントが発生したときに呼び出されるオーバーライド可能な OnHandlerChanging メソッドと、HandlerChanged イベントが発生したときに呼び出される OnHandlerChanged メソッドもあります。

ハンドラーの表示

次の表に、.NET MAUI でビューを実装する型を示します。

表示	インターフェイス	ハンドラー	プロパティ マッパー	コマンド マッパー
ActivityIndicator	IActivityIndicator	ActivityIndicatorHandler	Mapper	CommandMapper
BlazorWebView	IBlazorWebView	BlazorWebViewHandler	BlazorWebViewMapper
Border	IBorderView	BorderHandler	Mapper	CommandMapper
BoxView	IShapeView, IShape	ShapeViewHandler	Mapper	CommandMapper
Button	IButton	ButtonHandler	ImageButtonMapper、 TextButtonMapperMapper	CommandMapper
CarouselView		CarouselViewHandler	Mapper
Cell		CellRenderer	Mapper	CommandMapper
CheckBox	ICheckBox	CheckBoxHandler	Mapper	CommandMapper
CollectionView		CollectionViewHandler	<Mapper
ContentView	IContentView	ContentViewHandler	Mapper	CommandMapper
DatePicker	IDatePicker	DatePickerHandler	Mapper	CommandMapper
Editor	IEditor	EditorHandler	Mapper	CommandMapper
Ellipse	IShape	ShapeViewHandler	Mapper	CommandMapper
Entry	IEntry	EntryHandler	Mapper	CommandMapper
EntryCell		EntryCellRenderer	Mapper	CommandMapper
Frame		FrameRenderer	Mapper	CommandMapper
GraphicsView	IGraphicsView	GraphicsViewHandler	Mapper	CommandMapper
Image	IImage	ImageHandler	Mapper	CommandMapper
ImageButton	IImageButton	ImageButtonHandler	ImageMapper, Mapper
ImageCell		ImageCellRenderer	Mapper	CommandMapper
IndicatorView	IIndicatorView	IndicatorViewHandler	Mapper	CommandMapper
Label	ILabel	LabelHandler	Mapper	CommandMapper
Line	IShape	LineHandler	Mapper	CommandMapper
ListView		ListViewRenderer	Mapper	CommandMapper
Map	IMap	MapHandler	Mapper	CommandMapper
Path	IShape	PathHandler	Mapper	CommandMapper
Picker	IPicker	PickerHandler	Mapper	CommandMapper
Polygon	IShape	PolygonHandler	Mapper	CommandMapper
Polyline	IShape	PolylineHandler	Mapper	CommandMapper
ProgressBar	IProgress	ProgressBarHandler	Mapper	CommandMapper
RadioButton	IRadioButton	RadioButtonHandler	Mapper	CommandMapper
Rectangle	IShape	RectangleHandler	Mapper	CommandMapper
RefreshView	IRefreshView	RefreshViewHandler	Mapper	CommandMapper
RoundRectangle	IShape	RoundRectangleHandler	Mapper	CommandMapper
ScrollView	IScrollView	ScrollViewHandler	Mapper	CommandMapper
SearchBar	ISearchBar	SearchBarHandler	Mapper	CommandMapper
Slider	ISlider	SliderHandler	Mapper	CommandMapper
Stepper	IStepper	StepperHandler	Mapper	CommandMapper
SwipeView	ISwipeView	SwipeViewHandler	Mapper	CommandMapper
Switch	ISwitch	SwitchHandler	Mapper	CommandMapper
SwitchCell		SwitchCellRenderer	Mapper	CommandMapper
TableView		TableViewRenderer	Mapper	CommandMapper
TextCell		TextCellRenderer	Mapper	CommandMapper
TimePicker	ITimePicker	TimePickerHandler	Mapper	CommandMapper
ViewCell		ViewCellRenderer	Mapper	CommandMapper
WebView	IWebView	WebViewHandler	Mapper	CommandMapper

ページ ハンドラー

次の表に、.NET MAUI でページを実装する型を示します。

ページ	Android ハンドラー	iOS/Mac Catalyst ハンドラー	Windows ハンドラー	プロパティ マッパー	コマンド マッパー
ContentPage	PageHandler	PageHandler	PageHandler	Mapper	CommandMapper
FlyoutPage	FlyoutViewHandler	電話FlyoutPageRenderer	FlyoutViewHandler	Mapper	CommandMapper
NavigationPage	NavigationViewHandler	NavigationRenderer	NavigationViewHandler	Mapper	CommandMapper
TabbedPage	TabbedViewHandler	TabbedRenderer	TabbedViewHandler	Mapper	CommandMapper
Shell	ShellHandler	ShellRenderer	ShellRenderer	Mapper	CommandMapper