Trigger

Esplorare l'esempio

I trigger dell'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) consentono di esprimere azioni in modo dichiarativo in XAML che modificano l'aspetto dei controlli in base a eventi o modifiche ai dati. Inoltre, i trigger di stato, un gruppo specializzato di trigger, definiscono quando è necessario applicare VisualState.

È possibile assegnare un trigger direttamente alla raccolta di Triggers un controllo o aggiungerlo a un dizionario risorse a livello di pagina o a livello di app da applicare a più controlli.

Trigger di proprietà

Un Trigger oggetto rappresenta un trigger che applica i valori delle proprietà o esegue azioni quando la proprietà specificata soddisfa una condizione specificata.

L'esempio seguente mostra un Trigger oggetto che modifica un Entry colore di sfondo quando riceve lo stato attivo:

<Entry Placeholder="Enter name">
    <Entry.Triggers>
        <Trigger TargetType="Entry"
                 Property="IsFocused"
                 Value="True">
            <Setter Property="BackgroundColor"
                    Value="Yellow" />
            <!-- Multiple Setter elements are allowed -->
        </Trigger>
    </Entry.Triggers>
</Entry>

La dichiarazione del trigger specifica quanto segue:

• TargetType : tipo di controllo a cui si applica il trigger.
• Property : proprietà nel controllo monitorato.
• Value : valore, quando si verifica per la proprietà monitorata, che determina l'attivazione del trigger.
• Setter : raccolta di Setter elementi applicati quando viene soddisfatta la condizione del trigger.

È inoltre possibile specificare raccolte e ExitActions facoltativeEnterActions. Per altre informazioni, vedere EnterActions e ExitActions.

Applicare un trigger usando uno stile

È anche possibile aggiungere trigger a una dichiarazione Style in un controllo, in una pagina o in un oggetto ResourceDictionary dell'applicazione. Nell'esempio seguente viene dichiarato uno stile implicito per tutti i Entry controlli nella pagina:

<ContentPage.Resources>
    <Style TargetType="Entry">
        <Style.Triggers>
            <Trigger TargetType="Entry"
                     Property="IsFocused"
                     Value="True">
                <Setter Property="BackgroundColor"
                        Value="Yellow" />
                <!-- Multiple Setter elements are allowed -->
            </Trigger>
        </Style.Triggers>
    </Style>
</ContentPage.Resources>

Trigger di dati

Un DataTrigger oggetto rappresenta un trigger che applica i valori delle proprietà o esegue azioni quando i dati associati soddisfano una condizione specificata. L'estensione Binding di markup viene usata per monitorare la condizione specificata.

Nell'esempio seguente viene illustrato un oggetto che disabilita un DataTriggerButton oggetto quando è Entry vuoto:

<Entry x:Name="entry"
       Text=""
       Placeholder="Enter text" />
<Button Text="Save">
    <Button.Triggers>
        <DataTrigger TargetType="Button"
                     Binding="{Binding Source={x:Reference entry},
                                       Path=Text.Length}"
                     Value="0">
            <Setter Property="IsEnabled"
                    Value="False" />
            <!-- Multiple Setter elements are allowed -->
        </DataTrigger>
    </Button.Triggers>
</Button>

In questo esempio, quando la lunghezza di Entry è zero, il trigger viene attivato.

Suggerimento

Quando si Path=Text.Length valuta sempre un valore predefinito per la proprietà di destinazione ( ad esempio Text="") perché in caso contrario sarà null e il trigger non funzionerà come previsto.

È inoltre possibile specificare raccolte e ExitActions facoltativeEnterActions. Per altre informazioni, vedere EnterActions e ExitActions.

Trigger di evento

Rappresenta EventTrigger un trigger che applica un set di azioni in risposta a un evento. A differenza di Trigger, EventTrigger non ha alcun concetto di terminazione dello stato, quindi le azioni non verranno annullate una volta che la condizione che ha generato l'evento non è più true.

