.NET Multi-platform App UI (.NET MAUI) provides a collection of cross-platform controls that can be used to display data, initiate actions, indicate activity, display collections, pick data, and more. Each control has an interface representation that abstracts the control. Cross-platform controls that implement these interfaces are known as virtual views. Handlers map these virtual views to controls on each platform, which are known as native views. Handlers are also responsible for instantiating the underlying native view, and mapping the cross-platform control API to the native view API. For example, on iOS a handler maps a .NET MAUI Button to an iOS
UIButton. On Android, the Button is mapped to an
.NET MAUI handlers are accessed through their control-specific interface, such as
IButton for a Button. This avoids the cross-platform control having to reference its handler, and the handler having to reference the cross-platform control.
Each handler class exposes the native view for the cross-platform control via its
PlatformView property. This property can be accessed to set native view properties, invoke native view methods, and subscribe to native view events. In addition, the cross-platform control implemented by the handler is exposed via its
When you create a cross-platform control whose implementation is provided on each platform by native views, you should implement a handler that maps the cross-platform control API to the native view APIs. For more information, see Create custom controls with handlers.
You can also customize handlers to augment the appearance and behavior of existing cross-platform controls beyond the customization that's possible through the control's API. This handler customization modifies the native views for the cross-platform control. Handlers are global, and customizing a handler for a control will result in all controls of the same type being customized in your app. For more information, see Customize .NET MAUI controls with handlers.
A key concept of .NET MAUI handlers is mappers. Each handler typically provides a property mapper, and sometimes a command mapper, that maps the cross-platform control's API to the native view's API.
A property mapper defines what Actions to take when a property change occurs in the cross-platform control. It's a
Dictionary that maps the cross-platform control's properties to their associated Actions. Each platform handler then provides implementations of the Actions, which manipulate the native view API. This ensures that when a property is set on a cross-platform control, the underlying native view is updated as required.
A command mapper defines what Actions to take when the cross-platform control sends commands to native views. They're similar to property mappers, but allow for additional data to be passed. A command in this context doesn't mean an
ICommand implementation. Instead, a command is just an instruction, and optionally its data, that's sent to a native view. The command mapper is a
Dictionary that maps the cross-platform control's command to their associated Actions. Each handler then provides implementations of the Actions, which manipulate the native view API. This ensures that when a cross-platform control sends a command to its native view, the native view is updated as required. For example, when a ScrollView is scrolled, the
ScrollViewHandler uses a command mapper to invoke an Action that accepts a scroll position argument. The Action then instructs the underlying native view to scroll to that position.
The advantage of using mappers to update native views is that native views can be decoupled from cross-platform controls. This removes the need for native views to subscribe to and unsubscribe from cross-platform control events. It also allows for easy customization because mappers can be modified without subclassing.
All handler-based .NET MAUI controls support two handler lifecycle events:
HandlerChangingis raised when a new handler is about to be created for a cross-platform control, and when an existing handler is about to be removed from a cross-platform control. The
HandlerChangingEventArgsobject that accompanies this event has
OldHandlerproperties, of type
IElementHandler. When the
null, the event indicates that a new handler is about to be created for a cross-platform control. When the
null, the event indicates that the existing native control is about be removed from the cross-platform control, and therefore any native events should be unwired and other cleanup performed.
HandlerChangedis raised after the handler for a cross-platform control has been created. This event indicates that the native control that implements the cross-platform control is available, and all the property values set on the cross-platform control have been applied to the native control.
HandlerChanging event is raised on a cross-platform control before the
In addition to these events, each cross-platform control also has an overridable
OnHandlerChanging method that's invoked when the
HandlerChanging event is raised, and a
OnHandlerChanged method that's invoked when the
HandlerChanged event is raised.
The following table lists the types that implement handler-based views in .NET MAUI: