ImageButton

  • Artigo

O modo de exibição .NET Multi-platform App UI (.NET MAUI) ImageButton combina o modo de exibição e Image o Button modo de exibição para criar um botão cujo conteúdo é uma imagem. Quando você pressiona o com um dedo ou clica nele com um mouse, ele direciona o ImageButton aplicativo para executar uma tarefa. No entanto, ao contrário do ButtonImageButton modo de exibição não tem nenhum conceito de texto e 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 de 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 o conteúdo do botão.

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

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

  • Fill - estica a imagem para preencher completamente e exatamente o ImageButton. Isso pode resultar na distorção da imagem.
  • AspectFill - recorta a imagem para que ela preencha a ImageButton proporção.
  • AspectFit - letterboxes a imagem (se necessário) para que a imagem inteira caiba ImageButtonno , com espaço em branco adicionado à parte superior/inferior ou laterais, dependendo se a imagem é larga ou alta. Esse é o valor padrão da Aspect enumeração.
  • Center - centraliza ImageButton a imagem no enquanto preserva a proporção.

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

Importante

Um ImageButton deve ter sua IsEnabled propriedade definida como true para que ele responda a toques.

Criar um ImageButton

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

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 Source propriedade especifica a imagem que aparece no ImageButton. O Clicked evento é definido como 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 é tocado, o ImageButtonOnImageButtonClicked método é executado. O sender argumento é o ImageButton responsável por esse evento. Você pode usar isso para acessar o objeto ou para distinguir entre vários ImageButton objetos que compartilham o ImageButton mesmo Clicked evento. O Clicked manipulador incrementa um contador e exibe o valor do contador em um Label:

Screenshot of an ImageButton.

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 ImageButton toques sem manipular o Clicked evento. O ImageButton implementa um mecanismo de notificação alternativo chamado de comando ou interface de comando. Isso consiste em duas propriedades:

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

Pressione e solte um ImageButton

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

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

Estados visuais de ImageButton

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

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

<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>
        </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
</ImageButton>

Neste exemplo, o especifica que, quando o PressedVisualStateImageButton é pressionado, sua Scale propriedade será alterada de seu valor padrão de 1 para 0,8. O NormalVisualState especifica que, quando o ImageButton estiver em um estado normal, sua Scale propriedade será definida como 1. Portanto, o efeito geral é que, quando o é pressionado, ele é redimensionado para ser um pouco menor e, quando o ImageButtonImageButton é lançado, ele é redimensionado para seu tamanho padrão.

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

Desativar um ImageButton

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