Compartilhar via

Reconhecer um gesto de toque

  • Artigo

Um reconhecedor de gestos de toque do .NET Multi-Platform App UI (.NET MAUI) é usado para detecção de toque e é implementado com a TapGestureRecognizer classe. Essa classe define as seguintes propriedades:

  • Buttons, do tipo ButtonsMask, que define se o botão principal ou secundário do mouse, ou ambos, aciona o gesto no Android, Mac Catalyst e Windows. Para obter mais informações, consulte Definir as máscaras de botão.
  • Command, do tipo ICommand, que é executado quando um toque é reconhecido.
  • CommandParameter, do tipo object, que é o parâmetro passado para Command.
  • NumberOfTapsRequired, do tipo int, que representa o número de toques necessários para reconhecer um gesto de toque. O valor padrão desta propriedade é 1.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que elas podem ser alvos de associações de dados e estilizadas.

A TapGestureRecognizer classe também define um evento que é gerado quando um Tapped toque é reconhecido. O TappedEventArgs objeto que acompanha o evento define uma Parameter propriedade do tipo object que indica o Tapped valor passado pela CommandParameter propriedade, se definido. O TappedEventArgs objeto também define uma Buttons propriedade e um GetPosition método. A Buttons propriedade é do tipo ButtonsMaske pode ser usada para determinar se o botão primário ou secundário do mouse acionou o reconhecedor de gestos no Android, Mac Catalyst e Windows. O GetPosition método retorna um Point? objeto que representa a posição na qual o gesto de toque foi detectado. Para obter mais informações sobre máscaras de botão, consulte Definir a máscara de botão. Para obter mais informações sobre o GetPosition método, consulte Obter a posição do gesto.

Aviso

Não TapGestureRecognizer é possível reconhecer mais do que um toque duplo no Windows.

Criar um TapGestureRecognizer

Para reconhecer View um gesto de toque, crie um TapGestureRecognizer objeto, manipule o evento e adicione o Tapped novo reconhecedor de gestos à GestureRecognizers coleção no modo de exibição. O exemplo de código a seguir mostra um anexado a um TapGestureRecognizer Image:

<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <TapGestureRecognizer Tapped="OnTapGestureRecognizerTapped"
                              NumberOfTapsRequired="2" />
  </Image.GestureRecognizers>
</Image>

O código para o OnTapGestureRecognizerTapped manipulador de eventos deve ser adicionado ao arquivo code-behind:

void OnTapGestureRecognizerTapped(object sender, TappedEventArgs args)
{
    // Handle the tap
}

Este é o código C# equivalente:

TapGestureRecognizer tapGestureRecognizer = new TapGestureRecognizer();
tapGestureRecognizer.Tapped += (s, e) =>
{
    // Handle the tap
};
Image image = new Image();
image.GestureRecognizers.Add(tapGestureRecognizer);

Por padrão, o Image responderá a toques únicos. Quando a NumberOfTapsRequired propriedade é definida como maior que um, o manipulador de eventos só será executado se os toques ocorrerem dentro de um período de tempo definido. Se os segundos (ou subsequentes) toques não ocorrerem dentro desse período, eles serão efetivamente ignorados.

Definir a máscara de botão

Um TapGestureRecognizer objeto tem uma Buttons propriedade, do tipo ButtonsMask, que define se o botão primário ou secundário do mouse, ou ambos, aciona o gesto no Android, Mac Catalyst e Windows. A enumeração ButtonsMask define os seguintes membros:

  • Primary representa o botão principal do mouse, que normalmente é o botão esquerdo do mouse.
  • Secondary representa o botão secundário do mouse, que normalmente é o botão direito do mouse.

O exemplo a seguir mostra um TapGestureRecognizer que detecta toques com o botão secundário do mouse:

<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <TapGestureRecognizer Tapped="OnTapGestureRecognizerTapped"
                              Buttons="Secondary" />
  </Image.GestureRecognizers>
</Image>

O manipulador de eventos para o evento pode determinar qual botão disparou o Tapped gesto:

void OnTapGestureRecognizerTapped(object sender, TappedEventArgs args)
{
    // Handle the tap
    if (args.Buttons == ButtonsMask.Secondary)
    {
        // Do something
    }
}

Este é o código C# equivalente:

TapGestureRecognizer tapGestureRecognizer = new TapGestureRecognizer
{
    Buttons = ButtonsMask.Secondary
};
tapGestureRecognizer.Tapped += (s, e) =>
{
    // Handle the tap
    if (args.Buttons == ButtonsMask.Secondary)
    {
        // Do something
    }
};
Image image = new Image();
image.GestureRecognizers.Add(tapGestureRecognizer);

Aviso

No Windows, um que define a propriedade como Secondary não respeita a Buttons NumberOfTapsRequired propriedade quando ela é maior que umTapGestureRecognizer.

Além disso, um TapGestureRecognizer pode ser definido para que o botão primário ou secundário do mouse acione o gesto:

<TapGestureRecognizer Tapped="OnTapGestureRecognizerTapped"
                      Buttons="Primary,Secondary" />

Este é o código C# equivalente:

TapGestureRecognizer tapGestureRecognizer = new TapGestureRecognizer
{
    Buttons = ButtonsMask.Primary | ButtonsMask.Secondary
};

Obter a posição do gesto

A posição na qual ocorreu um gesto de toque pode ser obtida chamando o GetPosition método em um TappedEventArgs objeto. O GetPosition método aceita um argumento e retorna uma posição como um Element? Point? objeto:

void OnTapGestureRecognizerTapped(object sender, TappedEventArgs e)
{
    // Position inside window
    Point? windowPosition = e.GetPosition(null);

    // Position relative to an Image
    Point? relativeToImagePosition = e.GetPosition(image);

    // Position relative to the container view
    Point? relativeToContainerPosition = e.GetPosition((View)sender);
}

O Element? argumento define o elemento ao qual a posição deve ser obtida em relação. Fornecer um valor como esse argumento significa que o GetPosition método retorna um null Point? objeto que define a posição do gesto de toque dentro da janela.