Un EventTrigger oggetto richiede solo l'impostazione di una Event proprietà:

<EventTrigger Event="TextChanged">
    <local:NumericValidationTriggerAction />
</EventTrigger>

In questo esempio non Setter sono presenti elementi. È invece presente un NumericalValidationTriggerAction oggetto .

Nota

I trigger di evento non supportano EnterActions e ExitActions.

Un'implementazione dell'azione trigger deve:

• Implementare la classe TriggerAction<T> generica con il parametro generico corrispondente al tipo di controllo a cui verrà applicato il trigger. È possibile usare classi come VisualElement per scrivere azioni trigger che funzionano con un'ampia gamma di controlli o specificare un tipo di controllo come Entry.
• Eseguire l'override del metodo Invoke. Questo metodo viene chiamato ogni volta che si verifica l'evento trigger.
• Facoltativamente, esporre le proprietà che possono essere impostate in XAML quando il trigger viene dichiarato.

L'esempio seguente illustra la NumericValidationTriggerAction classe :

public class NumericValidationTriggerAction : TriggerAction<Entry>
{
    protected override void Invoke(Entry entry)
    {
        double result;
        bool isValid = Double.TryParse(entry.Text, out result);
        entry.TextColor = isValid ? Colors.Black : Colors.Red;
    }
}

Avviso

Prestare attenzione quando si condividono i trigger in un oggetto ResourceDictionary. Un'istanza verrà condivisa tra i controlli in modo che tutti gli stati configurati una volta verranno applicati a tutti.

Trigger multi-trigger

Un MultiTrigger oggetto rappresenta un trigger che applica i valori delle proprietà o esegue azioni quando viene soddisfatto un set di condizioni. Tutte le condizioni devono essere vere prima dell'applicazione degli Setter oggetti.

Nell'esempio seguente viene illustrato un oggetto MultiTrigger che esegue l'associazione a due Entry oggetti:

<Entry x:Name="email"
       Text="" />
<Entry x:Name="phone"
       Text="" />
<Button Text="Save">
    <Button.Triggers>
        <MultiTrigger TargetType="Button">
            <MultiTrigger.Conditions>
                <BindingCondition Binding="{Binding Source={x:Reference email},
                                            Path=Text.Length}"
                                  Value="0" />
                <BindingCondition Binding="{Binding Source={x:Reference phone},
                                            Path=Text.Length}"
                                  Value="0" />
            </MultiTrigger.Conditions>
            <Setter Property="IsEnabled" Value="False" />
            <!-- multiple Setter elements are allowed -->
        </MultiTrigger>
    </Button.Triggers>
</Button>

Inoltre, la MultiTrigger.Conditions raccolta può contenere PropertyCondition anche oggetti:

<PropertyCondition Property="Text"
                   Value="OK" />

EnterActions ed ExitActions

Un approccio alternativo all'implementazione delle modifiche quando si verifica un trigger consiste nell'specificare EnterActions e ExitActions nelle raccolte e creare TriggerAction<T> implementazioni.

La EnterActions raccolta, di tipo IList<TriggerAction>, definisce una raccolta che verrà richiamata quando viene soddisfatta la condizione del trigger. La ExitActions raccolta, di tipo IList<TriggerAction>, definisce una raccolta che verrà richiamata dopo che la condizione del trigger non viene più soddisfatta.

Nota

Gli oggetti TriggerAction definiti nelle raccolte EnterActions e ExitActions vengono ignorati dalla classe EventTrigger.

Nell'esempio seguente viene illustrato un trigger di proprietà che specifica un e EnterAction un ExitAction:

<Entry Placeholder="Enter job title">
    <Entry.Triggers>
        <Trigger TargetType="Entry"
                 Property="Entry.IsFocused"
                 Value="True">
            <Trigger.EnterActions>
                <local:FadeTriggerAction StartsFrom="0" />
            </Trigger.EnterActions>

            <Trigger.ExitActions>
                <local:FadeTriggerAction StartsFrom="1" />
            </Trigger.ExitActions>
        </Trigger>
    </Entry.Triggers>
