通过

识别点击手势

.NET 多平台应用 UI （.NET MAUI） 点击手势识别器用于点击检测，并使用类实现 TapGestureRecognizer 。

重要

在 .NET 10 中， ClickGestureRecognizer 已弃用。 用于 TapGestureRecognizer 点击/单击交互，以及 PointerGestureRecognizer 指针悬停/移动/按方案。 支持 TapGestureRecognizer 通过 Buttons 属性和辅助按钮，可用于处理单次点击手势和双击手势。

此类定义以下属性：

  • 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当属性设置为大于 1 时，仅当点击发生在一定时间段内时，才会执行事件处理程序。 如果第二次（或后续）点击在该时间段内未发生，则实际上将被忽略。

从 ClickGestureRecognizer 迁移（>= .NET 10）

在以前的版本中，可以处理 ClickGestureRecognizer鼠标单击交互。 在 .NET 10 中，此识别器已弃用。 TapGestureRecognizer迁移到单击/点击交互，并用于PointerGestureRecognizer指针进入/退出/移动/按/发布方案。

以下示例演示如何在维护对主要/辅助按钮的支持的同时从 ClickGestureRecognizer 其迁移 TapGestureRecognizer ：

<!-- Before (.NET 9 and earlier) -->
<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <ClickGestureRecognizer Clicked="OnClicked"
                                                        NumberOfClicksRequired="1"
                                                        Buttons="Primary,Secondary" />
    </Image.GestureRecognizers>
</Image>

<!-- After (.NET 10) -->
<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <TapGestureRecognizer Tapped="OnTapped"
                                                    NumberOfTapsRequired="1"
                                                    Buttons="Primary,Secondary" />
    </Image.GestureRecognizers>
</Image>

在代码隐藏中 Tapped ，处理事件并检查 Buttons 以区分鼠标按钮：

void OnTapped(object sender, TappedEventArgs e)
{
        if (e.Buttons == ButtonsMask.Secondary)
        {
                // Handle secondary/right click
        }
        else
        {
                // Handle primary/left click
        }
}

如果需要指针悬停或按下/释放详细信息（未完成点击），请使用PointerGestureRecognizer及其事件，例如PointerEntered，PointerMoved和PointerPressedPointerReleased。 有关详细信息，请参阅 “识别指针手势”。

定义按钮掩码

对象 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在属性大于 1 时不尊重NumberOfTapsRequired该属性。

此外，可以定义 a TapGestureRecognizer ，以便主要或辅助鼠标按钮触发手势：

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

等效的 C# 代码为：

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

获取手势位置

可以通过对对象调用 GetPosition 方法 TappedEventArgs 来获取点击手势的位置。 该方法 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? 对象，该对象定义点击手势在窗口内的位置。

  • Last updated on