GestureDetector 手势检测拓展：旋转、缩放和滑动手势检测，自定义手势识别、多点触控

• GestureDetector 手势检测拓展
  • 基本用法
  • 示例
• RotationDetector 旋转检测
  • 属性
  • 事件
  • 方法
• ScaleDetector 缩放检测
  • 属性
  • 事件
  • 方法
• SwipeDetector 滑动检测
  • 属性
  • 事件
  • 方法
• CustomGestureDetector 自定义手势检测
  • 使用流程
  • 属性
  • 事件
  • 方法
• MultiTouch 多点触控
  • 属性
  • 事件
  • 方法
  • 多检测器共存
  • 焦点坐标
  • 角度阈值
  • 滑动阈值
  • 注意事项

« 返回首页

GestureDetector 手势检测拓展

提供完整的手势检测功能，包含五个组件：

• RotationDetector：检测双指旋转手势，返回旋转角度（绑定到 Canvas）
• ScaleDetector：检测双指缩放/捏合手势，返回缩放比例（绑定到 Canvas）
• SwipeDetector：检测滑动、单击、双击和长按手势（绑定到任意可视组件）
• CustomGestureDetector：自定义手势识别，录制手势后可识别相同手势（绑定到 Canvas）
• MultiTouch：多点触控追踪，追踪所有触摸点位置和数量（绑定到 Canvas）

适用于图片查看器、地图缩放、游戏控制等需要手势交互的场景。

• .aix 拓展下载：

cn.fun123.GestureDetector.aix

基本用法

旋转/缩放（绑定到 Canvas）：

1. 在设计器中拖入 Canvas 画布组件
2. 拖入 RotationDetector 或 ScaleDetector 组件
3. 在 Screen.Initialize 中调用 AddHandlerToCanvas(Canvas1) 绑定

滑动/点击（绑定到任意可视组件）：

1. 拖入 SwipeDetector 组件
2. 在 Screen.Initialize 中调用 AddHandler(组件) 绑定到任意可视组件

自定义手势（绑定到 Canvas）：

1. 拖入 CustomGestureDetector 和 Canvas 组件
2. 在 Screen.Initialize 中调用 AddHandlerToCanvas(Canvas1) 绑定
3. 调用 StartRecording("圆形") → 在 Canvas 上画圆 → 自动录制
4. 调用 EnableDetection() → 之后画圆会触发 GestureDetected 事件

多点触控（绑定到 Canvas）：

1. 拖入 MultiTouch 和 Canvas 组件
2. 在 Screen.Initialize 中调用 AddHandlerToCanvas(Canvas1) 绑定

示例

待完善。

RotationDetector 旋转检测

检测双指旋转手势，返回旋转角度（度）。正值为顺时针，负值为逆时针。

属性

Enabled

是否启用旋转检测，默认 true

Threshold

旋转角度阈值（度），小于此值的角度变化将被忽略。默认 0.5 度。值越小越灵敏。

MyCanvas

当前绑定的 Canvas 组件（只读）

事件

RotateBegin()

双指触摸开始旋转时触发

Rotate(angle)

检测到旋转角度变化时触发。angle 为本次角度变化（度），正值=顺时针，负值=逆时针。仅当角度变化超过 Threshold 时触发。

RotateEnd()

双指旋转结束（手指抬起或只剩一指）时触发

方法

AddHandlerToCanvas(canvas)

将旋转检测器绑定到指定 Canvas。重复绑定会自动解绑之前的 Canvas。

RemoveHandlerFromCanvas()

从当前 Canvas 移除旋转检测器

ScaleDetector 缩放检测

检测双指缩放/捏合手势，返回缩放比例因子。大于1表示放大（手指张开），小于1表示缩小（手指捏合）。

属性

Enabled

是否启用缩放检测，默认 true

FocusX

缩放焦点 X 坐标（只读）

FocusY

缩放焦点 Y 坐标（只读）

ScaleFactor

最近一次缩放的比例因子（只读）

MyCanvas

当前绑定的 Canvas 组件（只读）

事件

ScaleBegin()

双指缩放开始时触发

Scale(scaleFactor)

检测到缩放变化时触发。scaleFactor 为缩放比例因子，>1 表示放大，<1 表示缩小。

ScaleEnd()

双指缩放结束时触发

方法

AddHandlerToCanvas(canvas)

将缩放检测器绑定到指定 Canvas。重复绑定会自动解绑之前的 Canvas。

RemoveHandlerFromCanvas()

从当前 Canvas 移除缩放检测器

SwipeDetector 滑动检测

检测单指滑动和点击手势，可绑定到任意可视组件（不限于 Canvas）。

属性

Enabled

是否启用手势检测，默认 true

SwipeThreshold

滑动距离阈值（像素），滑动距离超过此值才触发滑动事件。默认 100。

SwipeVelocityThreshold

滑动速度阈值（像素/秒），滑动速度超过此值才触发滑动事件。默认 100。

