ImageButton

La vista ImageButton de .NET Multi-platform App UI (.NET MAUI) combina la vista Button y la vista Image para crear un botón cuyo contenido sea una imagen. Al presionar el ImageButton con un dedo o hacer clic en él con el ratón, dirige la aplicación para llevar a cabo una tarea. Pero, a diferencia de Button, la vista ImageButton no tiene ningún concepto texto ni de apariencia de texto.

ImageButton define las siguientes propiedades:

• Aspect, de tipo Aspect, determina cómo se escala la imagen para ajustarse al área de visualización.
• BorderColor, de tipo Color, describe el color del borde del botón.
• BorderWidth, de tipo double, define el ancho del borde del botón.
• Command, de tipo ICommand, define el comando que se ejecuta cuando se pulsa el botón.
• CommandParameter, de tipo object, que es el parámetro que se pasa a Command.
• CornerRadius, de tipo int, describe el radio de esquina del borde del botón.
• IsLoading, de tipo bool, representa el estado de carga de la imagen. El valor predeterminado de esta propiedad es false.
• IsOpaque, de tipo bool, determina si .NET MAUI debe tratar la imagen como opaca al representarla. El valor predeterminado de esta propiedad es false.
• IsPressed, de tipo bool, representa si se está presionando el botón. El valor predeterminado de esta propiedad es false.
• Padding, de tipo Thickness, determina el relleno del botón.
• Source, de tipo ImageSource, especifica una imagen que se va a mostrar como el contenido del botón.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

La propiedad Aspect se debe establecer en uno de los miembros de la enumeración Aspect.

• Fill: ajusta la imagen para rellenar completa y exactamente el ImageButton. Esto puede hacer que la imagen se distorsione.
• AspectFill: recorta la imagen para que rellene el ImageButton y conserve la relación de aspecto.
• AspectFit: aplica el formato letterbox a la imagen (si es necesario) para que la imagen quepa en el ImageButton, con un espacio en blanco agregado a la parte superior o inferior o a los laterales, en función de si la imagen es ancha o alta. Se trata del valor predeterminado de la enumeración Aspect.
• Center: centra la imagen en el ImageButton mientras conserva la relación de aspecto.

Además, ImageButton define los eventos Clicked, Pressed y Released. El evento Clicked se genera cuando se suelta un toque de ImageButton con un dedo o el puntero del ratón desde la superficie del botón. El evento Pressed se genera cuando se presiona un dedo en ImageButton o se presiona el botón del ratón con el puntero situado sobre ImageButton. El evento Released se produce cuando se sueltan el dedo o el botón del ratón. Por lo general, también se genera un evento Clicked al mismo tiempo que el evento Released, pero si el dedo o el puntero del ratón se aleja de la superficie del ImageButton antes de soltarlo, es posible que el evento Clicked no se produzca.

Importante

ImageButton debe tener su propiedad IsEnabled establecida en true para que responda a los toques.

Crear un ImageButton

Para crear un botón de imagen, crea un objeto ImageButton, establece su propiedad Source y controla su evento Clicked.

En el siguiente ejemplo de XAML se muestra cómo crear un 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>

La propiedad Source especifica la imagen que aparece en el elemento ImageButton. El evento Clicked se establece en un controlador de eventos denominado OnImageButtonClicked. Este controlador se encuentra en el archivo de código subyacente:

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")}";
    }
}

En este ejemplo, cuando se pulsa ImageButton, se ejecuta el método OnImageButtonClicked. El argumento sender es el ImageButton responsable de este evento. Puedes usarlo para tener acceso al objeto ImageButton o para distinguir entre varios objetos ImageButton que comparten el mismo evento Clicked. El controlador Clicked incrementa un contador y muestra el valor del contador en un Label:

El código de C# equivalente que va a crear un ImageButton es:

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 la interfaz de comandos

Una aplicación puede responder a pulsaciones del ImageButton sin controlar el evento Clicked. El ImageButton implementa un mecanismo de notificación alternativo denominado interfaz comando o de comandos. Esta consta de dos propiedades:

• Command de tipo ICommand, una interfaz definida en el espacio de nombres System.Windows.Input.
• Propiedad CommandParameter de tipo Object.

Este enfoque es adecuado en relación con el enlace de datos y, especialmente, al implementar el patrón Model-View-ViewModel (MVVM). Para obtener más información sobre el comando, consulta Uso de la interfaz de comandos en el artículo Botón .

Presiona y suelta un ImageButton

El evento Pressed se genera cuando se presiona un dedo en ImageButton o se presiona un botón del ratón con el puntero situado sobre ImageButton. El evento Released se produce cuando se sueltan el dedo o el botón del ratón. Por lo general, el evento Clicked también se genera al mismo tiempo que el evento Released, pero si el dedo o el puntero del ratón se alejan de la superficie de ImageButton antes de soltarse, es posible que el evento Clicked no se produzca.

Para obtener más información sobre estos eventos, consulta Presionar y soltar el botón en el artículo Botón.

Estados visuales de ImageButton

ImageButton tiene un VisualState Pressed que puede usarse para iniciar un cambio visual del ImageButton cuando se presiona, si está habilitado.

En el ejemplo de XAML siguiente se muestra cómo definir un estado visual para el estado de 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>

En este ejemplo, el VisualState de Pressed especifica que cuando se presiona el ImageButton, su propiedad Scale se cambiará de su valor predeterminado de 1 a 0,8. El VisualState de Normal especifica que cuando el ImageButton está en estado normal, su propiedad Scale se establecerá en 1. Por lo tanto, el efecto general es que, cuando se presiona ImageButton, se vuelve a escalar para que sea ligeramente más pequeño y, cuando se libera ImageButton, se vuelve a escalar a su tamaño predeterminado.

Importante

Para que ImageButton vuelva a su estado Normal, VisualStateGroup también debe definir un estado PointerOver. Si usas los estilos ResourceDictionary creados mediante la plantilla de proyecto de aplicación .NET MAUI, ya tendrás un estilo ImageButton implícito que define el estado PointerOver.

Para obtener más información sobre los estados visuales, consulta Estados visuales.

Deshabilitar un ImageButton

A veces, una aplicación entra en un estado en el que un clic de ImageButton no es una operación válida. En tales casos, se debe deshabilitar el objeto ImageButton estableciendo su propiedad IsEnabled en false.