Gatilhos

Artigo
11/11/2023

Os gatilhos da IU do aplicativo multiplataforma do .NET (.NET MAUI) permitem que você expresse ações declarativamente em XAML que alteram a aparência dos controles com base em eventos ou alterações de dados. Além disso, os gatilhos de estado, que são um grupo especializado de gatilhos, definem quando se deve aplicar VisualState.

Você pode atribuir um gatilho diretamente à coleção de Triggers um controle ou adicioná-lo a um dicionário de recursos no nível da página ou no nível do aplicativo para ser aplicado a vários controles.

Gatilhos de propriedades

A Trigger representa um gatilho que aplica valores de propriedade ou executa ações quando a propriedade especificada atende a uma condição especificada.

O exemplo a seguir mostra um que altera uma cor de Trigger Entry plano de fundo quando recebe foco:

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

A declaração do gatilho especifica o seguinte:

TargetType - o tipo de controle ao qual o gatilho se aplica.
Property - a propriedade no controle que é monitorado.
Value - o valor, quando ocorre para a propriedade monitorada, que faz com que o gatilho seja ativado.
Setter - uma coleção de elementos que são aplicados quando a condição de Setter gatilho é atendida.

Além disso, opcionais EnterActions e ExitActions coleções podem ser especificados. Para obter mais informações, consulte EnterActions e ExitActions.

Aplicar um gatilho usando um estilo

Gatilhos também podem ser adicionados a uma declaração Style em um controle, em uma página ou um aplicativo ResourceDictionary. O exemplo a seguir declara um estilo implícito para todos os Entry controles na página:

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

Gatilhos de dados

A DataTrigger representa um gatilho que aplica valores de propriedade ou executa ações quando os dados vinculados atendem a uma condição especificada. A Binding extensão de marcação é usada para monitorar a condição especificada.

O exemplo a seguir mostra um que desabilita um DataTrigger Button quando o Entry está vazio:

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

Neste exemplo, quando o comprimento do Entry é zero, o gatilho é ativado.

Dica