</Entry>

Un'implementazione dell'azione trigger deve:

• Implementare la classe TriggerAction<T> generica con il parametro generico corrispondente al tipo di controllo a cui verrà applicato il trigger. È possibile usare classi come VisualElement per scrivere azioni trigger che funzionano con un'ampia gamma di controlli o specificare un tipo di controllo come Entry.
• Eseguire l'override del metodo Invoke. Questo metodo viene chiamato ogni volta che si verifica l'evento trigger.
• Facoltativamente, esporre le proprietà che possono essere impostate in XAML quando il trigger viene dichiarato.

L'esempio seguente illustra la FadeTriggerAction classe :

public class FadeTriggerAction : TriggerAction<VisualElement>
{
    public int StartsFrom { get; set; }

    protected override void Invoke(VisualElement sender)
    {
        sender.Animate("FadeTriggerAction", new Animation((d) =>
        {
            var val = StartsFrom == 1 ? d : 1 - d;
            sender.BackgroundColor = Color.FromRgb(1, val, 1);
        }),
        length: 1000, // milliseconds
        easing: Easing.Linear);
    }
}

Nota

È possibile fornire EnterActions e ExitActions nonché Setter oggetti in un trigger, ma tenere presente che gli Setter oggetti vengono chiamati immediatamente (non attendono il EnterAction completamento di o ExitAction ).

Trigger di stato

I trigger di stato sono un gruppo specializzato di trigger che definiscono le condizioni in cui deve essere applicato un oggetto VisualState .

I trigger di stato vengono aggiunti alla raccolta StateTriggers di VisualState. Questa raccolta può contenere un solo o più trigger di stato. VisualState viene applicato quando nella raccolta è attivo un qualsiasi trigger di stato.

Quando si usano trigger di stato per controllare gli stati di visualizzazione, .NET MAUI usa le regole di precedenza seguenti per determinare quale trigger (e corrispondente VisualState) sarà attivo:

1. Qualsiasi trigger che derivi da StateTriggerBase.
2. AdaptiveTrigger attivato perché la condizione MinWindowWidth è soddisfatta.
3. AdaptiveTrigger attivato perché la condizione MinWindowHeight è soddisfatta.

Se sono attivi più trigger, ad esempio due trigger personalizzati, contemporaneamente, il primo trigger dichiarato nel markup ha la precedenza.

Nota

I trigger di stato possono essere impostati in Style o direttamente negli elementi.

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

Trigger di stato

La classe StateTrigger, che deriva dalla classe StateTriggerBase, ha una proprietà IsActive associabile. StateTrigger attiva una modifica di VisualState quando la proprietà IsActive cambia valore.

La classe StateTriggerBase, che rappresenta la classe di base per tutti i trigger di stato, ha una proprietà IsActive e un evento IsActiveChanged. Questo evento viene generato ogni volta che si verifica una modifica di VisualState. Inoltre, la classe dispone di metodi e OnDetached di cui è possibile eseguire l'override.StateTriggerBaseOnAttached

Importante

La proprietà associabile StateTrigger.IsActive nasconde la proprietà StateTriggerBase.IsActive ereditata.

L'esempio di codice XAML seguente illustra un elemento Style che include oggetti StateTrigger:

<Style TargetType="Grid">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Checked">
                    <VisualState.StateTriggers>
                        <StateTrigger IsActive="{Binding IsToggled}"
                                      IsActiveChanged="OnCheckedStateIsActiveChanged" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Black" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Unchecked">
                    <VisualState.StateTriggers>
                        <StateTrigger IsActive="{Binding IsToggled, Converter={StaticResource inverseBooleanConverter}}"
                                      IsActiveChanged="OnUncheckedStateIsActiveChanged" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="White" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

