maui-gestures

.NET MAUI 手势识别器

弃用 API 警告

⚠️ 在 .NET 10 中，ClickGestureRecognizer 已弃用。请改用 TapGestureRecognizer（触摸／触控笔）和 PointerGestureRecognizer （鼠标悬停／按下）。

---

常见错误

每个方向使用一个 SwipeGestureRecognizer

单个识别器只能处理一个方向。向一个识别器添加多个方向，在大多数平台上都会静默失败。

<SwipeGestureRecognizer Direction="Left,Right" Swiped="OnSwiped" />


<SwipeGestureRecognizer Direction="Left" Swiped="OnSwiped" />
<SwipeGestureRecognizer Direction="Right" Swiped="OnSwiped" />

AllowDrop 默认为 false

如果忘记设置此属性，放置目标会静默忽略放置操作。

<StackLayout>
  <StackLayout.GestureRecognizers>
    <DropGestureRecognizer Drop="OnDrop" />
  </StackLayout.GestureRecognizers>
</StackLayout>


<StackLayout>
  <StackLayout.GestureRecognizers>
    <DropGestureRecognizer AllowDrop="True" Drop="OnDrop" />
  </StackLayout.GestureRecognizers>
</StackLayout>

使用 TapGestureRecognizer 实现悬停效果

点击识别器不会跟踪指针移动。请使用 PointerGestureRecognizer 实现悬停效果——它还会启用 PointerOver 视觉状态。

<Border>
  <Border.GestureRecognizers>
    <TapGestureRecognizer Command="{Binding HoverCommand}" />
  </Border.GestureRecognizers>
</Border>


<Border>
  <Border.GestureRecognizers>
    <PointerGestureRecognizer PointerEnteredCommand="{Binding HoverInCommand}"
                              PointerExitedCommand="{Binding HoverOutCommand}" />
  </Border.GestureRecognizers>
</Border>

---

容易踩坑的平台差异

平移增量坐标因平台而异

平台	TotalX / TotalY 的相对基准
iOS / Mac Catalyst	手势起点
Android	上一个事件（而非起点！）
Windows	手势起点

如果需要亚像素级精度，请手动累加 Android 的增量进行归一化，而不要直接使用 TotalX/TotalY。

指针悬停仅适用于鼠标／触控板

在触摸设备上，PointerGestureRecognizer 事件会在按下／释放时触发，但不会跟踪触摸之间的悬停。请勿在触摸界面中依赖 PointerMoved。

跨应用拖放

平台	是否支持
iPadOS / Mac Catalyst	✅ 是
Windows	✅ 是
Android	❌ 否

辅助按钮（右键单击）

平台	行为
iOS / Mac Catalyst	Buttons = ButtonsMask.Secondary 可用
Windows	Buttons = ButtonsMask.Secondary 可用
Android	会回退为长按——不支持真正的右键单击

---

手势组合冲突

在同一视图上组合平移和滑动手势会在 Android 上产生冲突——滑动手势可能会在平移手势启动前消耗该手势。请在所有平台上进行测试，或一次只使用一种手势。

组合点击和平移效果良好——快速点击时触发点击，持续拖动时触发平移。

---

MVVM 最佳实践

优先使用命令而非事件，以便测试视图模型。两者在运行时的行为相同，但命令更容易模拟和测试。

<TapGestureRecognizer Command="{Binding TapCommand}" />


<TapGestureRecognizer Tapped="OnTapped" />

---

快速规则

1. 每个方向使用一个 SwipeGestureRecognizer
2. 悬停使用 PointerGestureRecognizer，不要使用 TapGestureRecognizer
3. 在放置目标上设置 AllowDrop="True"——其默认值为 false
4. 在 Android 上归一化平移增量（相对于上一个事件，而非起点）
5. MVVM 优先使用命令而非事件
6. 使用 TapGestureRecognizer 替代已弃用的 ClickGestureRecognizer（.NET 10）
7. 不要在触摸界面中依赖 PointerMoved——它不会跟踪悬停