MyView

当前绑定的可视组件（只读）

事件

SwipeLeft()

检测到向左滑动时触发

SwipeRight()

检测到向右滑动时触发

SwipeUp()

检测到向上滑动时触发

SwipeDown()

检测到向下滑动时触发

Click()

检测到单击时触发

DoubleClick()

检测到双击时触发

LongClick()

检测到长按时触发

方法

AddHandler(view)

将手势检测器绑定到指定可视组件。支持任意可视组件（如 VerticalArrangement、HorizontalArrangement、Image 等）。重复绑定会自动解绑之前的组件。

RemoveHandler()

从当前组件移除手势检测器

CustomGestureDetector 自定义手势检测

自定义手势识别。用户在画布上录制手势（如圆形、三角形、对勾等），之后可识别相同手势。

使用流程

1. 绑定 Canvas：AddHandlerToCanvas(Canvas1)
2. 录制手势：StartRecording("circle") → 在 Canvas 上画圆 → 手指抬起自动保存
3. 开启识别：EnableDetection()
4. 再画圆 → 触发 GestureDetected("circle", 分数)

也可以通过 LoadGestureFile / SaveGestureFile 导入导出手势库。

属性

Enabled

是否启用自定义手势检测，默认 true

MinimumScore

识别最低分数阈值。分数越高要求越严格，建议 1.0~5.0，默认 2.0

IsRecording

是否正在录制手势（只读）

DetectionEnabled

识别模式是否开启（只读）

MyCanvas

当前绑定的 Canvas 组件（只读）

事件

GestureDetected(name, score)

识别到手势时触发。name 为手势名称，score 为匹配分数（越高越相似）

GestureRecorded(name)

手势录制完成时触发

方法

AddHandlerToCanvas(canvas)

将检测器绑定到指定 Canvas

RemoveHandlerFromCanvas()

从 Canvas 移除检测器

StartRecording(name)

开始录制手势。在 Canvas 上画完后手指抬起自动保存

StopRecording()

停止录制并保存手势（通常不需要手动调用，手指抬起自动保存）

CancelRecording()

取消当前录制，不保存

LoadGestureFile(path)

从文件加载手势库，与现有手势合并

SaveGestureFile(path)

保存手势库到指定文件路径

GetGestureNames()

返回手势库中所有手势名称列表

DeleteGesture(name)

删除指定名称的所有手势

EnableDetection()

开启识别模式。在 Canvas 上画手势会尝试匹配库中的手势

DisableDetection()

关闭识别模式。Canvas 恢复正常触摸行为

MultiTouch 多点触控

多点触控追踪。追踪所有触摸点的位置和数量，提供实时触摸数据。

属性

Enabled

是否启用多点触控检测，默认 true

PointerCount

当前活跃触摸点数量（只读）

MyCanvas

当前绑定的 Canvas 组件（只读）

事件

TouchStart(pointerCount)

第一个手指按下时触发

PointerDown(index, x, y, pointerCount)

新手指按下时触发。index 为按下手指的索引

TouchMove(pointerCount)

触摸点移动时触发。坐标通过 GetPointerX / GetPointerY 获取

PointerUp(index, x, y, pointerCount)

手指抬起时触发。pointerCount 为剩余触摸点数量

TouchEnd()

所有手指抬起时触发

方法

AddHandlerToCanvas(canvas)

将多点触控检测器绑定到指定 Canvas

RemoveHandlerFromCanvas()

从 Canvas 移除检测器

GetPointerX(index)

获取第 index 个触摸点的 X 坐标（index 从 0 开始）

GetPointerY(index)

获取第 index 个触摸点的 Y 坐标（index 从 0 开始）

GetPointerId(index)

获取第 index 个触摸点的 ID（index 从 0 开始）

多检测器共存

RotationDetector 和 ScaleDetector 可以同时绑定到同一个 Canvas，互不干扰。SwipeDetector 绑定到独立组件。

焦点坐标

ScaleDetector 的 FocusX / FocusY 表示双指缩放的中心点坐标，可用于锚点缩放。

角度阈值

RotationDetector 默认 Threshold = 0.5 度，过滤手指微小的抖动。设为更小的值可提高灵敏度。

滑动阈值

SwipeDetector 的 SwipeThreshold 和 SwipeVelocityThreshold 控制滑动的灵敏度。两个条件必须同时满足（距离和速度）才触发滑动事件。降低阈值可提高灵敏度，但可能增加误触发。

注意事项

• RotationDetector、ScaleDetector、CustomGestureDetector 和 MultiTouch 仅支持 Canvas 画布组件
• SwipeDetector 支持任意可视组件，但在按钮等自带点击事件的组件上可能冲突
• Enabled 设为 false 时不会触发任何事件，但检测器仍保持绑定
• 调用 Remove 方法后需要重新绑定才能再次检测
• CustomGestureDetector 的录制和识别模式互斥，录制时不会触发识别事件