In questo esempio, l'elemento Style implicito ha come destinazioni oggetti Grid. Quando la proprietà IsToggled dell'oggetto associato corrisponde a true, il colore di sfondo di Grid viene impostato sul nero. Quando la proprietà IsToggled dell'oggetto associato diventa false, viene attivata una modifica di VisualState e il colore di sfondo di Grid diventa bianco.

Inoltre, ogni volta che si verifica una VisualState modifica, viene generato l'evento IsActiveChanged per .VisualState Ogni VisualState registra un gestore per questo evento:

void OnCheckedStateIsActiveChanged(object sender, EventArgs e)
{
    StateTriggerBase stateTrigger = sender as StateTriggerBase;
    Console.WriteLine($"Checked state active: {stateTrigger.IsActive}");
}

void OnUncheckedStateIsActiveChanged(object sender, EventArgs e)
{
    StateTriggerBase stateTrigger = sender as StateTriggerBase;
    Console.WriteLine($"Unchecked state active: {stateTrigger.IsActive}");
}

In questo esempio, quando viene generato un gestore per l'evento IsActiveChanged , il gestore restituisce se VisualState è attivo o meno. Quando si passa dallo stato di visualizzazione Checked allo stato di visualizzazione Unchecked, ad esempio, nella finestra della console vengono visualizzati i messaggi seguenti:

Checked state active: False
Unchecked state active: True

Nota

I trigger di stato personalizzati possono essere creati derivando dalla StateTriggerBase classe ed eseguendo l'override dei OnAttached metodi e OnDetached per eseguire eventuali registrazioni e pulizia necessarie.

Trigger adattivi

AdaptiveTrigger attiva una modifica di VisualState quando la finestra assume l'altezza o la larghezza specificata. Questo trigger ha due proprietà associabili:

• MinWindowHeight, di tipo double, che indica l'altezza minima della finestra in corrispondenza della quale è necessario applicare VisualState.
• MinWindowWidth, di tipo double, che indica la larghezza minima della finestra in corrispondenza della quale è necessario applicare VisualState.

Nota

AdaptiveTrigger deriva dalla classe StateTriggerBase e può quindi allegare un gestore all'evento IsActiveChanged.

L'esempio di codice XAML seguente illustra un elemento Style che include oggetti AdaptiveTrigger:

<Style TargetType="StackLayout">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Vertical">
                    <VisualState.StateTriggers>
                        <AdaptiveTrigger MinWindowWidth="0" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="Orientation"
                                Value="Vertical" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Horizontal">
                    <VisualState.StateTriggers>
                        <AdaptiveTrigger MinWindowWidth="800" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="Orientation"
                                Value="Horizontal" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

In questo esempio, l'elemento Style implicito ha come destinazioni oggetti StackLayout. Quando la larghezza della finestra è compresa tra 0 e 800 unità indipendenti dal dispositivo, gli oggetti StackLayout a cui è applicato Style hanno un orientamento verticale. Quando la larghezza della finestra è >= 800 unità indipendenti dal dispositivo, viene attivata la VisualState modifica e l'orientamento StackLayout cambia in orizzontale.

Le proprietà MinWindowHeight e MinWindowWidth possono essere usate in modo indipendente o in combinazione. Il codice XAML seguente illustra un esempio di impostazione di entrambe le proprietà:

<AdaptiveTrigger MinWindowWidth="800"
                 MinWindowHeight="1200"/>

In questo esempio, indica AdaptiveTrigger che il corrispondente VisualState verrà applicato quando la larghezza della finestra corrente è >= 800 unità indipendenti dal dispositivo e l'altezza della finestra corrente è >= 1200 unità indipendenti dal dispositivo.

Trigger di stato di confronto

CompareStateTrigger attiva una modifica di VisualState quando una proprietà è uguale a un valore specifico. Questo trigger ha due proprietà associabili:

• Property, di tipo object, che indica la proprietà sottoposta a confronto dal trigger.
• Value, di tipo object, che indica il valore in corrispondenza del quale è necessario applicare VisualState.

