Xamarin.Forms Imagebutton

Artigo
07/13/2023

O ImageButton exibe uma imagem e responde a um toque ou clique que direciona um aplicativo para executar uma tarefa específica.

O ImageButton modo de exibição combina a exibição Button e Image a exibição para criar um botão cujo conteúdo é uma imagem. O usuário pressiona o ImageButton com um dedo ou clica nele com um mouse para direcionar o aplicativo a realizar uma tarefa específica. No entanto, ao contrário do modo Button de exibição, o modo de exibição ImageButton não tem nenhum conceito de aparência de texto e texto.

Observação

Embora a Button exibição defina uma Image propriedade , que permite exibir uma imagem no Button, essa propriedade deve ser usada ao exibir um pequeno ícone ao lado do Button texto.

Os exemplos de código neste guia são obtidos do exemplo FormsGallery.

Definindo a origem da imagem

ImageButton define uma Source propriedade que deve ser definida como a imagem a ser exibida no botão, com a origem da imagem sendo um arquivo, um URI, um recurso ou um fluxo. Para obter mais informações sobre como carregar imagens de diferentes fontes, consulte Imagens no Xamarin.Forms.

O exemplo a seguir mostra como instanciar um ImageButton em XAML:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="FormsGallery.XamlExamples.ImageButtonDemoPage"
             Title="ImageButton Demo">
    <StackLayout>
        <Label Text="ImageButton"
               FontSize="50"
               FontAttributes="Bold"
               HorizontalOptions="Center" />

       <ImageButton Source="XamarinLogo.png"
                    HorizontalOptions="Center"
                    VerticalOptions="CenterAndExpand" />
    </StackLayout>
</ContentPage>

A Source propriedade especifica a imagem que aparece no ImageButton. Neste exemplo, ele é definido como um arquivo local que será carregado de cada projeto de plataforma, resultando nas seguintes capturas de tela:

Por padrão, o ImageButton é retangular, mas você pode dar a ele cantos arredondados usando a CornerRadius propriedade . Para obter mais informações sobre ImageButton a aparência, consulte Aparência de ImageButton.

Observação

Embora um ImageButton possa carregar um GIF animado, ele exibirá apenas o primeiro quadro do GIF.

O exemplo a seguir mostra como criar uma página funcionalmente equivalente ao exemplo XAML anterior, mas inteiramente em C#:

public class ImageButtonDemoPage : ContentPage
{
    public ImageButtonDemoPage()
    {
        Label header = new Label
        {
            Text = "ImageButton",
            FontSize = 50,
            FontAttributes = FontAttributes.Bold,
            HorizontalOptions = LayoutOptions.Center
        };

        ImageButton imageButton = new ImageButton
        {
            Source = "XamarinLogo.png",
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.CenterAndExpand
        };

        // Build the page.
        Title = "ImageButton Demo";
        Content = new StackLayout
        {
            Children = { header, imageButton }
        };
    }
}

Manipulando cliques de ImageButton

ImageButton define um Clicked evento que é acionado quando o usuário toca no com um dedo ou ponteiro do ImageButton mouse. O evento é acionado quando o botão do dedo ou do mouse é liberado da superfície do ImageButton. O ImageButton deve ter sua IsEnabled propriedade definida como true para responder a toques.

O exemplo a seguir mostra como instanciar um ImageButton em XAML e manipular seu Clicked evento:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="FormsGallery.XamlExamples.ImageButtonDemoPage"
             Title="ImageButton Demo">
    <StackLayout>
        <Label Text="ImageButton"
               FontSize="50"
               FontAttributes="Bold"
               HorizontalOptions="Center" />

       <ImageButton Source="XamarinLogo.png"
                    HorizontalOptions="Center"
                    VerticalOptions="CenterAndExpand"
                    Clicked="OnImageButtonClicked" />

        <Label x:Name="label"
               Text="0 ImageButton clicks"
               FontSize="Large"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand" />
    </StackLayout>
</ContentPage>

O Clicked evento é definido como um manipulador de eventos chamado OnImageButtonClicked 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")}";
    }
}

Quando o ImageButton é tocado, o método OnImageButtonClicked é executado. O sender argumento é o ImageButton responsável por esse evento. Você pode usar isso para acessar o ImageButton objeto ou para distinguir entre vários ImageButton objetos que compartilham o mesmo Clicked evento.

