在 ArkUI 中PanGesture滑动/拖拽和PinchGesture捏合缩放是实现复杂交互的核心手势。它们的坐标计算逻辑各有特点。一、 PanGesture 滑动坐标计算PanGesture的核心在于增量叠加。在onActionUpdate回调中系统提供的是相对于手势起始点的偏移量event.offsetX/event.offsetY单位为 vp。核心计算逻辑记录初始状态在onActionStart或首次触发时记录组件当前的绝对位置positionX,positionY。实时叠加偏移在onActionUpdate中将当前偏移量与初始位置相加得到组件的新位置。更新基准位置在onActionEnd中将组件最终的位置保存为下一次滑动的初始位置。实战代码Entry Component struct PanGestureDemo { State offsetX: number 0; State offsetY: number 0; // 记录手指按下时组件的绝对位置 State positionX: number 0; State positionY: number 0; build() { Column() { Text(拖拽我) .width(100) .height(100) .backgroundColor(#4A90E2) .borderRadius(10) .translate({ x: this.offsetX, y: this.offsetY }) // 使用 translate 移动组件 .gesture( PanGesture() .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 【核心公式】当前位置 初始绝对位置 实时偏移量 this.offsetX this.positionX event.offsetX; this.offsetY this.positionY event.offsetY; } }) .onActionEnd(() { // 手指抬起时将当前位置保存为下一次拖拽的初始位置 this.positionX this.offsetX; this.positionY this.offsetY; }) ) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }二、 PinchGesture 缩放坐标计算PinchGesture的坐标计算比滑动复杂它不仅涉及缩放比例Scale的累积还涉及缩放中心点Center的坐标转换。1. 缩放比例Scale的累积运算event.scale是相对于本次捏合起始点的比例起始时为 1.0。为了实现连续缩放必须引入一个基准值savedScale当前总缩放 历史基准缩放 × 本次相对缩放 (event.scale)。2. 缩放中心点Center的坐标转换event.pinchCenterX/Y的单位是vp原点在组件左上角。而.scale({ centerX, centerY })属性接收的是归一化值0.0 ~ 1.0。转换公式centerX pinchCenterX / 组件宽度centerY pinchCenterY / 组件高度。实战代码Entry Component struct PinchGestureDemo { State currentScale: number 1.0; State savedScale: number 1.0; // 记录历史缩放基准 State centerX: number 0.5; State centerY: number 0.5; build() { Column() { Text(双指捏合缩放) .width(200) .height(200) .backgroundColor(#4A90E2) .borderRadius(10) // 【核心】应用缩放比例和动态中心点 .scale({ x: this.currentScale, y: this.currentScale, centerX: this.centerX, centerY: this.centerY }) .gesture( PinchGesture({ fingers: 2 }) .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 1. 累积计算缩放比例 this.currentScale this.savedScale * event.scale; // 2. 坐标转换将 vp 坐标转换为 0~1 的归一化值 // 假设组件宽高为 200 this.centerX event.pinchCenterX / 200; this.centerY event.pinchCenterY / 200; } }) .onActionEnd(() { // 捏合结束将当前比例保存为下一次的基准值 this.savedScale this.currentScale; }) ) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }三、 进阶优化建议边界限制在onActionEnd中建议对currentScale或offsetX/Y进行边界检查如限制缩放范围在 0.5 ~ 3.0 之间防止组件缩放过小或飞出屏幕。丝滑回弹动画在onActionEnd中如果检测到缩放或位移超出了边界可以使用animateTo配合Curve.Friction摩擦力曲线实现丝滑的回弹效果。性能优化高频触发的onActionUpdate中尽量避免复杂的 DOM 查询或重计算仅更新State变量让框架自动进行 UI 刷新。1、 动态缩放中心点PinchGesture 进阶在实际的图片查看器或地图应用中缩放中心点必须跟随用户的双指中心实时变化而不是固定在组件中心。核心计算逻辑获取双指中心坐标event.pinchCenterX/Y单位 vp。将 vp 坐标转换为组件内部的相对比例0.0 ~ 1.0。动态更新.scale()的centerX和centerY属性。Entry Component struct DynamicPinchDemo { State currentScale: number 1.0; State savedScale: number 1.0; State centerX: number 0.5; // 默认中心 State centerY: number 0.5; // 组件的固定尺寸实际开发中可通过 onAreaChange 动态获取 private componentSize: number 200; build() { Column() { Text(️) .fontSize(80) .width(this.componentSize) .height(this.componentSize) .backgroundColor(#E3F2FD) .borderRadius(16) // 【核心】动态绑定缩放中心点 .scale({ x: this.currentScale, y: this.currentScale, centerX: this.centerX, centerY: this.centerY }) .gesture( PinchGesture({ fingers: 2 }) .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 1. 累积缩放比例 this.currentScale Math.max(0.5, Math.min(3.0, this.savedScale * event.scale )); // 2. 动态计算并更新缩放中心vp 转归一化值 this.centerX event.pinchCenterX / this.componentSize; this.centerY event.pinchCenterY / this.componentSize; } }) .onActionEnd(() { this.savedScale this.currentScale; }) ) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }2、 实时监测多指触控信息fingerInfos在高级交互中可能需要根据参与手势的手指数量来切换行为例如单指拖拽双指缩放。PanGesture支持通过event.fingerInfos实时获取有效触点信息。State fingerCount: number 0; .gesture( PanGesture() .onActionStart((event: GestureEvent | undefined) { // 记录初始触点数量 this.fingerCount event?.fingerInfos?.length || 0; }) .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 实时更新触点数量 this.fingerCount event.fingerInfos?.length || 0; // 根据手指数量执行不同逻辑 if (this.fingerCount 1) { // 单指拖拽逻辑 } else if (this.fingerCount 2) { // 双指特殊交互逻辑 } } }) .onActionEnd(() { this.fingerCount 0; }) )3、 手势冲突解决PanGesture vs SwipeGesture在列表或 Swiper 组件中嵌套可拖拽元素时PanGesture极易与系统的滑动手势冲突。解决方案增大触发阈值通过distance参数提高 Pan 手势的触发门槛避免轻微滑动被误判为拖拽。限定滑动方向使用PanDirection限制拖拽方向与列表的滑动方向正交。.gesture( PanGesture({ direction: PanDirection.Horizontal, // 仅允许水平拖拽 distance: 10 // 滑动超过 10vp 才触发避免与垂直列表冲突 }) .onActionUpdate((event: GestureEvent | undefined) { // 拖拽逻辑 }) )4、 性能优化与丝滑体验高频的onActionUpdate回调是性能瓶颈的重灾区以下优化至关重要细粒度状态更新使用ObservedV2和Trace装饰器替代传统的State仅追踪发生变化的坐标属性减少不必要的 UI 重绘。硬件加速动画在onActionEnd中触发回弹或吸附动画时务必使用animateTo并设置较短的 duration如 200ms框架会自动启用硬件加速渲染。避免重计算在onActionUpdate中仅更新State变量严禁进行 DOM 查询、复杂数学运算或网络请求。// 丝滑回弹示例 .onActionEnd(() { this.positionX this.offsetX; this.positionY this.offsetY; // 边界检查与回弹 if (this.offsetX -100) { animateTo({ duration: 200, curve: Curve.Friction }, () { this.offsetX -100; }); } })
高级手势：PanGesture滑动、PinchGesture缩放的坐标计算（31）
在 ArkUI 中PanGesture滑动/拖拽和PinchGesture捏合缩放是实现复杂交互的核心手势。它们的坐标计算逻辑各有特点。一、 PanGesture 滑动坐标计算PanGesture的核心在于增量叠加。在onActionUpdate回调中系统提供的是相对于手势起始点的偏移量event.offsetX/event.offsetY单位为 vp。核心计算逻辑记录初始状态在onActionStart或首次触发时记录组件当前的绝对位置positionX,positionY。实时叠加偏移在onActionUpdate中将当前偏移量与初始位置相加得到组件的新位置。更新基准位置在onActionEnd中将组件最终的位置保存为下一次滑动的初始位置。实战代码Entry Component struct PanGestureDemo { State offsetX: number 0; State offsetY: number 0; // 记录手指按下时组件的绝对位置 State positionX: number 0; State positionY: number 0; build() { Column() { Text(拖拽我) .width(100) .height(100) .backgroundColor(#4A90E2) .borderRadius(10) .translate({ x: this.offsetX, y: this.offsetY }) // 使用 translate 移动组件 .gesture( PanGesture() .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 【核心公式】当前位置 初始绝对位置 实时偏移量 this.offsetX this.positionX event.offsetX; this.offsetY this.positionY event.offsetY; } }) .onActionEnd(() { // 手指抬起时将当前位置保存为下一次拖拽的初始位置 this.positionX this.offsetX; this.positionY this.offsetY; }) ) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }二、 PinchGesture 缩放坐标计算PinchGesture的坐标计算比滑动复杂它不仅涉及缩放比例Scale的累积还涉及缩放中心点Center的坐标转换。1. 缩放比例Scale的累积运算event.scale是相对于本次捏合起始点的比例起始时为 1.0。为了实现连续缩放必须引入一个基准值savedScale当前总缩放 历史基准缩放 × 本次相对缩放 (event.scale)。2. 缩放中心点Center的坐标转换event.pinchCenterX/Y的单位是vp原点在组件左上角。而.scale({ centerX, centerY })属性接收的是归一化值0.0 ~ 1.0。转换公式centerX pinchCenterX / 组件宽度centerY pinchCenterY / 组件高度。实战代码Entry Component struct PinchGestureDemo { State currentScale: number 1.0; State savedScale: number 1.0; // 记录历史缩放基准 State centerX: number 0.5; State centerY: number 0.5; build() { Column() { Text(双指捏合缩放) .width(200) .height(200) .backgroundColor(#4A90E2) .borderRadius(10) // 【核心】应用缩放比例和动态中心点 .scale({ x: this.currentScale, y: this.currentScale, centerX: this.centerX, centerY: this.centerY }) .gesture( PinchGesture({ fingers: 2 }) .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 1. 累积计算缩放比例 this.currentScale this.savedScale * event.scale; // 2. 坐标转换将 vp 坐标转换为 0~1 的归一化值 // 假设组件宽高为 200 this.centerX event.pinchCenterX / 200; this.centerY event.pinchCenterY / 200; } }) .onActionEnd(() { // 捏合结束将当前比例保存为下一次的基准值 this.savedScale this.currentScale; }) ) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }三、 进阶优化建议边界限制在onActionEnd中建议对currentScale或offsetX/Y进行边界检查如限制缩放范围在 0.5 ~ 3.0 之间防止组件缩放过小或飞出屏幕。丝滑回弹动画在onActionEnd中如果检测到缩放或位移超出了边界可以使用animateTo配合Curve.Friction摩擦力曲线实现丝滑的回弹效果。性能优化高频触发的onActionUpdate中尽量避免复杂的 DOM 查询或重计算仅更新State变量让框架自动进行 UI 刷新。1、 动态缩放中心点PinchGesture 进阶在实际的图片查看器或地图应用中缩放中心点必须跟随用户的双指中心实时变化而不是固定在组件中心。核心计算逻辑获取双指中心坐标event.pinchCenterX/Y单位 vp。将 vp 坐标转换为组件内部的相对比例0.0 ~ 1.0。动态更新.scale()的centerX和centerY属性。Entry Component struct DynamicPinchDemo { State currentScale: number 1.0; State savedScale: number 1.0; State centerX: number 0.5; // 默认中心 State centerY: number 0.5; // 组件的固定尺寸实际开发中可通过 onAreaChange 动态获取 private componentSize: number 200; build() { Column() { Text(️) .fontSize(80) .width(this.componentSize) .height(this.componentSize) .backgroundColor(#E3F2FD) .borderRadius(16) // 【核心】动态绑定缩放中心点 .scale({ x: this.currentScale, y: this.currentScale, centerX: this.centerX, centerY: this.centerY }) .gesture( PinchGesture({ fingers: 2 }) .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 1. 累积缩放比例 this.currentScale Math.max(0.5, Math.min(3.0, this.savedScale * event.scale )); // 2. 动态计算并更新缩放中心vp 转归一化值 this.centerX event.pinchCenterX / this.componentSize; this.centerY event.pinchCenterY / this.componentSize; } }) .onActionEnd(() { this.savedScale this.currentScale; }) ) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }2、 实时监测多指触控信息fingerInfos在高级交互中可能需要根据参与手势的手指数量来切换行为例如单指拖拽双指缩放。PanGesture支持通过event.fingerInfos实时获取有效触点信息。State fingerCount: number 0; .gesture( PanGesture() .onActionStart((event: GestureEvent | undefined) { // 记录初始触点数量 this.fingerCount event?.fingerInfos?.length || 0; }) .onActionUpdate((event: GestureEvent | undefined) { if (event) { // 实时更新触点数量 this.fingerCount event.fingerInfos?.length || 0; // 根据手指数量执行不同逻辑 if (this.fingerCount 1) { // 单指拖拽逻辑 } else if (this.fingerCount 2) { // 双指特殊交互逻辑 } } }) .onActionEnd(() { this.fingerCount 0; }) )3、 手势冲突解决PanGesture vs SwipeGesture在列表或 Swiper 组件中嵌套可拖拽元素时PanGesture极易与系统的滑动手势冲突。解决方案增大触发阈值通过distance参数提高 Pan 手势的触发门槛避免轻微滑动被误判为拖拽。限定滑动方向使用PanDirection限制拖拽方向与列表的滑动方向正交。.gesture( PanGesture({ direction: PanDirection.Horizontal, // 仅允许水平拖拽 distance: 10 // 滑动超过 10vp 才触发避免与垂直列表冲突 }) .onActionUpdate((event: GestureEvent | undefined) { // 拖拽逻辑 }) )4、 性能优化与丝滑体验高频的onActionUpdate回调是性能瓶颈的重灾区以下优化至关重要细粒度状态更新使用ObservedV2和Trace装饰器替代传统的State仅追踪发生变化的坐标属性减少不必要的 UI 重绘。硬件加速动画在onActionEnd中触发回弹或吸附动画时务必使用animateTo并设置较短的 duration如 200ms框架会自动启用硬件加速渲染。避免重计算在onActionUpdate中仅更新State变量严禁进行 DOM 查询、复杂数学运算或网络请求。// 丝滑回弹示例 .onActionEnd(() { this.positionX this.offsetX; this.positionY this.offsetY; // 边界检查与回弹 if (this.offsetX -100) { animateTo({ duration: 200, curve: Curve.Friction }, () { this.offsetX -100; }); } })
