识别点击手势

项目
05/14/2024

.NET Multi-platform App UI (.NET MAUI) 点击手势识别器用于检测点击操作，它是使用 TapGestureRecognizer 类实现的。此类定义了以下属性：

Buttons，类型为 ButtonsMask，用于定义是由鼠标的主要按钮还是辅助按钮触发 Android、Mac Catalyst 和 Windows 上的手势识别，或是两者都可触发。有关详细信息，请参阅定义按钮掩码。
Command，类型为 ICommand，在第一次识别点击时执行。
CommandParameter，类型为 object，是传递给 Command 的参数。
NumberOfTapsRequired，类型为 int，表示识别点击手势时所需达到的点击次数。此属性的默认值为 1。

这些属性由 BindableProperty 对象提供支持；也就是说，它们可以作为数据绑定的目标，并能进行样式设置。

TapGestureRecognizer 类还可定义识别点击时引发的 Tapped 事件。 Tapped 事件附带的 TappedEventArgs 对象定义了类型为 object 的 Parameter 属性，该属性指示 CommandParameter 属性传递的值（如果已定义）。 TappedEventArgs 对象还会定义 Buttons 属性和 GetPosition 方法。 Buttons 属性的类型为 ButtonsMask，可用于确定是由鼠标主按钮还是鼠标辅助按钮触发 Android、Mac Catalyst 和 Windows 上的手势识别器。 GetPosition 方法会返回一个 Point? 对象，该对象表示检测到点击手势的位置。有关按钮掩码的详细信息，请参阅定义按钮掩码。有关 GetPosition 方法的详细信息，请参阅获取手势位置。

警告

TapGestureRecognizer 无法在 Windows 上识别双击以上次数的点击。

创建 TapGestureRecognizer

要使 View 识别点击手势，请创建一个 TapGestureRecognizer 对象，处理 Tapped 事件，并将新的手势识别器添加到视图上的 GestureRecognizers 集合中。下面的代码示例展示了附加到 Image 上的 TapGestureRecognizer：

<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 属性设置为大于 1 时，只有在设定的时间段内进行点击时才会执行事件处理程序。如果在该时间段内没有发生第二次（或后续）点击，系统会有效地进行忽略。

定义按钮掩码

TapGestureRecognizer 对象具有一个 ButtonsMask 类型的 Buttons 属性，用于定义鼠标主按钮还是鼠标辅助按钮触发 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 上，将 Buttons 属性设置为 Secondary 的 TapGestureRecognizer 在 NumberOfTapsRequired 属性大于 1 时不会遵循该属性。

此外，可以定义 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

定义按钮掩码

获取手势位置

其他资源