ImageButton

A visualização ImageButton do .NET Multi-platform App UI (.NET MAUI) combina a visualização Button e a visualização Image para criar um botão cujo conteúdo é uma imagem. Quando você pressiona o ImageButton com um dedo ou clica nele com um mouse, ele direciona o aplicativo para executar uma tarefa. Entretanto, ao contrário do Button, a visualização ImageButton não tem o conceito e a aparência de texto.

ImageButton define as propriedades a seguir:

• Aspect, do tipo Aspect, determina como a imagem é dimensionada para se ajustar à área de exibição.
• BorderColor, do tipo Color, descreve a cor da borda do botão.
• BorderWidth, do tipo double, define a largura da borda do botão.
• Command, do tipo ICommand, define o comando que é executado quando o botão é tocado.
• CommandParameter, do tipo object, é o parâmetro que é passado para Command.
• CornerRadius, do tipo int, descreve o raio do canto da borda do botão.
• IsLoading, do tipo bool, representa o status de carregamento da imagem. O valor padrão dessa propriedade é false.
• IsOpaque, do tipo bool, determina se o .NET MAUI deve tratar a imagem como opaca ao renderizá-la. O valor padrão dessa propriedade é false.
• IsPressed, do tipo bool, representa se o botão está sendo pressionado. O valor padrão dessa propriedade é false.
• Padding, do tipo Thickness, determina o preenchimento do botão.
• Source, do tipo ImageSource, especifica uma imagem a ser exibida como conteúdo do botão.

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que podem ser alvos de associações de dados e ser estilizada.

A propriedade Aspect pode ser definida como um dos membros da enumeração Aspect:

• Fill - estica a imagem para preencher completa e exatamente o ImageButton. Isso pode fazer com que a imagem fique distorcida.
• AspectFill - recorta a imagem de modo que ela preencha o ImageButton, preservando a taxa de proporção.
• AspectFit - adiciona faixas horizontais ou verticais à imagem (se necessário) para que a imagem inteira se ajuste no ImageButton, com espaço em branco adicionado na parte superior/inferior ou nas laterais, dependendo se a imagem é larga ou alta. Esse é o valor padrão da enumeração Aspect.
• Center - centraliza a imagem em ImageButton, preservando a taxa de proporção.

Além disso, ImageButton define os eventos Clicked, Pressed e Released. O evento Clicked é acionado quando um toque ImageButton com o dedo ou o ponteiro do mouse é liberado da superfície do botão. O evento Pressed é acionado quando um dedo pressiona um ImageButton ou um botão do mouse é pressionado com o ponteiro posicionado sobre o ImageButton. O evento Released é acionado quando o dedo ou o botão do mouse é liberado. Geralmente, um evento Clicked também é acionado ao mesmo tempo que o evento Released, mas se o dedo ou o ponteiro do mouse deslizar para fora da superfície do ImageButton antes de ser liberado, o evento Clicked poderá não ocorrer.

Importante

Um ImageButton deve ter sua propriedade IsEnabled definida como true para responder a toques.

Criar um ImageButton

Para criar um botão de imagem, crie um objeto ImageButton, defina sua propriedade Source e manipule seu evento Clicked.

O exemplo XAML a seguir mostra como criar um ImageButton:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ControlGallery.Views.XAML.ImageButtonDemoPage"
             Title="ImageButton Demo">
    <StackLayout>
       <ImageButton Source="image.png"
                    Clicked="OnImageButtonClicked"
                    HorizontalOptions="Center"
                    VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

A propriedade Source especifica a imagem que aparece no ImageButton. O evento Clicked é definido para um manipulador de eventos chamado OnImageButtonClicked. Esse manipulador está localizado no arquivo code-behind:

public partial class ImageButtonDemoPage : ContentPage
{
    int clickTotal;

    public ImageButtonDemoPage()
    {
        InitializeComponent();
    }

