Manipuladores

A interface do usuário do aplicativo multiplataforma .NET (.NET MAUI) fornece uma coleção de controles de plataforma cruzada que podem ser usados para exibir dados, iniciar ações, indicar atividades, exibir coleções, selecionar dados e muito mais. Cada controle tem uma representação de interface que abstrai o controle. Os controles de plataforma cruzada que implementam essas interfaces são conhecidos como exibições virtuais. Os manipuladores mapeiam essas exibições virtuais para controles em cada plataforma, que são conhecidos como modos de exibição nativos. Os manipuladores também são responsáveis por instanciar a exibição nativa subjacente e mapear a API de controle entre plataformas para a API de exibição nativa. Por exemplo, no iOS, um manipulador mapeia um .NET MAUI Button para um iOS UIButton. No Android, o Button é mapeado para um AppCompatButton:

Os manipuladores MAUI do .NET são acessados por meio de sua interface específica de controle, como IButton para um Buttonarquivo . Isso evita que o controle de plataforma cruzada tenha que fazer referência ao seu manipulador e o manipulador tenha que fazer referência ao controle de plataforma cruzada.

Cada classe de manipulador expõe a exibição nativa para o controle entre plataformas por meio de sua PlatformView propriedade. Essa propriedade pode ser acessada para definir propriedades de exibição nativa, invocar métodos de exibição nativos e assinar eventos de exibição nativa. Além disso, o controle de plataforma cruzada implementado pelo manipulador é exposto por meio de sua VirtualView propriedade.

Ao criar um controle entre plataformas cuja implementação é fornecida em cada plataforma por exibições nativas, você deve implementar um manipulador que mapeie a API de controle entre plataformas para as APIs de exibição nativa. Para obter mais informações, consulte Criar controles personalizados com manipuladores.

Você também pode personalizar manipuladores para aumentar a aparência e o comportamento dos controles de plataforma cruzada existentes além da personalização possível por meio da API do controle. Essa personalização do manipulador modifica as exibições nativas para o controle entre plataformas. Os manipuladores são globais, e a personalização de um manipulador para um controle resultará em todos os controles do mesmo tipo sendo personalizados em seu aplicativo. Para obter mais informações, consulte Personalizar controles MAUI do .NET com manipuladores.

Mappers

Um conceito-chave dos manipuladores MAUI do .NET são mapeadores. Cada manipulador normalmente fornece um mapeador de propriedades e, às vezes, um mapeador de comandos, que mapeia a API do controle de plataforma cruzada para a API da exibição nativa.

Um mapeador de propriedades define quais Ações devem ser executadas quando ocorre uma alteração de propriedade no controle entre plataformas. É um Dictionary que mapeia as propriedades do controle de plataforma cruzada para suas Ações associadas. Em seguida, cada manipulador de plataforma fornece implementações das Ações, que manipulam a API de exibição nativa. Isso garante que, quando uma propriedade é definida em um controle entre plataformas, a exibição nativa subjacente é atualizada conforme necessário.

Um mapeador de comandos define quais Ações devem ser executadas quando o controle entre plataformas envia comandos para exibições nativas. Eles são semelhantes aos mapeadores de propriedades, mas permitem que dados adicionais sejam passados. Um comando nesse contexto não significa uma ICommand implementação. Em vez disso, um comando é apenas uma instrução e, opcionalmente, seus dados, que são enviados para uma exibição nativa. O mapeador de comandos é um Dictionary que mapeia o comando do controle de plataforma cruzada para suas Ações associadas. Em seguida, cada manipulador fornece implementações das Ações, que manipulam a API de exibição nativa. Isso garante que, quando um controle entre plataformas envia um comando para sua exibição nativa, a exibição nativa é atualizada conforme necessário. Por exemplo, quando um é rolado, o ScrollViewHandler usa um mapeador de comandos para invocar uma Ação que aceita um ScrollView argumento de posição de rolagem. Em seguida, a Ação instrui o modo de exibição nativo subjacente a rolar até essa posição.

A vantagem de usar mapeadores para atualizar exibições nativas é que as exibições nativas podem ser dissociadas de controles entre plataformas. Isso elimina a necessidade de exibições nativas para se inscrever e cancelar a assinatura de eventos de controle entre plataformas. Ele também permite fácil personalização, pois os mapeadores podem ser modificados sem subclassificação.

Ciclo de vida do manipulador

Todos os controles .NET MAUI baseados em manipulador oferecem suporte a dois eventos de ciclo de vida do manipulador:

• HandlerChanging é gerado quando um novo manipulador está prestes a ser criado para um controle de plataforma cruzada e quando um manipulador existente está prestes a ser removido de um controle de plataforma cruzada. O HandlerChangingEventArgs objeto que acompanha esse evento tem NewHandler e OldHandler propriedades, do tipo IElementHandler. Quando a propriedade não nullé , o evento indica que um novo manipulador está prestes a NewHandler ser criado para um controle entre plataformas. Quando a OldHandler propriedade não nullé , o evento indica que o controle nativo existente está prestes a ser removido do controle entre plataformas e, portanto, quaisquer eventos nativos devem ser desconectados e outras limpezas executadas.
• HandlerChanged é gerado após a criação do manipulador para um controle entre plataformas. Esse evento indica que o controle nativo que implementa o controle entre plataformas está disponível e todos os valores de propriedade definidos no controle entre plataformas foram aplicados ao controle nativo.

Observação

O HandlerChanging evento é gerado em um controle multiplataforma antes do HandlerChanged evento.

Além desses eventos, cada controle de plataforma cruzada também tem um método substituível OnHandlerChanging que é invocado quando o evento é gerado e um OnHandlerChanged método que é invocado quando o HandlerChangingHandlerChanged evento é gerado.

Exibir manipuladores

A tabela a seguir lista os tipos que implementam modos de exibição no .NET MAUI:

Exibir	Interface	Manipulador	Mapeador de Propriedades	Mapeador de Comandos
ActivityIndicator	IActivityIndicator	ActivityIndicatorHandler	Mapper	CommandMapper
BlazorWebView	IBlazorWebView	BlazorWebViewHandler	BlazorWebViewMapper
Border	IBorderView	BorderHandler	Mapper	CommandMapper
BoxView	IShapeView, IShape	ShapeViewHandler	Mapper	CommandMapper
Button	IButton	ButtonHandler	ImageButtonMapper, TextButtonMapper, Mapper	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

Manipuladores de página

A tabela a seguir lista os tipos que implementam páginas no .NET MAUI:

Página	Manipulador Android	Manipulador de catalisador iOS/Mac	Manipulador do Windows	Mapeador de Propriedades	Mapeador de Comandos
ContentPage	PageHandler	PageHandler	PageHandler	Mapper	CommandMapper
FlyoutPage	FlyoutViewHandler	PhoneFlyoutPageRenderer	FlyoutViewHandler	Mapper	CommandMapper
NavigationPage	NavigationViewHandler	NavigationRenderer	NavigationViewHandler	Mapper	CommandMapper
TabbedPage	TabbedViewHandler	TabbedRenderer	TabbedViewHandler	Mapper	CommandMapper
Shell	ShellHandler	ShellRenderer	ShellRenderer	Mapper	CommandMapper