@buaa_smat/hometrans 0.1.0 → 0.1.2

package/skills/hmos-ui-align-batch/references/mappings/android-to-harmonyOS-ui-interaction-mapping-reference.md

@@ -0,0 +1,555 @@
+# Android-to-HarmonyOS UI Interaction Mapping Reference
+
+<!-- TODO: Fill in the actual UI interaction mapping content -->
+<!-- This reference maps Android UI interaction patterns to HarmonyOS ArkUI equivalents -->
+<!-- Covers: onClick→.onClick(), onLongClick→LongPressGesture, swipe→SwipeGesture, TextWatcher→onChange, onScroll, Drag&Drop, animations, etc. -->
+
+
+
+
+## 一、触摸事件映射
+
+### 1.1 基础触摸事件
+
+| Android 事件 | HarmonyOS 事件 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `onTouchEvent(MotionEvent)` | `onTouch(event: TouchEvent)` | 直接映射 | Android: `view.onTouchEvent(event)`<br/>HarmonyOS: `Component().onTouch((event) => {})` |
+| `onInterceptTouchEvent(MotionEvent)` | `onTouchIntercept(event: TouchEvent)` | 直接映射 | Android: `viewGroup.onInterceptTouchEvent(event)`<br/>HarmonyOS: `Container().onTouchIntercept((event) => {})` |
+| `dispatchTouchEvent(MotionEvent)` | 事件分发机制 | 架构差异 | Android: 手动分发<br/>HarmonyOS: 自动分发 + 手势系统 |
+
+### 1.2 MotionEvent 动作映射
+
+| Android Action | HarmonyOS 触摸类型 | 映射说明 |
+|---------------|-------------------|----------|
+| `ACTION_DOWN` | `TouchType.Down` | 手指按下 |
+| `ACTION_UP` | `TouchType.Up` | 手指抬起 |
+| `ACTION_MOVE` | `TouchType.Move` | 手指移动 |
+| `ACTION_CANCEL` | `TouchType.Cancel` | 事件取消 |
+| `ACTION_POINTER_DOWN` | 多点触摸开始 | 新手指按下 |
+| `ACTION_POINTER_UP` | 多点触摸结束 | 手指抬起 |
+| `ACTION_OUTSIDE` | 触摸区域外 | 触摸在组件外 |
+
+### 1.3 触摸事件属性映射（API 20/21）
+
+| Android 属性 | HarmonyOS 属性 | 映射说明 |
+|-------------|---------------|----------|
+| `event.getX()` / `event.getY()` | `event.touches[0].x` / `event.touches[0].y` | 获取坐标 |
+| `event.getRawX()` / `event.getRawY()` | `event.touches[0].screenX` / `event.touches[0].screenY` | 获取屏幕坐标 |
+| `event.getPointerCount()` | `event.touches.length` | 触摸点数量 |
+| `event.getPointerId(index)` | `event.touches[index].id` | 触摸点 ID |
+| `event.getPressure()` | `event.touches[0].pressure` | 压力值 |
+| `event.getSize()` | `event.touches[0].toolType` | 触摸工具类型 |
+| `event.getEventTime()` | `event.timestamp` | 事件时间戳 |
+| `event.getSource()` | 无直接对应 | 输入源判断需自定义 |
+
+### 1.4 响应热区设置（API 20/21 新增）
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| `setTouchDelegate()` | `responseRegion` | 扩展响应热区 | `Component().responseRegion({ x: '10%', y: '10%', width: '80%', height: '80%' })` |
+| 无直接对应 | `responseRegion` | 热区可配置多个区域 | 支持设置一个或多个热区范围 |
+| 无直接对应 | `responseRegion` | 百分比偏移 | x/y 可设置正负值百分比 |
+
+### 1.5 触摸测试控制（API 20/21 新增）
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| `requestDisallowInterceptTouchEvent()` | `hitTestBehavior` | 阻止拦截（静态配置） | `Component().hitTestBehavior(HitTestMode.None)` |
+| `onInterceptTouchEvent()` | `onTouchIntercept()` | 事件拦截（动态回调） | `Container().onTouchIntercept((event) => { /* 返回 HitTestMode */ })` |
+| 无直接对应 | `HitTestMode.Default` | 默认：自身命中会阻塞兄弟组件 | API 7+ |
+| 无直接对应 | `HitTestMode.None` | 自身不接收事件，不阻塞 | API 7+ |
+| 无直接对应 | `HitTestMode.Block` | 阻塞子组件的触摸测试 | API 7+ |
+| 无直接对应 | `HitTestMode.Transparent` | 自身触摸测试，不阻塞 | API 7+ |
+| 无直接对应 | `HitTestMode.BLOCK_HIERARCHY`（API 20 新增）| 自身和子节点响应，阻止祖先 | API 20+ |
+| 无直接对应 | `HitTestMode.BLOCK_DESCENDANTS`（API 20 新增）| 自身不响应，后代也不响应 | API 20+ |
+
+### 1.6 事件冒泡与阻止（API 20/21 增强）
+
+| Android 机制 | HarmonyOS 机制 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| 无直接 API | `stopPropagation()` | 停止事件冒泡 | HarmonyOS: `event.stopPropagation()`（API 21+） |
+| 无直接 API | 事件冒泡机制 | 默认冒泡到父组件 | 遵循右子树优先的后序遍历 |
+| 手势和事件独立 | 手势事件冒泡不影响基础事件 | stopPropagation 只停止 Touch 事件，不影响手势 | 需要注意 |
+
+---
+
+## 二、点击事件映射
+
+### 2.1 基础点击事件
+
+| Android 事件 | HarmonyOS 事件 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `OnClickListener.onClick(View)` | `onClick(() => {})` | 直接映射 | Android: `button.setOnClickListener { }`<br/>HarmonyOS: `Button().onClick(() => {})` |
+| `OnLongClickListener.onLongClick(View)` | `onLongPress()` 手势 | 手势识别 | Android: `button.setOnLongClickListener { }`<br/>HarmonyOS: `Button().gesture(LongPressGesture().onAction(() => {}))` |
+| `OnDoubleClickListener` | `TapGesture({count: 2})` | 手势识别 | Android: 自定义实现<br/>HarmonyOS: `Component().gesture(TapGesture({count: 2}).onAction(() => {}))` |
+| `OnContextClickListener` | `BindContextMenu` | 上下文菜单 | Android: `view.setOnContextClickListener { }`<br/>HarmonyOS: `Component().bindContextMenu(this.menuBuilder)` |
+
+---
+
+## 三、手势识别映射
+
+### 3.1 点击手势
+
+| Android 手势 | HarmonyOS 手势 | 映射说明 | 参数映射 |
+|-------------|---------------|----------|---------|
+| `GestureDetector.OnSingleTapUpListener` | `TapGesture({count: 1})` | 单击 | count: 1 |
+| `GestureDetector.OnDoubleTapListener` | `TapGesture({count: 2})` | 双击 | count: 2 |
+| `GestureDetector.OnShowPressListener` | `TapGesture` + 延时 | 长按触发 | 需自定义延时 |
+| 手指按下 | `TapGesture` onAction | 动作回调 | `onAction(() => {})` |
+
+### 3.2 长按手势
+
+| Android 手势 | HarmonyOS 手势 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| `GestureDetector.OnLongPressListener` | `LongPressGesture` | 长按 | `Component().gesture(LongPressGesture().onAction(() => {}))` |
+| `onLongPress(MotionEvent)` | `LongPressGesture` onAction | 长按动作 | `onAction(() => { /* 长按触发 */ })` |
+
+### 3.3 拖动手势
+
+| Android 手势 | HarmonyOS 手势 | 映射说明 | 参数映射 |
+|-------------|---------------|----------|---------|
+| `GestureDetector.OnScrollListener` | `PanGesture` | 滑动/拖动 | direction: PanDirection |
+| `onScroll(MotionEvent e1, MotionEvent e2, float distanceX, float distanceY)` | `PanGesture` onAction | 滑动动作 | `onAction((event: GestureEvent) => { /* 处理滑动 */ })` |
+| `onFling(MotionEvent e1, MotionEvent e2, float velocityX, float velocityY)` | `SwipeGesture` | 快速滑动 | 需要速度阈值判断 |
+
+### 3.4 缩放手势
+
+| Android 手势 | HarmonyOS 手势 | 映射说明 | 参数映射 |
+|-------------|---------------|----------|---------|
+| `ScaleGestureDetector.OnScaleGestureListener` | `PinchGesture` | 双指缩放 | 需配合手势系统 |
+| `onScale(ScaleGestureDetector detector)` | `PinchGesture` onAction | 缩放动作 | `onAction((event: GestureEvent) => { /* 处理缩放 */ })` |
+| `onScaleBegin(ScaleGestureDetector detector)` | `PinchGesture` onActionStart | 缩放开始 | `onActionStart(() => {})` |
+| `onScaleEnd(ScaleGestureDetector detector)` | `PinchGesture` onActionEnd | 缩放结束 | `onActionEnd(() => {})` |
+
+### 3.5 旋转手势
+
+| Android 手势 | HarmonyOS 手势 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| 无直接对应（需自定义） | `RotationGesture` | 双指旋转 | `Component().gesture(RotationGesture().onAction(() => {}))` |
+
+### 3.6 手势组合与冲突处理
+
+| Android 机制 | HarmonyOS 机制 | 映射说明 |
+|-------------|---------------|----------|
+| GestureDetector 组合 | `GestureGroup` | 手势组合识别 |
+| 手势冲突处理 | `GestureMask` | 手势响应模式控制 |
+| 事件拦截 onInterceptTouchEvent | `onTouchIntercept` | 触摸事件拦截 |
+
+---
+
+## 四、滑动与拖拽映射
+
+### 4.1 滑动手势
+
+| Android 事件 | HarmonyOS 手势 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| `OnPageChangeListener` | `SwiperController` + onChange | 页面滑动 | `Swiper().onChange((index) => {})` |
+| `OnScrollChangeListener` | `Scroll` onScroll | 滚动监听 | `Scroll().onScroll((xOffset, yOffset) => {})` |
+| `RecyclerView.OnScrollListener` | `List` onScroll | 列表滚动 | `List().onScroll((scrollOffset, scrollState) => {})` |
+
+### 4.2 拖拽功能
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| View.OnDragListener | `Drag` 装饰器 | 拖拽功能 | `Component().gesture(Drag())` |
+| `onDrag(View v, DragEvent event)` | `Drag` onActionStart/onAction/onActionEnd | 拖拽事件 | `onActionStart(() => {})`<br/>`onAction((event) => {})`<br/>`onActionEnd(() => {})` |
+| `startDragAndDrop()` | 无直接对应 | 系统拖拽 | 需自定义实现 |
+
+### 4.3 滑动删除
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| ItemTouchHelper Swipe | `SwipeGesture` + 状态 | 滑动删除 | `ListItem().gesture(SwipeGesture().onAction(() => { /* 删除逻辑 */ }))` |
+
+---
+
+## 五、焦点事件映射
+
+### 5.1 焦点获取与失去
+
+| Android 事件 | HarmonyOS 事件 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `OnFocusChangeListener.onFocusChange(View v, boolean hasFocus)` | `onFocus()` / `onBlur()` | 分离为两个事件 | Android: `view.onFocusChange { _, hasFocus -> }`<br/>HarmonyOS: `Component().onFocus(() => {}).onBlur(() => {})` |
+| `setOnFocusChangeListener()` | `onFocus()` / `onBlur()` | 焦点变化监听 | `Component().onFocus(() => { /* 获得焦点 */ }).onBlur(() => { /* 失去焦点 */ })` |
+
+### 5.2 焦点请求与管理
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `requestFocus()` | `focusControl.requestFocus()` | 请求焦点 | Android: `editText.requestFocus()`<br/>HarmonyOS: `focusControl.requestFocus(this.input)` |
+| `clearFocus()` | `focusControl.requestFocus(null)` | 清除焦点 | Android: `editText.clearFocus()`<br/>HarmonyOS: `focusControl.requestFocus(null)` |
+| `isFocused()` | 组件属性 `focused` | 检查焦点状态 | Android: `view.isFocused()`<br/>HarmonyOS: 组件内部状态判断 |
+| `findFocus()` | `focusControl.requestFocus()` | 查找焦点组件 | 功能相似，API不同 |
+
+### 5.3 焦点遍历
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 |
+|-------------|---------------|----------|
+| `FOCUS_DOWN` / `FOCUS_UP` / `FOCUS_LEFT` / `FOCUS_RIGHT` | 键盘方向键 | 方向键移动焦点 |
+| `nextFocusDown` 等 XML 属性 | `focusable` 属性 | 焦点可获取性 |
+| `FocusFinder.findNextFocus()` | 系统自动处理 | 下一个焦点查找 |
+
+### 5.4 焦点触发方式
+
+| Android 特性 | HarmonyOS 特性 | 映射说明 |
+|-------------|---------------|----------|
+| 触摸自动获取焦点 | 默认不自动 | HarmonyOS 需设置 `focusOnTouch` 属性 |
+| Tab 键切换焦点 | Tab 键切换焦点 | 默认行为一致 |
+| 方向键移动焦点 | 方向键移动焦点 | 默认行为一致 |
+
+---
+
+## 六、键盘事件映射
+
+### 6.1 键盘输入事件
+
+| Android 事件 | HarmonyOS 事件 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `OnKeyListener.onKey(View v, int keyCode, KeyEvent event)` | `onKeyEvent(event: KeyEvent)` | 键盘事件 | Android: `view.setOnKeyListener { _, keyCode, _ -> }`<br/>HarmonyOS: `Component().onKeyEvent((event) => { /* 处理按键 */ })` |
+| `dispatchKeyEvent(KeyEvent event)` | `onKeyEvent()` | 按键分发 | 功能类似 |
+
+### 6.2 键盘操作映射
+
+| Android 键值 | HarmonyOS 键值 | 映射说明 |
+|-------------|---------------|----------|
+| `KeyEvent.KEYCODE_ENTER` | `KeyCode.ENTER` | 回车键 |
+| `KeyEvent.KEYCODE_BACK` | `KeyCode.ESCAPE` | 返回键 |
+| `KeyEvent.KEYCODE_DEL` | `KeyCode.DELETE` | 删除键 |
+| `KeyEvent.KEYCODE_TAB` | `KeyCode.TAB` | Tab 键 |
+| `KeyEvent.KEYCODE_DPAD_UP/DOWN/LEFT/RIGHT` | 方向键 | 方向键 |
+
+### 6.3 输入法相关
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 |
+|-------------|---------------|----------|
+| `InputMethodManager` | `InputMethod` | 输入法管理 |
+| `showSoftInput()` / `hideSoftInput()` | `focusControl.requestFocus()` | 显示/隐藏键盘 |
+| `IME_ACTION` 配置 | `enterKeyType` 属性 | 输入法操作类型 |
+
+---
+
+## 七、事件分发与拦截映射
+
+### 7.1 事件分发机制（API 20/21）
+
+| Android 机制 | HarmonyOS 机制 | 映射说明 | 架构差异 |
+|-------------|---------------|----------|---------|
+| `dispatchTouchEvent()` | 自动分发系统 | Android 手动分发 | HarmonyOS 自动处理 |
+| `onInterceptTouchEvent()` | `onTouchIntercept()` | 事件拦截 | 功能类似，API不同 |
+| 事件响应链机制 | 事件响应链机制 | 事件传播 | HarmonyOS 基于触摸测试构建响应链（API 20/21） |
+
+### 7.2 事件冒泡与阻止（API 20/21）
+
+| Android 机制 | HarmonyOS 机制 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `requestDisallowInterceptTouchEvent(true)` | `onTouchIntercept` 返回 false | 阻止拦截 | Android: `parent.requestDisallowInterceptTouchEvent(true)`<br/>HarmonyOS: `Container().onTouchIntercept(() => false)` |
+| `stopPropagation()` | `event.stopPropagation()` | 停止事件冒泡 | HarmonyOS: `event.stopPropagation()`（API 21+） |
+| `return true` / `return false` | 事件消费 | 事件消费控制 | Android: `return true` 消费事件<br/>HarmonyOS: 绑定事件即消费 |
+
+### 7.3 手势拦截增强（API 20 新增）
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| 无直接对应 | `onGestureRecognizerJudgeBegin()` | 手势判断拦截 | `Component().onGestureRecognizerJudgeBegin(() => { /* 拦截手势判断 */ })` |
+| 无直接对应 | `parallelGesture()` | 并行手势绑定 | 支持系统手势和自定义手势并行处理 |
+| 无直接对应 | `手势拦截` | 动态控制手势触发 | 从 API 20 开始支持手势拦截能力 |
+
+### 7.4 事件响应链（API 20/21 核心特性）
+
+| 概念 | Android | HarmonyOS | 说明 |
+|-----|---------|-----------|------|
+| 触摸测试 | 手动实现 | 自动基于坐标测试 | API 20/21 自动进行 |
+| 响应链收集 | 递归遍历 | 右子树优先后序遍历 | 更高效的事件分发 |
+| 事件分发 | dispatchTouchEvent | 自动分发系统 | 减少开发复杂度 |
+
+### 7.3 触摸冲突处理
+
+| Android 问题 | HarmonyOS 解决方案 | 映射说明 | 参考文档 |
+|-------------|-------------------|----------|---------|
+| 父子组件触摸事件冲突 | `onTouch` + `onClick` 冲突解决 | 多层级事件处理 | [多层级手势事件官方文档](https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-gesture-events-multi-level-gesture) |
+| Button onClick 父组件 onTouch 冲突 | `stopPropagation()` 或配置 | 事件优先级处理 | [onTouch与onClick事件冲突 FAQ](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-arkui-174) |
+
+---
+
+## 八、生命周期事件映射
+
+### 8.1 组件生命周期
+
+| Android 生命周期 | HarmonyOS 生命周期 | 映射说明 | 调用时机 |
+|----------------|-------------------|----------|---------|
+| `View.onAttachedToWindow()` | `aboutToAppear()` | 组件即将出现 | 组件挂载到 DOM 时 |
+| `View.onDetachedFromWindow()` | `aboutToDisappear()` | 组件即将消失 | 组件从 DOM 卸载时 |
+| `View.onVisibilityChanged()` | `visibility` 属性变化 | 可见性变化 | 组件显示/隐藏时 |
+
+### 8.2 页面生命周期
+
+| Android 生命周期 | HarmonyOS 生命周期 | 映射说明 | 调用时机 |
+|----------------|-------------------|----------|---------|
+| `Activity.onCreate()` | `UIAbility.onCreate()` | 创建 | 页面创建时 |
+| `Activity.onStart()` | `UIAbility.onForeground()` | 前台 | 页面进入前台时 |
+| `Activity.onResume()` | `UIAbility.onForeground()` 内部处理 | 可交互 | 页面可交互时 |
+| `Activity.onPause()` | `UIAbility.onBackground()` | 后台 | 页面进入后台时 |
+| `Activity.onStop()` | `UIAbility.onBackground()` | 停止 | 页面停止时 |
+| `Activity.onDestroy()` | `UIAbility.onDestroy()` | 销毁 | 页面销毁时 |
+
+### 8.3 页面显示与隐藏
+
+| Android 事件 | HarmonyOS 事件 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| `onWindowFocusChanged(boolean hasFocus)` | `onPageShow()` / `onPageHide()` | 窗口焦点变化 | `@Entry struct Page { onPageShow() { /* 页面显示 */ } onPageHide() { /* 页面隐藏 */ } }` |
+| `onConfigurationChanged(Configuration newConfig)` | `onConfigurationUpdated(newConfig)` | 配置变化 | 配置（如屏幕方向）变化时调用 |
+
+---
+
+## 九、动画交互映射
+
+### 9.1 属性动画
+
+| Android 动画 | HarmonyOS 动画 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `ObjectAnimator.ofFloat(view, "translationX", 0, 100)` | `animateTo({ duration: 1000 }, () => { this.x = 100 })` | 属性动画 | Android: `ObjectAnimator.ofFloat(view, "translationX", 0, 100).start()`<br/>HarmonyOS: `animateTo({ duration: 1000 }, () => { this.x = 100 })` |
+| `ValueAnimator.ofFloat(0, 100)` | `animateTo()` | 值动画 | Android: `ValueAnimator.ofFloat(0, 100)`<br/>HarmonyOS: `animateTo({ duration: 1000 }, () => { this.value = 100 })` |
+| `AnimatorSet` | 组合 `animateTo` 调用 | 动画集合 | Android: `AnimatorSet.playTogether(animator1, animator2)`<br/>HarmonyOS: `animateTo({ duration: 1000 }, () => { this.x = 100; this.y = 200; })` |
+
+### 9.2 补间动画
+
+| Android 动画 | HarmonyOS 动画 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `TranslateAnimation` | `animateTo` + `translate` | 平移动画 | Android: `TranslateAnimation(0, 100, 0, 0)`<br/>HarmonyOS: `Component().translate({ x: this.x }).animation({ duration: 1000 })` |
+| `ScaleAnimation` | `animateTo` + `scale` | 缩放动画 | Android: `ScaleAnimation(1, 1.5f, 1, 1.5f)`<br/>HarmonyOS: `Component().scale({ x: this.scale }).animation({ duration: 1000 })` |
+| `RotateAnimation` | `animateTo` + `rotate` | 旋转动画 | Android: `RotateAnimation(0, 360)`<br/>HarmonyOS: `Component().rotate({ angle: this.angle }).animation({ duration: 1000 })` |
+| `AlphaAnimation` | `animateTo` + `opacity` | 透明度动画 | Android: `AlphaAnimation(1, 0)`<br/>HarmonyOS: `Component().opacity(this.opacity).animation({ duration: 1000 })` |
+
+### 9.3 转场动画
+
+| Android 转场 | HarmonyOS 转场 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `ActivityOptions.makeCustomAnimation()` | `pageTransition()` | 页面转场 | Android: `startActivity(intent, options.toBundle())`<br/>HarmonyOS: `@Entry @Component struct Page { pageTransition() { PageTransitionEnter({ type: RouteType.None, duration: 1000 }).slide({ type: SlideEffect.Right }) } }` |
+| `SharedElementCallback` | `sharedTransition()` | 共享元素转场 | Android: `ActivityOptions.makeSceneTransitionAnimation()`<br/>HarmonyOS: `Component().sharedTransition('id', { duration: 1000 })` |
+| `Transition` | `transition` | 组件转场 | Android: `TransitionSet`<br/>HarmonyOS: `if (this.show) { Component().transition({ type: TransitionType.All, opacity: 0 }) }` |
+
+### 9.4 动画监听器
+
+| Android 监听器 | HarmonyOS 监听器 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `Animator.AnimatorListener` | `AnimatorResult` 回调 | 动画生命周期 | Android: `animator.addListener(object: Animator.AnimatorListener { override fun onAnimationStart(animation: Animator) {} override fun onAnimationEnd(animation: Animator) {} })`<br/>HarmonyOS: `animateTo({ duration: 1000, onFinish: () => { /* 动画结束 */ } }, () => { /* 动画内容 */ })` |
+| `ValueAnimator.AnimatorUpdateListener` | `AnimatorResult` 回调 | 动画更新 | Android: `valueAnimator.addUpdateListener { animation -> val value = animation.animatedValue as Float }`<br/>HarmonyOS: 状态自动更新，无需回调 |
+
+### 9.5 动画控制
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `animator.start()` | `animateTo()` 自动执行 | 启动动画 | Android: `animator.start()`<br/>HarmonyOS: `animateTo({}, () => { /* 状态变化即启动 */ })` |
+| `animator.cancel()` | `AnimatorResult.cancel()` | 取消动画 | Android: `animator.cancel()`<br/>HarmonyOS: `animatorResult.cancel()` |
+| `animator.pause()` | 无直接对应 | 暂停动画 | HarmonyOS 需自定义实现 |
+| `animator.resume()` | 无直接对应 | 恢复动画 | HarmonyOS 需自定义实现 |
+
+---
+
+## 十、拖放功能映射
+
+### 10.1 拖拽系统
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `View.startDragAndDrop()` | `Drag` 装饰器 | 拖拽启动 | Android: `view.startDragAndDrop(clipData, myShadow, null, 0)`<br/>HarmonyOS: `Component().gesture(Drag())` |
+| `OnDragListener` | `Drag` 回调 | 拖拽监听 | Android: `view.setOnDragListener { _, event -> when (event.action) { DragEvent.ACTION_DROP -> } }`<br/>HarmonyOS: `Component().gesture(Drag().onActionStart(() => {}).onAction((event) => {}).onActionEnd(() => {}))` |
+| `DragEvent.ACTION_DRAG_STARTED` | `Drag` onActionStart | 拖拽开始 | `onActionStart(() => { /* 拖拽开始 */ })` |
+| `DragEvent.ACTION_DRAG_LOCATION` | `Drag` onAction | 拖拽进行中 | `onAction((event: GestureEvent) => { /* 拖拽位置 */ })` |
+| `DragEvent.ACTION_DROP` | `Drop` 装饰器 | 放置 | `Component().gesture(Drop().onDrop((event) => { /* 处理放置 */ }))` |
+
+### 10.2 放置目标
+
+| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例 |
+|-------------|---------------|----------|---------|
+| `DragEvent.ACTION_DROP` | `Drop` onDrop | 放置目标 | `DropContainer().gesture(Drop().onDrop((event) => { /* 处理数据放置 */ }))` |
+| `ClipData` 传递 | `Drop` event 参数 | 数据传递 | 通过 gesture event 传递数据 |
+
+---
+
+## 十一、无障碍功能映射
+
+### 11.1 无障碍属性
+
+| Android 属性 | HarmonyOS 属性 | 映射说明 | 代码示例对比 |
+|-------------|---------------|----------|-------------|
+| `setContentDescription(CharSequence)` | `accessibilityText` | 无障碍文本 | Android: `view.setContentDescription("描述文本")`<br/>HarmonyOS: `Component().accessibilityText("描述文本")` |
+| `setImportantForAccessibility(int)` | `accessibilityLevel` | 无障碍重要性 | Android: `view.setImportantForAccessibility(View.IMPORTANT_FOR_ACCESSIBILITY_YES)`<br/>HarmonyOS: `Component().accessibilityLevel(AccessibilityLevel.AUTO)` |
+| `setAccessibilityDelegate()` | 无直接对应 | 无障碍代理 | 需自定义实现 |
+| `announceForAccessibility(CharSequence)` | 无直接对应 | 公告通知 | 需使用系统 API |
+
+---
+
+## 十二、未找到直接对应方案的 UI 交互功能（API 20/21 更新）
+
+以下 Android UI 交互功能在 HarmonyOS ArkUI 中暂无直接对应功能：
+
+| Android 功能 | HarmonyOS 替代方案 | 难度等级 | 说明 |
+|-------------|-------------------|---------|------|
+| **拖放系统** |  |  |  |
+| `ClipData` 系统拖放 | 自定义拖拽 | 困难 | HarmonyOS 没有 ClipData 系统，需自定义数据传递 |
+| `DragEvent.ACTION_DRAG_ENTERED/EXITED` | 自定义边界检测 | 中等 | 需手动判断拖拽进入/离开区域 |
+| **高级焦点功能** |  |  |  |
+| `FocusFinder` 查找算法 | `focusControl` API | 中等 | 系统自动处理，无手动查找需求 |
+| `setOnFocusChangeListener` 的精确时机 | `onFocus` / `onBlur` | 简单 | 时机略有差异，需调整逻辑 |
+| **触摸事件细节** |  |  |  |
+| `MotionEvent.getToolType()` | `toolType` 属性 | 简单 | 部分支持，工具类型有限 |
+| `MotionEvent.getAxisValue()` | 无直接对应 | 中等 | 手柄、滚轮等高级输入暂不支持 |
+| `MotionEvent.getSource()` | 无直接对应 | 中等 | 输入源判断需自定义 |
+| **手势冲突高级处理** |  |  |  |
+| `onInterceptTouchEvent()` 嵌套拦截 | `onTouchIntercept` 级联 | 简单 | API 20/21 提供了更强大的拦截机制 |
+| **动画高级功能** |  |  |  |
+| `Animator.pause()` / `resume()` | 自定义状态管理 | 中等 | 需要手动控制动画状态 |
+| `AnimatorListener.onAnimationRepeat()` | 自定义重复逻辑 | 中等 | HarmonyOS 无重复回调，需手动实现 |
+| `LayoutTransition` | 自定义布局动画 | 困难 | 需要监听组件添加/删除 |
+| `ViewPropertyAnimator` 组合 | 链式 `animateTo` | 简单 | 语法不同，功能类似 |
+| **键盘事件细节** |  |  |  |
+| `KeyEvent` 完整事件体系 | `KeyEvent` 简化版 | 中等 | HarmonyOS 键盘事件较为简化 |
+| `dispatchKeyShortcutEvent()` | 无直接对应 | 中等 | 快捷键处理需自定义 |
+| `onKeyLongPress()` | 自定义延时判断 | 简单 | 需要计时逻辑 |
+| **多窗口交互** |  |  |  |
+| `onMultiWindowModeChanged()` | 无直接对应 | 不可行 | HarmonyOS 无多窗口模式 |
+| `onPictureInPictureModeChanged()` | 无直接对应 | 不可行 | HarmonyOS 无画中画模式 |
+
+**注意**：API 20/21 已显著改进了事件处理能力，包括：
+- 增强的 HitTestMode（BLOCK_HIERARCHY、BLOCK_DESCENDANTS）
+- 手势拦截增强（onGestureRecognizerJudgeBegin）
+- 事件响应链机制优化
+- 响应热区 responseRegion 支持
+
+---
+
+## 十三、映射方案总结
+
+### 13.1 完全直接映射的交互功能（40+）
+
+可以直接一对一替换的交互功能：
+- 基础触摸事件（onTouch）
+- 点击事件（onClick）
+- 焦点事件（onFocus/onBlur）
+- 键盘事件（onKeyEvent）
+- 基础手势（点击、长按）
+- 动画 API（animateTo）
+
+### 13.2 需要调整的交互功能（30+）
+
+需要调整实现方式的交互功能：
+- 手势识别（需使用手势系统而非监听器）
+- 动画系统（声明式动画，状态驱动）
+- 事件分发（自动分发 vs 手动分发）
+- 生命周期（分离为多个回调）
+
+### 13.3 需要自定义实现的交互功能（15+）
+
+需要编写自定义逻辑或组件的交互功能：
+- 系统拖放（需自定义数据传递）
+- 高级焦点功能（系统自动处理）
+- 动画暂停/恢复（需状态管理）
+- 多窗口交互（架构不支持）
+
+### 13.4 API 20/21 新增改进
+
+API 20/21 带来了以下重要改进：
+- **响应热区支持**：`responseRegion` 属性，可扩展组件响应范围
+- **增强的触摸测试控制**：`HitTestMode.BLOCK_HIERARCHY`、`HitTestMode.BLOCK_DESCENDANTS`
+- **手势拦截增强**：`onGestureRecognizerJudgeBegin()`、`parallelGesture()`
+- **事件响应链优化**：更高效的事件分发机制
+- **stopPropagation()**：更灵活的事件冒泡控制
+
+---
+
+## 十四、迁移建议
+
+### 14.1 交互功能迁移优先级
+
+1. **高优先级**（完全支持）：
+   - 点击事件、长按事件
+   - 基础手势（点击、长按、拖动）
+   - 焦点事件、键盘事件
+   - 基础动画
+
+2. **中优先级**（部分支持）：
+   - 复杂手势（缩放、旋转）
+   - 事件分发与拦截
+   - 转场动画
+   - 无障碍功能
+
+3. **低优先级**（暂不支持或困难）：
+   - 系统拖放
+   - 多窗口交互
+   - 高级键盘事件
+   - 动画暂停/恢复
+
+### 14.2 交互功能迁移策略
+
+1. **声明式思维转换**：
+   - Android：命令式，监听器 + 回调
+   - HarmonyOS：声明式，状态 + 绑定
+   - 需要改变编程范式
+
+2. **手势系统优先**：
+   - 优先使用 HarmonyOS 手势系统（TapGesture、PanGesture 等）
+   - 避免在 onTouch 中手动解析手势
+
+3. **状态驱动动画**：
+   - 动画通过状态变化触发
+   - 使用 @State 装饰器管理动画状态
+
+4. **事件冒泡处理**：
+   - 理解 HarmonyOS 事件冒泡机制
+   - 合理使用 stopPropagation()
+
+### 14.3 注意事项
+
+1. **事件模型差异**：
+   - Android：事件分发机制复杂
+   - HarmonyOS：手势系统更简洁
+
+2. **焦点处理方式**：
+   - Android：复杂的焦点查找和管理
+   - HarmonyOS：focusControl API 简化
+
+3. **动画架构差异**：
+   - Android：基于对象的动画系统
+   - HarmonyOS：基于状态的声明式动画
+
+4. **手势识别方式**：
+   - Android：GestureDetector + 监听器
+   - HarmonyOS：手势装饰器 + 回调
+
+5. **测试重点**：
+   - 多点触控场景
+   - 手势冲突处理
+   - 性能优化（避免过度重绘）
+
+---
+
+## 参考链接
+
+### Android 官方文档
+1. **[处理多点触控手势 | Android Developers](https://developer.android.com/develop/ui/views/touch-and-input/gestures/multi?hl=zh-cn)**
+2. **[检测常用手势 | Android Developers](https://developer.android.com/develop/ui/views/touch-and-input/gestures/detector?hl=zh-cn)**
+3. **[了解手势 | Jetpack Compose](https://android-docs.cn/develop/ui/compose/touch-input/pointer-input/understand-gestures)**
+4. **[ViewGroup中管理触摸事件 | Android Developers](https://developer.android.com/develop/ui/views/touch-and-input/gestures/viewgroup?hl=zh-cn)**
+5. **[属性动画概览 | Android Developers](https://developer.android.com/develop/ui/views/animations/prop-animation?hl=zh-cn)**
+6. **[Android 触摸手势基础官方文档概览](https://www.cnblogs.com/mengdd/p/3335508.html)**
+7. **[Android 手势识别类 GestureDetector 基本介绍](https://developer.aliyun.com/article/569712)**
+
+### HarmonyOS 官方文档
+1. **[多层级手势事件官方文档](https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-gesture-events-multi-level-gesture)**
+2. **[焦点事件](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-focus-event)**
+3. **[焦点处理指南](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-common-events-focus-event)**
+4. **[转场动画](https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-animation-transition)**
+5. **[显式动画(animateTo)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-explicit-animation)**
+6. **[焦点事件onBlur/onFocus回调无法触发](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-arkui-165)**
+7. **[onTouch与onClick事件冲突 FAQ](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-arkui-174)**
+
+### 技术博客与实战文章
+1. **[ArkUI交互事件与手势处理全解析](https://blog.csdn.net/2301_79624024/article/details/147620496)** - HarmonyOS 手势处理
+2. **[触摸事件机制深入解析](https://segmentfault.com/a/1190000047072887)** - Android 触摸事件详解
+3. **[Android触摸事件分发、手势识别与输入优化实战](https://juejin.cn/post/7611830146089615406)** - 事件分发机制
+4. **[探秘Android手势事件机制与优化技巧](https://juejin.cn/post/7238869983621611576)** - 手势事件机制
+
+---
+
+*本文档基于 Android 14 和 HarmonyOS NEXT API 20/21 (6.0.0/6.0.1) 整理，具体 API 以官方最新文档为准。UI 交互功能的映射涉及复杂的编程范式转换和 API 20/21 新增的事件响应链机制，建议在实际迁移中结合具体场景灵活应用。*