    void OnImageButtonClicked(object sender, EventArgs e)
    {
        clickTotal += 1;
        label.Text = $"{clickTotal} ImageButton click{(clickTotal == 1 ? "" : "s")}";
    }
}

Neste exemplo, quando o ImageButton é tocado, o método OnImageButtonClicked é executado. O argumento sender é o ImageButton responsável por esse evento. Você pode usar isso para acessar o objeto ImageButton ou para distinguir entre vários objetos ImageButton que compartilham o mesmo evento Clicked. O manipulador Clicked incrementa um contador e exibe o valor do contador em um Label:

O código C# equivalente para criar um ImageButton é:

Label label;
int clickTotal = 0;
...

ImageButton imageButton = new ImageButton
{
    Source = "XamarinLogo.png",
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.CenterAndExpand
};
imageButton.Clicked += (s, e) =>
{
  clickTotal += 1;
  label.Text = $"{clickTotal} ImageButton click{(clickTotal == 1 ? "" : "s")}";
};

Usar a interface de comando

Um aplicativo pode responder a toques ImageButton sem manipular o evento Clicked. O ImageButton implementa um mecanismo de notificação alternativo chamado interface de comando ou comandos. Isso consiste em duas propriedades:

• Command do tipo ICommand, uma interface definida no namespace System.Windows.Input.
• CommandParameter propriedade do tipo Object.

Essa abordagem é adequada em conexão com a associação de dados e, particularmente, ao implementar o padrão Model-View-ViewModel (MVVM). Para obter mais informações sobre comandos, consulte Usar a interface de comando no artigo Botão.

Pressionar e liberar um ImageButton

O evento Pressed é acionado quando um dedo pressiona um ImageButton ou um botão do mouse é pressionado com o ponteiro posicionado sobre o ImageButton. O evento Released é acionado quando o dedo ou o botão do mouse é liberado. Geralmente, o evento Clicked também é acionado ao mesmo tempo que o evento Released, mas se o dedo ou o ponteiro do mouse deslizar para longe da superfície do ImageButton antes de ser liberado, o evento Clicked poderá não ocorrer.

Para obter mais informações sobre esses eventos, consulte Pressionar e soltar o botão no artigo Botão.

Estados visuais ImageButton

ImageButton tem um Pressed VisualState que pode ser usado para iniciar uma alteração visual no ImageButton quando pressionado, se estiver habilitado.

O exemplo XAML a seguir mostra como definir um estado visual para o estado Pressed:

<ImageButton Source="image.png"
             ...>
    <VisualStateManager.VisualStateGroups>
        <VisualStateGroup x:Name="CommonStates">
            <VisualState x:Name="Normal">
                <VisualState.Setters>
                    <Setter Property="Scale"
                            Value="1" />
                </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="Pressed">
                <VisualState.Setters>
                    <Setter Property="Scale"
                            Value="0.8" />
                </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="PointerOver" />            
        </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
</ImageButton>

Nesse exemplo, Pressed VisualState especifica que quando ImageButton for pressionado, sua propriedade Scale será alterada de seu valor padrão de 1 para 0,8. O Normal VisualState especifica que quando o ImageButton estiver em estado normal, sua propriedade Scale será definida como 1. Portanto, o efeito geral é que quando o ImageButton é pressionado, ele é redimensionado para ser um pouco menor, e quando o ImageButton é liberado, ele é redimensionado para seu tamanho padrão.

Importante

Para que um ImageButton retorne ao seu estado Normal, o VisualStateGroup também deve definir um estado PointerOver. Se usar os estilos ResourceDictionary criados pelo modelo de projeto de aplicativo .NET MAUI, você já terá um estilo ImageButton implícito que define o estado PointerOver.

Para obter mais informações sobre estados visuais, consulte Estados visuais.

Desabilitar um ImageButton

Às vezes, um aplicativo entra em um estado em que um clique ImageButton não é uma operação válida. Nesses casos, o ImageButton deve ser desabilitado, definindo sua propriedade IsEnabled como false.