SuperAPI AI 工具集

maui-gestures

智能体与模型

查看项目

更新于 10-15 20:34

技能介绍

用途:为 .NET MAUI 应用实现手势识别器提供指导,涵盖点按(tap)、轻扫(swipe)、平移(pan)、捏合(pinch)、拖放(drag-and-drop)和指针(pointer)手势,适用于 XAML 与 C# 两种写法。

版本注意:.NET 10 中 ClickGestureRecognizer 已弃用,应改用 TapGestureRecognizer(触控/触笔)和 PointerGestureRecognizer(鼠标悬停/按下)。

常见错误:

  1. 每个方向需单独一个 SwipeGestureRecognizer,单个识别器只能处理一个方向,给一个识别器添加多个方向在多数平台会静默失败。
  2. 放置目标需显式设置 AllowDrop="True",其默认值为 false,否则 Drop 不会触发。
  3. 悬停效果不要用 TapGestureRecognizer,它不跟踪指针移动,应使用 PointerGestureRecognizer(同时可启用 PointerOver 视觉状态)。

平台差异:

  • Pan 增量坐标:iOS / Mac Catalyst 与 Windows 的 TotalX/TotalY 相对手势起点;Android 相对上一个事件(非起点)。需要亚像素精度时应手动累加 Android 增量,而非直接使用 TotalX/TotalY。
  • 指针悬停仅限鼠标/触控板;在触控设备上 PointerGestureRecognizer 事件在按下/释放时触发,但不跟踪触摸间的悬停,不要依赖 PointerMoved 做触控 UI。
  • 跨应用拖放:iPadOS / Mac Catalyst 与 Windows 支持,Android 不支持。
  • 次要按钮(右键):iOS / Mac Catalyst 与 Windows 可用 Buttons = ButtonsMask.Secondary;Android 回退为长按,没有真正的右键。

手势组合冲突:同一视图上组合 pan + swipe 在 Android 会冲突,swipe 可能在 pan 开始前就消费掉手势,需在各平台测试或一次只用一种;tap + pan 组合则表现良好,快速点按触发 tap,持续拖动触发 pan。

MVVM 最佳实践:优先使用 Command 而非事件,二者运行时行为一致,但 Command 更易 mock 与测试。

快速规则:每个方向一个 SwipeGestureRecognizer;悬停用 PointerGestureRecognizer;放置目标加 AllowDrop="True";Android 上归一化 pan 增量;优先 Command;.NET 10 用 TapGestureRecognizer 替代 ClickGestureRecognizer;不要依赖 PointerMoved 做触控 UI。