← 返回多点触控组件参考 · 全部使用指导

多点触控使用指导

• 多点触控使用指导
  • 快速上手：左右互搏
  • 手势：缩放、旋转、滑动
  • 常见问题
  • 搭建与测试
  • 案例：暂停手势识别
  • 属性、方法与事件速查
  • 常见问题与验收
  • 完整 .aia 源码与操作指导
    • 多点触控

不可见组件：同时追踪最多 10 个触摸点——每个手指按下、移动、松开都触发事件，并带上「触摸点序号」和坐标； 同时识别常用手势：滑动（上下左右）、双击、长按、双指缩放、双指旋转。 可用于画布（左右互搏、双人对战、多指绘画、缩放旋转图片）、按钮（多个按钮同时按住做游戏手柄、按按下位置分区控制）、 图像和布局等可见组件。

触摸点序号从 1 开始：按下时分配当前最小的空闲序号，松开时回收，按住移动期间不变。 例如依次按下左手食指、右手食指、右手中指，序号分别是 1、2、3；松开右手食指后 2 号被回收， 此时再按下一个手指，它得到的序号仍是 2。用序号就能分清「哪根手指在动」。 坐标与画布「被按压」「被拖动」等事件同一单位，相对组件左上角。

注册到画布或按钮后，它们自己的触摸事件（被按压、被拖动、被点击等）照常触发，互不影响。 由原 GestureDetector 拓展的多点触控、滑动、缩放、旋转四个组件合并内化而来，一次注册全部可用。

快速上手：左右互搏

「左手画方、右手画圆」——左半边画红线、右半边画蓝线，两只手同时画；双击清空画布。

1. 拖一个画布（宽、高都设为充满）和一个多点触控到屏幕，屏幕方向建议锁定横屏；
2. 搭下面的代码块：按下时按位置给这根手指记一个颜色，移动时用它的颜色画线。

各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。

global 笔色 = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

when Screen1.Initialize() {
  多点触控1.Register(画布1)
  画布1.LineWidth = 12
}

when 多点触控1.TouchDown(组件, 触摸点序号, x坐标, y坐标) {
  if x坐标 < 画布1.Width / 2 {
    笔色[触摸点序号] = &HFFE53935
  } else {
    笔色[触摸点序号] = &HFF1E88E5
  }
}

when 多点触控1.TouchMoving(组件, 触摸点序号, 起点X坐标, 起点Y坐标, 前点X坐标, 前点Y坐标, 当前X坐标, 当前Y坐标) {
  画布1.PaintColor = 笔色[触摸点序号]
  画布1.DrawLine(前点X坐标, 前点Y坐标, 当前X坐标, 当前Y坐标)
  画布1.DrawCircle(当前X坐标, 当前Y坐标, 6, true)
}

when 多点触控1.DoubleTapped(组件, x坐标, y坐标) {
  画布1.Clear()
}

运行后两只手同时在左右两边画，左边的线是红色、右边是蓝色，互不串色；双击画布清空。 画完线再画一个小圆，是为了把粗线转折处的缝隙填平。

手势：缩放、旋转、滑动

在画布上放一个图像精灵（勾选「旋转」），双指捏合缩放、双指转动旋转；单指快速滑动在标签上显示方向：

global 基准宽 = 100
global 基准高 = 100
global 基准角 = 0

when 多点触控1.TouchDown(组件, 触摸点序号, x坐标, y坐标) {
  if 多点触控1.PointerCount(画布1) == 2 {
    基准宽 = 图像精灵1.Width
    基准高 = 图像精灵1.Height
    基准角 = 图像精灵1.Heading
  }
}

when 多点触控1.Pinched(组件, 缩放倍数, 中心X坐标, 中心Y坐标) {
  图像精灵1.Width = 基准宽 * 缩放倍数
  图像精灵1.Height = 基准高 * 缩放倍数
}

when 多点触控1.Rotated(组件, 角度) {
  图像精灵1.Heading = 基准角 - 角度
}

when 多点触控1.Swiped(组件, 方向) {
  标签1.Text = join("滑动方向：", 方向)
}

缩放倍数、旋转角度都相对「第二根手指按下时」计算，所以在按下第二根手指时记下原尺寸、原角度，之后直接乘、加即可。 图像精灵的方向是逆时针为正，而旋转角度是顺时针为正，所以用减法。

常见问题

搭建与测试

在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。

可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。

案例：暂停手势识别

准备一个有尺寸的垂直布局、标签和开关按钮，Register 后监听布局上的触摸手势。

when Screen1.Initialize() {
  多点触控1.Register(垂直布局1)
}
when 按钮_暂停.Click() {
  多点触控1.Enabled = false
}
when 按钮_恢复.Click() {
  多点触控1.Enabled = true
}
when 多点触控1.LongPressed(组件, x坐标, y坐标) {
  标签1.Text = join("长按位置：", x坐标, ",", y坐标)
}

注册对象要有可触摸的尺寸；滚动组件可能争抢触摸事件。不同事件中的 pointerId 是触摸点编号，不是第几根手指的固定序号。

属性、方法与事件速查

完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。

常见问题与验收

完整 .aia 源码与操作指导

下载 .aia 源码

需要支持多点触控的真实设备。蓝色区域是手势目标；请在该区域操作，下方滚动用于查看控制项。缩放和旋转显示真实手势数据，不自动缩放界面。手指编号以事件返回值为准。

导入 MultiTouchAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

多点触控

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 需要支持多点触控的真实设备。蓝色区域是手势目标；请在该区域操作，下方滚动用于查看控制项。缩放和旋转显示真实手势数据，不自动缩放界面。手指编号以事件返回值为准。 覆盖检查 15/15。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。