TouchBehavior

Artigo
04/08/2024

O TouchBehavior é um Behavior que fornece a capacidade de interagir com qualquer VisualElement com base em eventos de toque, clique do mouse e foco. A implementação TouchBehavior torna possível personalizar muitas propriedades visuais diferentes do VisualElement ao qual está anexado, como BackgroundColor, Opacity, Rotation e Scale, bem como muitas outras propriedades.

Observação

O kit de ferramentas também fornece a implementação ImageTouchBehavior que estende isso TouchBehavior, fornecendo também a capacidade de personalizar o Source de um elemento Image.

Importante

Os comportamentos do .NET MAUI Community Toolkit não definem o BindingContext de um comportamento, porque os comportamentos podem ser compartilhados e aplicados a vários controles por meio de estilos. Para mais informações confira Comportamentos do .NET MAUI

Sintaxe

Os exemplos a seguir mostram como adicionar TouchBehavior a um pai HorizontalStackLayout e executar as seguintes animações quando um usuário toca ou clica no HorizontalStackLayout ou em qualquer um de seus filhos:

é animado durante um período de 250 milissegundos
aplica o CubicInOut Easing
altera o Opacity para 0.6
altera o Scale para 0.8

XAML

Incluir o namespace XAML

Para usar o kit de ferramentas no XAML, o xmlns a seguir precisa ser adicionado à sua página ou exibição:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Portanto, o seguinte:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Seria modificado para incluir o xmlns conforme o seguinte:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Como usar o TouchBehavior

<ContentPage 
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
    x:Class="CommunityToolkit.Maui.Sample.Pages.Behaviors.TouchBehaviorPage">

   <HorizontalStackLayout HorizontalOptions="Center" VerticalOptions="Center">
        <HorizontalStackLayout.Behaviors>
            <toolkit:TouchBehavior
                DefaultAnimationDuration="250"
                DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
                PressedOpacity="0.6"
                PressedScale="0.8" />
        </HorizontalStackLayout.Behaviors>

        <ContentView
            HeightRequest="100"
            WidthRequest="10"
            BackgroundColor="Gold" />
        <Label Text="The entire layout receives touches" VerticalOptions="Center" LineBreakMode="TailTruncation"/>
        <ContentView
            HeightRequest="100"
            WidthRequest="10"
            BackgroundColor="Gold" />
    </HorizontalStackLayout>

</ContentPage>

C#

O TouchBehavior pode ser usado da seguinte maneira em C#:

class TouchBehaviorPage : ContentPage
{
    public TouchBehaviorPage()
    {
        var firstContent = new ContentView
        {
            HeightRequest = 100,
            WidthRequest = 10,
            BackgroundColor = Colors.Gold
        };

        var label = new Label
        {
            Text = "The entire layout receives touches",
            VerticalOptions = LayoutOptions.Center,
            LineBreakMode = LineBreakMode.TailTruncation
        };

        var secondContent = new ContentView
        {
            HeightRequest = 100,
            WidthRequest = 10,
            BackgroundColor = Colors.Gold
        };

        var layout = new HorizontalStackLayout
        {
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.Center,
            Children = 
            {
                firstContent,
                label,
                secondContent
            }
        }

        var touchBehavior = new TouchBehavior
        {
            DefaultAnimationDuration = 250,
            DefaultAnimationEasing = Easing.CubicInOut,
            PressedOpacity = 0.6,
            PressedScale = 0.8
        };

        layout.Behaviors.Add(touchBehavior);

        Content = layout;
    }
}

Markup do C#

Nosso pacote CommunityToolkit.Maui.Markup fornece uma maneira muito mais concisa de usar esse Behavior em C#.

using CommunityToolkit.Maui.Markup;

