文章目录前言效果展示实现原理PanGesture 的基本概念偏移量计算代码详解状态变量手势绑定容器区域完整代码常见问题QPanGesture 和 onTouch 有什么区别Q为什么方块拖出去就回不来了Qfingers 参数有什么用写在最后前言拖拽是移动端最直觉的交互方式之一。用手指按住一个东西拖到想放的位置松手——完成。ArkUI 用PanGesture来实现拖拽手势它比想象中灵活也比想象中需要更多细节处理。今天从最基础的自由拖拽开始把 PanGesture 的用法和偏移量计算讲清楚。效果展示在一个灰色的方形区域内有一个蓝色的方块。用户可以用手指拖动这个方块方块会实时跟随手指移动。区域顶部显示当前方块的 X、Y 坐标。实现原理PanGesture 的基本概念PanGesture检测的是手指在屏幕上的滑动。它提供的核心数据是offsetX和offsetY——手指相对于拖拽起点的偏移量。关键生命周期回调触发时机说明onActionStart手指按下拖拽开始初始化拖拽onActionUpdate手指移动持续触发提供偏移量onActionEnd手指抬起拖拽结束保存最终位置偏移量计算这是拖拽实现中最容易搞混的部分。核心公式当前显示位置 上次停止位置 本次拖拽偏移量为什么需要上次停止位置因为onActionUpdate给的offsetX/Y是相对于本次拖拽起点的偏移不是相对于原点的全局偏移。每次拖拽结束后需要把当前位置记录下来作为下次拖拽的基准。代码详解状态变量StateoffsetX:number0// 当前显示的 X 偏移StateoffsetY:number0// 当前显示的 Y 偏移StatepositionX:number0// 上次拖拽结束时的 X 位置StatepositionY:number0// 上次拖拽结束时的 Y 位置四个变量的关系offsetX/Y绑定到组件的.offset()属性控制显示位置positionX/Y是记忆变量记录上次拖拽结束时的位置手势绑定Column(){Text(拖拽我).fontSize(16).fontColor(#FFFFFF)}.width(80).height(80).backgroundColor(#4D96FF).borderRadius(16).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center).offset({x:this.offsetX,y:this.offsetY}).gesture(PanGesture({fingers:1,direction:PanDirection.All}).onActionStart((){}).onActionUpdate((event:GestureEvent){this.offsetXthis.positionXevent.offsetXthis.offsetYthis.positionYevent.offsetY}).onActionEnd((){this.positionXthis.offsetXthis.positionYthis.offsetY}))拆解一下关键逻辑PanGesture({ fingers: 1, direction: PanDirection.All })— 单指拖拽允许所有方向onActionUpdate— 手指移动时计算新的偏移上次位置 当前偏移onActionEnd— 手指抬起时把当前偏移保存到positionX/Y容器区域Stack(){// 可拖拽的方块放在这里}.width(100%).height(200).backgroundColor(#F8F8F8).borderRadius(12).margin({top:8})用Stack做容器方块在里面自由定位。Stack的子组件默认从中心开始偏移所以初始位置就是容器中心。完整代码EntryComponentstruct PanGestureDrag{StateoffsetX:number0StateoffsetY:number0StatepositionX:number0StatepositionY:number0build(){Column(){Column(){Text(拖拽基础).fontSize(16).fontWeight(FontWeight.Bold).margin({bottom:16})Row(){Text(X:${Math.floor(this.positionX)}).fontSize(13).fontColor(#333333)Text().layoutWeight(1)Text(Y:${Math.floor(this.positionY)}).fontSize(13).fontColor(#333333)}.width(100%).margin({bottom:12})Stack(){Column(){Text(拖拽我).fontSize(16).fontColor(#FFFFFF)}.width(80).height(80).backgroundColor(#4D96FF).borderRadius(16).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center).offset({x:this.offsetX,y:this.offsetY}).gesture(PanGesture({fingers:1,direction:PanDirection.All}).onActionStart((){}).onActionUpdate((event:GestureEvent){this.offsetXthis.positionXevent.offsetXthis.offsetYthis.positionYevent.offsetY}).onActionEnd((){this.positionXthis.offsetXthis.positionYthis.offsetY}))}.width(100%).height(200).backgroundColor(#F8F8F8).borderRadius(12).margin({top:8})Text(在灰色区域内拖拽方块).fontSize(12).fontColor(#999999).margin({top:12})}.width(100%).padding(24).backgroundColor(#FFFFFF).borderRadius(12)}.width(100%).height(100%).backgroundColor(#F5F6FA).padding(16)}}常见问题QPanGesture 和 onTouch 有什么区别onTouch是底层触摸事件能获取到每个触摸点的坐标。PanGesture是高级手势识别器它帮你识别拖拽这个动作并提供偏移量。PanGesture用起来更简单但定制性不如onTouch。Q为什么方块拖出去就回不来了方块用的是.offset()定位偏移量可以无限累加。如果拖出容器区域不会自动限制。下一篇文章会讲边界限制的实现方法。Qfingers 参数有什么用fingers指定触发拖拽需要几根手指。fingers: 1就是单指拖拽fingers: 2需要两根手指同时按住才能拖。大多数场景用 1 就行。写在最后PanGesture的拖拽实现核心就三行代码update里累加偏移、end里保存位置、用.offset()设置显示位置。理解了上次位置 当前偏移这个公式你就能实现各种拖拽效果。