Ao avaliar Path=Text.Length , sempre forneça um valor padrão para a propriedade de destino (por exemplo, porque caso contrário, Text=""será null e o gatilho não funcionará como você espera.

Além disso, opcionais EnterActions e ExitActions coleções podem ser especificados. Para obter mais informações, consulte EnterActions e ExitActions.

Gatilhos de evento

An EventTrigger representa um gatilho que aplica um conjunto de ações em resposta a um evento. Ao contrário Triggerde , não tem conceito de extinção de estado, portanto, EventTrigger as ações não serão desfeitas uma vez que a condição que gerou o evento não é mais verdadeira.

Um EventTrigger só requer que uma Event propriedade seja definida:

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

Neste exemplo, não Setter há elementos . Em vez disso, há um NumericalValidationTriggerAction objeto.

Observação

Os gatilhos de eventos não oferecem suporte EnterActions e ExitActions.

A execução de uma ação de desencadeamento deve:

Implementar a classe TriggerAction<T> genérica com o parâmetro genérico correspondente com o tipo de controle ao qual o gatilho será aplicado. Você pode usar classes como para escrever ações de gatilho que funcionam com uma variedade de controles ou especificar um tipo de controle como VisualElement Entry.
Substitua o método Invoke. Esse método é chamado sempre que o evento trigger ocorre.
Opcionalmente, exponha propriedades que podem ser definidas em XAML quando o gatilho é declarado.

O exemplo a seguir mostra a classe NumericValidationTriggerAction:

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

Aviso

Tenha cuidado ao compartilhar gatilhos em um ResourceDictionaryarquivo . Uma instância será compartilhada entre os controles, portanto, qualquer estado configurado uma vez será aplicado a todos eles.

Multi-gatilhos

A MultiTrigger representa um gatilho que aplica valores de propriedade ou executa ações quando um conjunto de condições é satisfeito. Todas as condições devem ser verdadeiras antes que os Setter objetos sejam aplicados.

O exemplo a seguir mostra um MultiTrigger que se liga a dois Entry objetos:

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

Além disso, a MultiTrigger.Conditions coleção também pode conter PropertyCondition objetos:

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

EnterActions e ExitActions

Uma abordagem alternativa para implementar alterações quando ocorre um gatilho é especificando EnterActions e coleções e ExitActions criando TriggerAction<T> implementações.

A EnterActions coleção, do tipo IList<TriggerAction>, define uma coleção que será chamada quando a condição de gatilho for atendida. A ExitActions coleção, do tipo IList<TriggerAction>, define uma coleção que será invocada depois que a condição de gatilho não for mais atendida.

Observação

Os objetos TriggerAction definidos nas coleções EnterActions e ExitActions são ignorados pela classe EventTrigger.

O exemplo a seguir mostra um gatilho de propriedade que especifica um e um EnterActionExitAction:

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

A execução de uma ação de desencadeamento deve:

Implementar a classe TriggerAction<T> genérica com o parâmetro genérico correspondente com o tipo de controle ao qual o gatilho será aplicado. Você pode usar classes como para escrever ações de gatilho que funcionam com uma variedade de controles ou especificar um tipo de controle como VisualElement Entry.
Substitua o método Invoke. Esse método é chamado sempre que o evento trigger ocorre.
Opcionalmente, exponha propriedades que podem ser definidas em XAML quando o gatilho é declarado.

O exemplo a seguir mostra a classe FadeTriggerAction:

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

Observação

Você pode fornecer EnterActions e ExitActions bem como Setter objetos em um gatilho, mas esteja ciente de que os Setter objetos são chamados imediatamente (eles não esperam que o EnterAction ou ExitAction seja concluído).

Gatilhos de estado

Os gatilhos de estado são um grupo especializado de gatilhos que definem as condições sob as quais um VisualState deve ser aplicado.

Os gatilhos de estado são adicionados à coleção de StateTriggers de um VisualState. Essa coleção pode conter um ou vários gatilhos de estado. Um VisualState será aplicado quando qualquer gatilho de estado na coleção estiver ativo.

Ao usar gatilhos de estado para controlar estados visuais, o .NET MAUI usa as seguintes regras de precedência para determinar qual gatilho (e correspondente VisualState) estará ativo:

Um gatilho que deriva de StateTriggerBase.
Um AdaptiveTrigger ativado porque a condição MinWindowWidth foi atendida.
Um AdaptiveTrigger ativado porque a condição MinWindowHeight foi atendida.

Se múltiplos gatinhos estiverem simultaneamente ativos (por exemplo, dois gatilhos personalizados), o primeiro gatilho declarado na marcação terá precedência.

Observação

Os gatilhos de estado podem ser definidos em Style ou diretamente nos elementos.

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

Gatilho de estado

A classe StateTrigger, que deriva da classe StateTriggerBase, tem uma propriedade associável IsActive. Um StateTrigger aciona o gatilho de uma alteração VisualState quando a propriedade IsActive muda de valor.

A classe StateTriggerBase, que é a classe base de todos os gatilhos de estado, tem uma propriedade IsActive e um evento IsActiveChanged. Esse evento é disparado sempre que ocorre uma alteração em VisualState. Além disso, a StateTriggerBase classe tem métodos e substituíveis OnDetached OnAttached.

Importante

A propriedade associável StateTrigger.IsActive oculta a propriedade herdada StateTriggerBase.IsActive.

O exemplo de XAML a seguir mostra um Style que inclui os objetos 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>

Nesse exemplo, o Style implícito tem como destino os objetos Grid. Quando a propriedade IsToggled do objeto associado é true, a cor da tela de fundo de Grid é definida como preto. Quando a propriedade IsToggled do objeto associado se torna false, uma alteração de VisualState é disparada, e a cor da tela de fundo de Grid se torna branca.

Além disso, toda vez que ocorre uma VisualState alteração, o evento para o IsActiveChanged VisualState é gerado. Cada VisualState registra um manipulador de eventos para esse 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}");
}

Neste exemplo, quando um manipulador para o evento é gerado, o manipulador gera se o IsActiveChanged VisualState está ativo ou não. Por exemplo, as mensagens a seguir são enviadas para a janela do console ao alterar do estado visual Checked para o estado visual Unchecked:

Checked state active: False
Unchecked state active: True

Observação

Os gatilhos de estado personalizados podem ser criados derivando da StateTriggerBase classe e substituindo os OnAttached métodos e para executar quaisquer registros e OnDetached limpeza necessários.