Esse manipulador específico Clicked incrementa um contador e exibe o valor do contador em um Label:

O exemplo a seguir mostra como criar uma página funcionalmente equivalente ao exemplo XAML anterior, mas inteiramente em C#:

public class ImageButtonDemoPage : ContentPage
{
    Label label;
    int clickTotal = 0;

    public ImageButtonDemoPage()
    {
        Label header = new Label
        {
            Text = "ImageButton",
            FontSize = 50,
            FontAttributes = FontAttributes.Bold,
            HorizontalOptions = LayoutOptions.Center
        };

        ImageButton imageButton = new ImageButton
        {
            Source = "XamarinLogo.png",
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.CenterAndExpand
        };
        imageButton.Clicked += OnImageButtonClicked;

        label = new Label
        {
            Text = "0 ImageButton clicks",
            FontSize = Device.GetNamedSize(NamedSize.Large, typeof(Label)),
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.CenterAndExpand
        };

        // Build the page.
        Title = "ImageButton Demo";
        Content = new StackLayout
        {
            Children =
            {
                header,
                imageButton,
                label
            }
        };
    }

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

Desabilitando o ImageButton

Às vezes, um aplicativo está em um estado específico em que um clique específico ImageButton não é uma operação válida. Nesses casos, o ImageButton deve ser desabilitado definindo sua IsEnabled propriedade falsecomo .

Usando a interface de comando

É possível que um aplicativo responda a ImageButton toques sem manipular o Clicked evento. O ImageButton implementa um mecanismo de notificação alternativo chamado comando ou interface de comando . Isso consiste em duas propriedades:

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

Essa abordagem é adequada em conexão com a associação de dados e, especialmente, ao implementar a arquitetura MVVM (Model-View-ViewModel).

Para obter mais informações sobre como usar a interface de comando, consulte Usando a interface de comando no guia Botão .

Pressionando e liberando o ImageButton

Além de evento Clicked, ImageButton também define eventos Pressed e Released. O Pressed evento ocorre quando um dedo pressiona em um ImageButtonou um botão do mouse é pressionado com o ponteiro posicionado sobre o ImageButton. O Released evento ocorre quando o dedo ou botão do mouse é liberado. Em geral, o Clicked evento também é disparado ao mesmo tempo que o Released evento, mas se o dedo ou ponteiro do mouse deslizar para longe da superfície do antes de ImageButton ser liberado, o Clicked evento pode não ocorrer.

Para obter mais informações sobre esses eventos, consulte Pressionando e liberando o botão no guia Botão .

Aparência de ImageButton

Além das propriedades herdadas ImageButton da View classe , ImageButton também define várias propriedades que afetam sua aparência:

Aspect é como a imagem será dimensionada para se ajustar à área de exibição.
BorderColor é a cor de uma área ao redor do ImageButton.
BorderWidth é a largura da borda.
CornerRadius é o raio de canto do ImageButton.

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

Fill – estende a imagem para preencher completamente e exatamente o ImageButton. Isso pode resultar na distorção da imagem.
AspectFill – corta a imagem para que ela preencha o ImageButton enquanto preserva a taxa de proporção.
AspectFit – em caixas de correio a imagem (se necessário) para que toda a imagem se ajuste ao ImageButton, 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 .

Observação

A ImageButton classe também tem Margin propriedades e Padding que controlam o comportamento de layout do ImageButton. Para saber mais, confira Margens e preenchimento.

Estados visuais ImageButton

ImageButton tem um PressedVisualState que pode ser usado para iniciar uma alteração visual no ImageButton quando pressionado pelo usuário, desde que ele esteja habilitado.

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

<ImageButton Source="XamarinLogo.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>

O PressedVisualState especifica que, quando o ImageButton for 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 ImageButton é pressionado, ele é redimensionado para ser um pouco menor e, quando o ImageButton é liberado, ele é redimensionado para seu tamanho padrão.

Para obter mais informações sobre estados visuais, consulte O Xamarin.Forms Gerenciador de Estado Visual.

Exemplo de FormsGallery

Xamarin.Forms Imagebutton

Definindo a origem da imagem

Manipulando cliques de ImageButton

Desabilitando o ImageButton

Usando a interface de comando

Pressionando e liberando o ImageButton

Aparência de ImageButton

Estados visuais ImageButton

Links relacionados

Recursos adicionais