ImageButton

La visualizzazione .NET Multi-platform App UI (.NET MAUI) ImageButton combina la visualizzazione e Image la Button visualizzazione per creare un pulsante il cui contenuto è un'immagine. Quando si preme ImageButton con un dito o si fa clic con un mouse, l'app viene indirizzata a eseguire un'attività. Tuttavia, a differenza della Button ImageButton visualizzazione non ha alcun concetto di testo e aspetto del testo.

ImageButton definisce le proprietà seguenti:

• Aspect, di tipo Aspect, determina il modo in cui l'immagine viene ridimensionata per adattarsi all'area di visualizzazione.
• BorderColor, di tipo Color, descrive il colore del bordo del pulsante.
• BorderWidth, di tipo double, definisce la larghezza del bordo del pulsante.
• Command, di tipo ICommand, definisce il comando eseguito quando viene toccato il pulsante.
• CommandParameter, di tipo object, è il parametro passato a Command.
• CornerRadius, di tipo int, descrive il raggio dell'angolo del bordo del pulsante.
• IsLoading, di tipo bool, rappresenta lo stato di caricamento dell'immagine. Il valore predefinito di questa proprietà è false.
• IsOpaque, di tipo bool, determina se .NET MAUI deve considerare l'immagine come opaca durante il rendering. Il valore predefinito di questa proprietà è false.
• IsPressed, di tipo bool, indica se il pulsante viene premuto. Il valore predefinito di questa proprietà è false.
• Padding, di tipo Thickness, determina la spaziatura interna del pulsante.
• Source, di tipo ImageSource, specifica un'immagine da visualizzare come contenuto del pulsante.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding e stili.

La Aspect proprietà può essere impostata su uno dei membri dell'enumerazione Aspect :

• Fill - estende completamente l'immagine e riempie esattamente l'oggetto ImageButton. Ciò può comportare la distorsione dell'immagine.
• AspectFill - ritaglia l'immagine in modo che riempia l'oggetto ImageButton mantenendo le proporzioni.
• AspectFit - la casella di lettere inserisce l'immagine (se necessario) in modo che l'intera immagine si adatti ImageButtona , con spazio vuoto aggiunto all'angolo superiore/inferiore o ai lati a seconda che l'immagine sia larga o alta. Questo è il valore predefinito dell'enumerazione Aspect .
• Center - centra l'immagine in ImageButton mantenendo al tempo stesso le proporzioni.

Definisce inoltre ImageButton Clickedgli eventi , Pressede Released . L'evento Clicked viene generato quando un ImageButton tocco con un dito o un puntatore del mouse viene rilasciato dalla superficie del pulsante. L'evento Pressed viene generato quando un dito preme un dito su un ImageButtonoggetto o un pulsante del mouse viene premuto con il puntatore posizionato su ImageButton. L'evento Released viene generato quando viene rilasciato il dito o il pulsante del mouse. In genere, viene generato anche un Clicked evento contemporaneamente all'evento Released , ma se il puntatore del mouse o il dito si allontana dalla superficie di prima del ImageButton rilascio, l'evento Clicked potrebbe non verificarsi.

Importante

Per rispondere ai tap, un ImageButton oggetto deve avere la relativa IsEnabled proprietà impostata su true .

Creare un controllo ImageButton

Per creare un pulsante di immagine, creare un ImageButton oggetto, impostarne la Source proprietà e gestire l'evento Clicked .

L'esempio XAML seguente illustra come creare un oggetto 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 Source proprietà specifica l'immagine visualizzata in ImageButton. L'evento Clicked è impostato su un gestore eventi denominato OnImageButtonClicked. Questo gestore si trova nel file 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")}";
    }
}

In questo esempio, quando viene toccato , ImageButton il OnImageButtonClicked metodo viene eseguito. L'argomento sender è il responsabile di ImageButton questo evento. È possibile usarlo per accedere all'oggetto ImageButton o per distinguere tra più ImageButton oggetti che condividono lo stesso Clicked evento. Il Clicked gestore incrementa un contatore e visualizza il valore del contatore in un Labeloggetto :

Il codice C# equivalente per creare un ImageButton oggetto è:

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

Usare l'interfaccia del comando

Un'app può rispondere ai ImageButton tap senza gestire l'evento Clicked . ImageButton implementa un meccanismo di notifica alternativo denominato comando o interfaccia di comando. Questo è costituito da due proprietà:

• Command di tipo ICommand, un'interfaccia definita nello spazio dei System.Windows.Input nomi .
• CommandParameter proprietà di tipo Object.

Questo approccio è adatto in relazione al data binding e in particolare quando si implementa il modello Model-View-ViewModel (MVVM). Per altre informazioni sui comandi, vedere Usare l'interfaccia dei comandi nell'articolo Pulsante .

Premere e rilasciare un controllo ImageButton

L'evento Pressed viene generato quando un dito preme un dito su un ImageButtonoggetto oppure viene premuto un pulsante del mouse con il puntatore posizionato su ImageButton. L'evento Released viene generato quando viene rilasciato il dito o il pulsante del mouse. In genere, l'evento Clicked viene generato contemporaneamente all'evento Released , ma se il puntatore del mouse o il dito si allontana dalla superficie di prima del ImageButton rilascio, l'evento Clicked potrebbe non verificarsi.

Per altre informazioni su questi eventi, vedere Premere e rilasciare il pulsante nell'articolo Pulsante .

Stati di visualizzazione ImageButton

ImageButton ha un oggetto Pressed VisualState che può essere usato per avviare una modifica visiva a ImageButton quando viene premuto, se è abilitato.

L'esempio XAML seguente illustra come definire uno stato di visualizzazione per lo Pressed stato:

<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>

In questo esempio, l'oggetto Pressed VisualState specifica che, quando ImageButton viene premuto, la relativa Scale proprietà verrà modificata dal valore predefinito da 1 a 0,8. Normal VisualState Specifica che quando l'oggetto ImageButton è in uno stato normale, la relativa Scale proprietà verrà impostata su 1. Di conseguenza, l'effetto complessivo è che, quando ImageButton viene premuto, viene ridimensionato leggermente più piccolo e, quando ImageButton viene rilasciato, viene ridimensionato in base alle dimensioni predefinite.

Importante

Affinché un oggetto ImageButton restituisca il relativo Normal stato, VisualStateGroup deve anche definire uno PointerOver stato. Se si usano gli stili ResourceDictionary creati dal modello di progetto dell'app MAUI .NET, si avrà già uno stile implicito ImageButton che definisce lo PointerOver stato.

Per altre informazioni sugli stati di visualizzazione, vedere Stati di visualizzazione.

Disabilitare un controllo ImageButton

In alcuni casi un'app entra in uno stato in cui un ImageButton clic non è un'operazione valida. In questi casi, l'oggetto ImageButton deve essere disabilitato impostando la relativa IsEnabled proprietà su false.