class TouchBehaviorPage : ContentPage
{
    public TouchBehaviorPage()
    {
        Content = new HorizontalStackLayout
        {
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.Center,
            Children = 
            {
                new ContentView()
                    .Size(10, 100)
                    .BackgroundColor(Colors.Gold),

                new Label
                {
                    LineBreakMode = LineBreakMode.TailTruncation
                }
                    .Text("The entire layout receives touches"
                    .CenterVertical(),

                new ContentView()
                    .Size(10, 100)
                    .BackgroundColor(Colors.Gold)
            }
        }
            .Behaviors(new TouchBehavior
            {
                DefaultAnimationDuration = 250,
                DefaultAnimationEasing = Easing.CubicInOut,
                PressedOpacity = 0.6,
                PressedScale = 0.8
            });
    }
}

Mais exemplos

Lidando com interação instantânea

O TouchBehavior fornece a capacidade de personalizar as propriedades do anexado VisualElement com base no fato de o mouse estar passando sobre o elemento.

O exemplo a seguir mostra como anexar o TouchBehavior a um HorizontalStackLayout e alterar o BackgroundColor e o Scale do HorizontalStackLayout quando um usuário passa o cursor do mouse sobre o layout e quaisquer elementos filhos.

<HorizontalStackLayout
    Padding="20"
    Background="Black"
    HorizontalOptions="Center">
    <HorizontalStackLayout.Behaviors>
        <toolkit:TouchBehavior
            HoveredBackgroundColor="{StaticResource Gray900}"
            HoveredScale="1.2" />
    </HorizontalStackLayout.Behaviors>
</HorizontalStackLayout>

Lidando com interação de toque longo

O TouchBehavior fornece a capacidade de lidar com o cenário quando um usuário pressiona por um longo período de tempo. Esse período de tempo pode ser definido pelo LongPressDuration que está em unidades de milissegundos.

O exemplo a seguir mostra como adicionar TouchBehavior a HorizontalStackLayout, vincular LongPressCommand ao IncreaseLongPressCountCommand definido no modelo de visualização de apoio e definir LongPressDuration como 750 milissegundos.

<HorizontalStackLayout
    Padding="20"
    Background="Black"
    HorizontalOptions="Center"
    x:Name="TouchableHorizontalStackLayout">
    <HorizontalStackLayout.Behaviors>
        <toolkit:TouchBehavior
            BindingContext="{Binding Source={x:Reference Page}, Path=BindingContext, x:DataType=ContentPage}"
            LongPressDuration="750"
            LongPressCommand="{Binding Source={x:Reference Page}, Path=BindingContext.IncreaseLongPressCountCommand, x:DataType=ContentPage}"/>
    </HorizontalStackLayout.Behaviors>
</HorizontalStackLayout>

Propriedades

Propriedade	Type	Descrição
Comando	`ICommand`	Obtém ou define o `ICommand` a ser invocado quando o usuário concluir um gesto de toque.
CommandParameter	`object`	Obtém ou define o parâmetro a ser passado para a propriedade `Command`.
CurrentHoverState	`HoverState`	Obtém ou define o `HoverState` atual do comportamento.
CurrentHoverStatus	`HoverStatus`	Obtém ou define o `HoverStatus` atual do comportamento.
CurrentInteractionStatus	`TouchInteractionStatus`	Obtém ou define o `TouchInteractionStatus` atual do comportamento.
CurrentTouchState	`TouchState`	Obtém ou define o `TouchState` atual do comportamento.
CurrentTouchStatus	`TouchStatus`	Obtém ou define o `TouchStatus` atual do comportamento.
DefaultAnimationDuration	`int`	Obtém ou define a duração da animação quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultAnimationEasing	`Easing`	Obtém ou define a atenuação da animação quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultBackgroundColor	`Color`	Obtém ou define a cor de fundo do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultOpacity	`double`	Obtém ou define a opacidade do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultRotation	`double`	Obtém ou define a rotação em torno dos eixos X e Y do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultRotationX	`double`	Obtém ou define a rotação em torno do eixo X do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultRotationY	`double`	Obtém ou define a rotação em torno do eixo Y do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultScale	`double`	Obtém ou define a escala do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultTranslationX	`double`	Obtém ou define a tradução X do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DefaultTranslationY	`double`	Obtém ou define a tradução Y do elemento quando a propriedade `CurrentTouchState` é `TouchState.Default`.
DisallowTouchThreshold	`int`	Obtém ou define o limite para proibir o toque.
HoveredAnimationDuration	`int`	Obtém ou define a duração da animação quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredAnimationEasing	`Easing`	Obtém ou define a atenuação da animação quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredBackgroundColor	`Color`	Obtém ou define a cor de fundo do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredOpacity	`double`	Obtém ou define a opacidade do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredRotation	`double`	Obtém ou define a rotação em torno dos eixos X e Y do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredRotationX	`double`	Obtém ou define a rotação em torno do eixo X do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredRotationY	`double`	Obtém ou define a rotação em torno do eixo Y do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredScale	`double`	Obtém ou define a escala do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredTranslationX	`double`	Obtém ou define a tradução X do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
HoveredTranslationY	`double`	Obtém ou define a tradução Y do elemento quando a propriedade `CurrentHoverState` é `HoverState.Hovered`.
IsEnabled	`bool`	Obtém ou define um valor que indica se o comportamento está habilitado.
LongPressCommand	`ICommand`	Obtém ou define o `ICommand` a ser invocado quando o usuário concluir um toque longo.
LongPressCommandParameter	`object`	Obtém ou define o parâmetro a ser passado para a propriedade `LongPressCommand`.
LongPressDuration	`int`	Obtém ou define a duração em milissegundos necessária para acionar o gesto de toque longo.
PressedAnimationDuration	`int`	Obtém ou define a duração da animação quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedAnimationEasing	`Easing`	Obtém ou define a atenuação da animação quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedBackgroundColor	`Color`	Obtém ou define a cor de fundo do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedOpacity	`double`	Obtém ou define a opacidade do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedRotation	`double`	Obtém ou define a rotação em torno dos eixos X e Y do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedRotationX	`double`	Obtém ou define a rotação em torno do eixo X do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedRotationY	`double`	Obtém ou define a rotação em torno do eixo Y do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedScale	`double`	Obtém ou define a escala do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedTranslationX	`double`	Obtém ou define a tradução X do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
PressedTranslationY	`double`	Obtém ou define a tradução Y do elemento quando a propriedade `CurrentTouchState` é `TouchState.Pressed`.
ShouldMakeChildrenInputTransparent	`bool`	Obtém ou define um valor que indica se os filhos do elemento devem ter entrada transparente.

Eventos

Evento	Descrição
`CurrentTouchStateChanged`	Dispara quando `CurrentTouchState` altera.
`CurrentTouchStatusChanged`	Dispara quando `CurrentTouchStatus` altera.
`HoverStateChanged`	Dispara quando `CurrentHoverState` altera.
`HoverStatusChanged`	Dispara quando `CurrentHoverStatus` altera.
`InteractionStatusChanged`	Dispara quando `CurrentInteractionStatus` altera.
`LongPressCompleted`	Dispara quando um gesto de pressão longa é concluído.
`TouchGestureCompleted`	Dispara quando um gesto de toque é concluído.

Exemplos

Você pode encontrar um exemplo desse comportamento em ação no Aplicativo de exemplo do .NET MAUI Community Toolkit.

API

O código-fonte do TouchBehavior pode ser encontrado no repositório GitHub do .NET MAUI Community Toolkit.

Migrando do Xamarin Community Toolkit

No Xamarin Community Toolkit, havia o TouchEffect caso de você estivesse atualizando um aplicativo do Xamarin.Forms para o .NET MAUI; há algumas alterações significativas das quais você deve estar ciente:

Alterações no nome da API
O TouchBehavior agora é implementado como um PlatformBehavior

Alterações no nome da API

Nome no Kit de Ferramentas da Comunidade do Xamarin	Nome no Kit de Ferramentas da Comunidade do MAUI
TouchEffect	TouchBehavior
NormalBackgroundColor	DefaultBackgroundColor
NormalScale	DefaultScale
NormalOpacity	DefaultOpacity
NormalTranslationX	DefaultTranslationX
NormalTranslationY	DefaultTranslationY
NormalRotation	DefaultRotation
NormalRotationX	DefaultRotationX
NormalRotationY	DefaultRotationY
NormalAnimationDuration	DefaultAnimationDuration
NormalAnimationEasing	DefaultAnimationEasing
NormalBackgroundImageSource	DefaultImageSource (Movido para `ImageTouchBehavior`)
NormalBackgroundImageAspect	DefaultImageAspect (Movido para `ImageTouchBehavior` )

O TouchBehavior agora é implementado como um `PlatformBehavior`

No Xamarin Community Toolkit, TouchEffect foi implementado como um AttachedEffect. Para usar o efeito, você usaria as propriedades anexadas e aplicaria a qualquer VisualElement

No .NET MAUI, o TouchBehavior é implementado como um PlatformBehavior que agora é aplicado à coleção de comportamentos de elementos; confira Comportamentos da Plataforma para obter mais informações.

Observação: por padrão, no .NET MAUI, PlatformBehaviors não definirão a propriedade BindingContext; isso ocorre porque comportamentos podem ser compartilhados em estilos. TouchBehavior definirá a propriedade BindingContext igual ao VisualElement ao qual ela é aplicada. Isso significa que você não deve compartilhar o TouchBehavior entre elementos por meio de estilos.

Veja abaixo um exemplo de um TouchEffect sendo aplicado a uma exibição no Xamarin.Forms:

XAML
C#

<StackLayout Orientation="Horizontal"
            HorizontalOptions="CenterAndExpand"
            xct:TouchEffect.AnimationDuration="250"
            xct:TouchEffect.AnimationEasing="{x:Static Easing.CubicInOut}"
            xct:TouchEffect.PressedScale="0.8"
            xct:TouchEffect.PressedOpacity="0.6"
            xct:TouchEffect.Command="{Binding Command}">
    <BoxView Color="Gold" />
    <Label Text="The entire layout receives touches" />
    <BoxView Color="Gold"/>
</StackLayout>

var stackLayout = new StackLayout()
{
    HorizontalOptions = LayoutOptions.CenterAndExpand,
    Orientation = StackOrientation.Horizontal,
    Children =
    {
        new BoxView() { Color = Color.Gold, },
        new Label() { Text = "The entire layout receives touches", },
        new BoxView() { Color = Color.Gold, },
    }
};

TouchEffect.SetAnimationDuration(stackLayout, 250);
TouchEffect.SetAnimationEasing(stackLayout, Easing.CubicInOut);
TouchEffect.SetPressedScale(stackLayout, 0.8);
TouchEffect.SetPressedOpacity(stackLayout, 0.6);
TouchEffect.SetCommand(stackLayout, command);

O TouchBehavior equivalente no .NET MAUI teria esta aparência:

XAML
C#

<HorizontalStackLayout 
    HorizontalOptions="Center" 
    VerticalOptions="Center"
    x:Name="TouchableHorizontalLayout">
    <HorizontalStackLayout.Behaviors>
        <toolkit:TouchBehavior
            DefaultAnimationDuration="250"
            DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
            PressedOpacity="0.6"
            PressedScale="0.8"
            BindingContext="{Binding Path=BindingContext, Source={x:Reference TouchableHorizontalLayout}, x:DataType=HorizontalStackLayout}"
            Command="{Binding LayoutTappedCommand}" />
    </HorizontalStackLayout.Behaviors>

