辨識點選手勢

發行項
05/14/2024

.NET 多平臺應用程式 UI （.NET MAUI）點選手勢辨識器用於點選偵測，並使用類別實作 TapGestureRecognizer 。這個類別會定義下列屬性：

Buttons類型 ButtonsMask為的，定義主要或次要滑鼠按鈕，或兩者都會在Android、Mac Catalyst和 Windows 上觸發手勢。如需詳細資訊，請參閱定義按鈕遮罩。
Command類型 ICommand為的，會在辨識點選時執行。
CommandParameter，屬於 object 類型，這是傳遞至 Command 的參數。
NumberOfTapsRequired，屬於類型 int，代表辨識點選手勢所需的點選數目。這個屬性的預設值為 1。

這些屬性是由 BindableProperty 物件所支援，這表示這些屬性可以是數據系結的目標，並設定樣式。

類別 TapGestureRecognizer 也會定義 Tapped 在辨識點選時引發的事件。事件 TappedEventArgs 隨附 Tapped 的物件會 Parameter 定義型 object 別的屬性，如果已定義，表示屬性所 CommandParameter 傳遞的值。物件 TappedEventArgs 也會定義 Buttons 屬性和 GetPosition 方法。 Buttons屬性的類型ButtonsMask為，可用來判斷主要或次要滑鼠按鈕是否在Android、Mac Catalyst和 Windows 上觸發手勢辨識器。方法 GetPosition 會 Point? 傳回物件，代表偵測到點選手勢的位置。如需按鈕遮罩的詳細資訊，請參閱定義按鈕遮罩。如需方法的詳細資訊 GetPosition ，請參閱取得手勢位置。

警告

TapGestureRecognizer無法辨識多次點選 Windows。

建立 TapGestureRecognizer

若要讓 View 辨識點選手勢，請建立 TapGestureRecognizer 對象、處理 Tapped 事件，並將新的手勢辨識器新增至 GestureRecognizers 檢視上的集合。下列程式代碼範例顯示 TapGestureRecognizer 附加至 Image的：

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

事件處理程式的程式 OnTapGestureRecognizerTapped 代碼應該新增至程式代碼後置檔案：

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

對等的 C# 程式碼為：

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

根據預設， Image 會回應單一點選。 NumberOfTapsRequired當屬性設定為大於一時，只有在點選發生在一段設定的時間內時，才會執行事件處理程式。如果第二次（或後續）點選未在該期間內發生，則會有效地忽略它們。

定義按鈕遮罩

TapGestureRecognizer物件具有 Buttons 類型的 ButtonsMask屬性，定義主要或次要滑鼠按鈕，或兩者都會觸發 Android、Mac Catalyst 和 Windows 上的手勢。 ButtonsMask 列舉會定義下列成員：

Primary 代表主要滑鼠按鈕，通常是滑鼠左鍵。
Secondary 表示次要滑鼠按鈕，通常是滑鼠右鍵。

下列範例顯示 TapGestureRecognizer 使用次要滑鼠按鈕偵測點選的：

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

事件的事件處理程式 Tapped 可以判斷觸發手勢的按鈕：

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

對等的 C# 程式碼為：

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

警告

在 Windows 上，TapGestureRecognizer當屬性大於一時，將屬性Secondary設定Buttons為不會遵守 NumberOfTapsRequired 屬性。

此外， TapGestureRecognizer 也可以定義，讓主要或次要滑鼠按鈕觸發手勢：

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

對等的 C# 程式碼為：

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

取得手勢位置

在物件上TappedEventArgs呼叫 GetPosition 方法，即可取得點選手勢的位置。方法 GetPosition 會接受 Element? 自變數，並傳回作為 Point? 物件的位置：

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

自 Element? 變數會定義應該相對於取得位置的專案。 null提供值做為這個自變數，表示GetPosition方法會傳回Point?物件，該物件會定義點選手勢在視窗內的位置。

共用方式為

辨識點選手勢

建立 TapGestureRecognizer

定義按鈕遮罩

取得手勢位置

其他資源