Gatilho adaptável

Um AdaptiveTrigger dispara uma alteração VisualState quando a janela tem a altura ou largura especificada. Esse gatilho tem duas propriedades associáveis:

MinWindowHeight, do tipo double, que indica a altura mínima da janela na qual VisualState deve ser aplicado.
MinWindowWidth, do tipo double, que indica a largura mínima da janela na qual VisualState deve ser aplicado.

Observação

AdaptiveTrigger deriva da classe StateTriggerBase e, portanto, pode anexar um manipulador de eventos ao evento IsActiveChanged.

O exemplo de XAML a seguir mostra um Style que inclui os objetos 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>

Nesse exemplo, o Style implícito tem como destino os objetos StackLayout. Quando a largura da janela está entre 0 e 800 unidades independentes de dispositivo, os objetos de StackLayout aos quais Style é aplicado terão uma orientação vertical. Quando a largura da janela é = 800 unidades independentes de dispositivo, a alteração é >acionada e a StackLayout VisualState orientação muda para horizontal.

As propriedades MinWindowHeight e MinWindowWidth podem ser usadas de forma independente ou em conjunto uma com a outra. O XAML a seguir mostra um exemplo da definição das duas propriedades:

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

Neste exemplo, o indica que o AdaptiveTrigger correspondente VisualState será aplicado quando a largura da janela atual for = 800 unidades independentes de dispositivo e a altura da janela atual for >>= 1200 unidades independentes de dispositivo.

Comparar gatilho de estado

O CompareStateTrigger dispara uma alteração de VisualState quando a propriedade é igual a um valor específico. Esse gatilho tem duas propriedades associáveis:

Property, do tipo object, que indica a propriedade comparada pelo gatilho.
Value, do tipo object, que indica o valor no qual VisualState deve ser aplicado.

Observação

CompareStateTrigger deriva da classe StateTriggerBase e, portanto, pode anexar um manipulador de eventos ao evento IsActiveChanged.

O exemplo de XAML a seguir mostra um Style que inclui os objetos 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>

Nesse exemplo, o Style implícito tem como destino os objetos Grid. Quando a propriedade IsChecked do objeto CheckBox é false, a cor da tela de fundo de Grid é definida como branca. Quando a propriedade se torna , uma VisualState alteração é acionada e a CheckBox.IsChecked cor do plano de fundo do Grid torna-se truepreta.

Gatilho de estado de dispositivo

O DeviceStateTrigger dispara uma alteração de VisualState com base na plataforma do dispositivo na qual o aplicativo está em execução. Esse gatilho tem uma única propriedade associável:

Device, do tipo string, que indica a plataforma do dispositivo na qual VisualState deve ser aplicado.

Observação

DeviceStateTrigger deriva da classe StateTriggerBase e, portanto, pode anexar um manipulador de eventos ao evento IsActiveChanged.

O exemplo de XAML a seguir mostra um Style que inclui os objetos 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>

Nesse exemplo, o Style explícito tem como destino os objetos ContentPage. ContentPage objetos que consomem o estilo definem sua cor de fundo para prata no iOS e para azul pálido no Android.

Gatilho de estado de orientação

O OrientationStateTrigger dispara uma alteração VisualState quando a orientação do dispositivo é alterada. Esse gatilho tem uma única propriedade associável:

Orientation, do tipo DisplayOrientation, que indica a orientação que deve ser aplicada a VisualState.

Observação

OrientationStateTrigger deriva da classe StateTriggerBase e, portanto, pode anexar um manipulador de eventos ao evento IsActiveChanged.

O exemplo de XAML a seguir mostra um Style que inclui os objetos 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>

Nesse exemplo, o Style explícito tem como destino os objetos ContentPage. Os objetos ContentPage que consomem o estilo definem sua cor de plano de fundo como prata quando a orientação é retrato e como branco quando a orientação é paisagem.

Partilhar via

Gatilhos

Gatilhos de propriedades

Aplicar um gatilho usando um estilo

Gatilhos de dados

Gatilhos de evento

Multi-gatilhos

EnterActions e ExitActions

Gatilhos de estado

Gatilho de estado

Gatilho adaptável

Comparar gatilho de estado

Gatilho de estado de dispositivo

Gatilho de estado de orientação

Comentários

Recursos adicionais