    <ContentView
        BackgroundColor="Gold"
        HeightRequest="100"
        WidthRequest="10" />
    <Label
        LineBreakMode="TailTruncation"
        Text="The entire layout receives touches"
        VerticalOptions="Center" />
    <ContentView
        BackgroundColor="Gold"
        HeightRequest="100"
        WidthRequest="10" />
</HorizontalStackLayout>

var stackLayout = new HorizontalStackLayout()
{
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center,
    Children =
    {
        new ContentView()
        {
            BackgroundColor = Colors.Gold,
            HeightRequest = 100,
            WidthRequest = 10,
        },
        new Label()
        {
            LineBreakMode = LineBreakMode.TailTruncation,
            Text = "The entire layout receives touches",
            VerticalOptions = LayoutOptions.Center,
        },
        new ContentView()
        {
            BackgroundColor = Colors.Gold,
            HeightRequest = 100,
            WidthRequest = 10,
        },
    },
    Behaviors =
    {
        new TouchBehavior()
        {
            DefaultAnimationDuration = 250,
            DefaultAnimationEasing = Easing.CubicInOut,
            PressedOpacity = 0.6,
            PressedScale = 0.8,
            Command = command,
            BindingContext = this.BindingContext
        }
    }
};

Partilhar via

TouchBehavior

Sintaxe

XAML

Incluir o namespace XAML

Como usar o TouchBehavior

C#

Markup do C#

Mais exemplos

Lidando com interação instantânea

Lidando com interação de toque longo

Propriedades

Eventos

Exemplos

API

Migrando do Xamarin Community Toolkit

Alterações no nome da API

O TouchBehavior agora é implementado como um `PlatformBehavior`

Recursos adicionais

Partilhar via

TouchBehavior

Sintaxe

XAML

Incluir o namespace XAML

Como usar o TouchBehavior

C#

Markup do C#

Mais exemplos

Lidando com interação instantânea

Lidando com interação de toque longo

Propriedades

Eventos

Exemplos

API

Migrando do Xamarin Community Toolkit

Alterações no nome da API

O TouchBehavior agora é implementado como um PlatformBehavior

Recursos adicionais

O TouchBehavior agora é implementado como um `PlatformBehavior`