Riconoscere un movimento di tocco

Per il rilevamento del tocco viene usato un sistema di riconoscimento dei movimenti dell'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) e viene implementato con la TapGestureRecognizer classe . Questa classe definisce le proprietà seguenti:

• Buttons, di tipo ButtonsMask, che definisce se il pulsante primario o secondario del mouse, o entrambi, attiva il movimento in Android, Mac Catalyst e Windows. Per altre informazioni, vedere Definire le maschere dei pulsanti.
• Command, di tipo ICommand, che viene eseguito quando viene riconosciuto un tocco.
• CommandParameter, di tipo object, ovvero il parametro passato a Command.
• NumberOfTapsRequired, di tipo int, che rappresenta il numero di tap necessari per riconoscere un movimento di tocco. Il valore predefinito di questa proprietà è 1.

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

La TapGestureRecognizer classe definisce anche un Tapped evento generato quando viene riconosciuto un tocco. L'oggetto TappedEventArgs che accompagna l'evento Tapped definisce una Parameter proprietà di tipo object che indica il valore passato dalla CommandParameter proprietà , se definito. L'oggetto TappedEventArgs definisce anche una Buttons proprietà e un GetPosition metodo . La Buttons proprietà è di tipo ButtonsMaske può essere usata per determinare se il pulsante primario o secondario del mouse ha attivato il riconoscimento movimento in Android, Mac Catalyst e Windows. Il GetPosition metodo restituisce un Point? oggetto che rappresenta la posizione in cui è stato rilevato il movimento di tocco. Per altre informazioni sulle maschere dei pulsanti, vedere Definire la maschera pulsante. Per altre informazioni sul GetPosition metodo, vedere Ottenere la posizione del movimento.

Avviso

Un TapGestureRecognizer oggetto non può riconoscere più di un doppio tocco su Windows.

Creare un oggetto TapGestureRecognizer

Per riconoscere un View movimento di tocco, creare un TapGestureRecognizer oggetto, gestire l'evento Tapped e aggiungere il nuovo riconoscimento movimento alla GestureRecognizers raccolta nella visualizzazione. L'esempio di codice seguente mostra un TapGestureRecognizer oggetto associato a un oggetto Image:

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

Il codice per il OnTapGestureRecognizerTapped gestore eventi deve essere aggiunto al file code-behind:

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

Il codice C# equivalente è il seguente:

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

Per impostazione predefinita, risponderà Image ai singoli tap. Quando la NumberOfTapsRequired proprietà è impostata su maggiore di una, il gestore eventi verrà eseguito solo se i tap si verificano entro un determinato periodo di tempo. Se il secondo (o successivo) tocco non si verifica entro tale periodo, vengono effettivamente ignorati.

Definire la maschera pulsante

Un TapGestureRecognizer oggetto ha una Buttons proprietà di tipo ButtonsMask, che definisce se il pulsante del mouse primario o secondario o entrambi attiva il movimento su Android, Mac Catalyst e Windows. L'enumerazione ButtonsMask definisce i membri seguenti:

• Primary rappresenta il pulsante principale del mouse, che in genere è il pulsante sinistro del mouse.
• Secondary rappresenta il pulsante secondario del mouse, che in genere è il pulsante destro del mouse.

L'esempio seguente mostra un TapGestureRecognizer oggetto che rileva i tocco con il pulsante del mouse secondario:

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

Il gestore eventi per l'evento Tapped può determinare quale pulsante ha attivato il movimento:

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

Il codice C# equivalente è il seguente:

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

Avviso

In Windows un oggetto TapGestureRecognizer che imposta la Buttons proprietà su Secondary non rispetta la NumberOfTapsRequired proprietà quando è maggiore di uno.

Inoltre, è possibile definire un oggetto TapGestureRecognizer in modo che il pulsante primario o secondario del mouse attivi il movimento:

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

Il codice C# equivalente è il seguente:

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

Ottenere la posizione del movimento

La posizione in cui si è verificato un movimento di tocco può essere ottenuta chiamando il GetPosition metodo su un TappedEventArgs oggetto . Il GetPosition metodo accetta un Element? argomento e restituisce una posizione come Point? oggetto :

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

L'argomento Element? definisce l'elemento a cui deve essere ottenuta la posizione rispetto a . Se si specifica un null valore come argomento, il GetPosition metodo restituisce un Point? oggetto che definisce la posizione del movimento di tocco all'interno della finestra.