Nota

CompareStateTrigger deriva dalla classe StateTriggerBase e può quindi allegare un gestore all'evento IsActiveChanged.

L'esempio di codice XAML seguente illustra un elemento Style che include oggetti CompareStateTrigger:

<Style TargetType="Grid">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Checked">
                    <VisualState.StateTriggers>
                        <CompareStateTrigger Property="{Binding Source={x:Reference checkBox}, Path=IsChecked}"
                                             Value="True" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Black" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Unchecked">
                    <VisualState.StateTriggers>
                        <CompareStateTrigger Property="{Binding Source={x:Reference checkBox}, Path=IsChecked}"
                                             Value="False" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="White" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>
...
<Grid>
    <Frame BackgroundColor="White"
           CornerRadius="12"
           Margin="24"
           HorizontalOptions="Center"
           VerticalOptions="Center">
        <StackLayout Orientation="Horizontal">
            <CheckBox x:Name="checkBox"
                      VerticalOptions="Center" />
            <Label Text="Check the CheckBox to modify the Grid background color."
                   VerticalOptions="Center" />
        </StackLayout>
    </Frame>
</Grid>

In questo esempio, l'elemento Style implicito ha come destinazioni oggetti Grid. Quando la proprietà IsChecked di CheckBox è false, il colore di sfondo di Grid viene impostato sul bianco. Quando la CheckBox.IsChecked proprietà diventa true, viene attivata una VisualState modifica e il colore di sfondo di Grid diventa nero.

Trigger di stato del dispositivo

DeviceStateTrigger attiva una modifica di VisualState in base alla piattaforma del dispositivo in cui è in esecuzione l'app. Questo trigger ha un'unica proprietà associabile:

• Device, di tipo string, che indica la piattaforma del dispositivo in cui è necessario applicare VisualState.

Nota

DeviceStateTrigger deriva dalla classe StateTriggerBase e può quindi allegare un gestore all'evento IsActiveChanged.

L'esempio di codice XAML seguente illustra un elemento Style che include oggetti DeviceStateTrigger:

<Style x:Key="DeviceStateTriggerPageStyle"
       TargetType="ContentPage">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="iOS">
                    <VisualState.StateTriggers>
                        <DeviceStateTrigger Device="iOS" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Silver" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Android">
                    <VisualState.StateTriggers>
                        <DeviceStateTrigger Device="Android" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="#2196F3" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

In questo esempio, l'elemento Style esplicito ha come destinazioni oggetti ContentPage. ContentPage gli oggetti che utilizzano lo stile impostano il colore di sfondo su argento in iOS e su blu pallido in Android.

Trigger di stato dell'orientamento

OrientationStateTrigger attiva una modifica di VisualState quando l'orientamento del dispositivo cambia. Questo trigger ha un'unica proprietà associabile:

• Orientation, di tipo DisplayOrientation, che indica l'orientamento a cui è necessario applicare VisualState.

Nota

OrientationStateTrigger deriva dalla classe StateTriggerBase e può quindi allegare un gestore all'evento IsActiveChanged.

L'esempio di codice XAML seguente illustra un elemento Style che include oggetti OrientationStateTrigger:

<Style x:Key="OrientationStateTriggerPageStyle"
       TargetType="ContentPage">
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup>
                <VisualState x:Name="Portrait">
                    <VisualState.StateTriggers>
                        <OrientationStateTrigger Orientation="Portrait" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="Silver" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="Landscape">
                    <VisualState.StateTriggers>
                        <OrientationStateTrigger Orientation="Landscape" />
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor"
                                Value="White" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

In questo esempio, l'elemento Style esplicito ha come destinazioni oggetti ContentPage. Gli oggetti ContentPage che utilizzano lo stile impostano il proprio colore di sfondo su argento quando l'orientamento è verticale e impostano il colore di sfondo su bianco quando l'orientamento è orizzontale.