用 onTouch 实现鸿蒙丝滑无抖动的悬浮球

在鸿蒙（HarmonyOS）应用开发中，悬浮工具球是一个常见的功能。但很多开发者在实现时会遇到一个痛点：使用常规的手势框架（Gesture）拖拽时，悬浮球容易出现延迟、跳变或抖动。

一、 核心技术选型与避坑

要实现丝滑的拖拽，关键在于底层技术的正确选型。相比于普通的手势框架，直接使用 onTouch 原始事件可以直接获取屏幕的绝对坐标，自由控制增量移动，从而避开手势框架内部逻辑带来的“坑”。

同时，悬浮球的 UI 必须依托于子窗口（SubWindow）。子窗口独立于主窗口运行，始终保持在最上层，且不受主页面滚动的影响。在位置维护上，拖拽过程中应只操作本地变量（px），避免频繁查询异步的窗口属性，这是彻底消除抖动的核心秘诀。

二、 架构解耦与生命周期管理

为了保证代码的整洁，悬浮球的逻辑应与主页面完全解耦。整体架构可以分为三层：

1. 入口层：在 EntryAbility 中存储 windowStage，并在 onWindowStageDestroy 时负责悬浮球的销毁。
2. 管理层：封装 FloatWindowManager 单例类，负责创建、移动和销毁子窗口。在调用 moveTo 时不等待异步结果，避免阻塞手势回调。
3. 视图层：创建 FloatBallPage.ets 作为子窗口的 UI 载体，使用 @ComponentV2 进行状态管理，并将所有的拖拽逻辑封装在此组件内部。

三、 关键实现细节

在具体编码时，有几个细节决定了最终的交互体验：

• 单位转换：鸿蒙的 display 获取的屏幕宽高通常是 vp（虚拟像素），而 onTouch 事件返回的坐标是 px（物理像素）。必须使用 vp2px 进行单位转换，才能确保悬浮球在拖拽时与手指精准对齐。
• 拖拽与点击分离：为了避免在拖拽结束时误触展开菜单，需要在 onTouch 的 DOWN、MOVE 和 UP 事件中记录滑动距离。只有当移动距离小于阈值时，才判定为单击并触发展开/收起工具栏。
• 智能吸边与防溢出：在手指抬起（UP）时，根据悬浮球当前的 X 轴坐标，自动计算并吸附到屏幕左边缘或右边缘（保留 20vp 边距），同时吸附到底部（保留 100vp 边距）。此外，若悬浮球过于靠右，展开横向工具栏时应自动向左偏移，防止 UI 溢出屏幕边界。

通过这套基于 onTouch 和子窗口的轻量级方案，可以轻松绕过复杂的框架限制，用最底层的控制力打造出体验极佳的悬浮球组件。