Android-to-HarmonyOS UI Interaction Mapping Reference
一、触摸事件映射
1.1 基础触摸事件
| Android 事件 | HarmonyOS 事件 | 映射说明 | 代码示例对比 |
|---|---|---|---|
onTouchEvent(MotionEvent) |
onTouch(event: TouchEvent) |
直接映射 | Android: view.onTouchEvent(event)HarmonyOS: Component().onTouch((event) => {}) |
onInterceptTouchEvent(MotionEvent) |
onTouchIntercept(event: TouchEvent) |
直接映射 | Android: viewGroup.onInterceptTouchEvent(event)HarmonyOS: Container().onTouchIntercept((event) => {}) |
dispatchTouchEvent(MotionEvent) |
事件分发机制 | 架构差异 | Android: 手动分发 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 { }HarmonyOS: Button().onClick(() => {}) |
OnLongClickListener.onLongClick(View) |
onLongPress() 手势 |
手势识别 | Android: button.setOnLongClickListener { }HarmonyOS: Button().gesture(LongPressGesture().onAction(() => {})) |
OnDoubleClickListener |
TapGesture({count: 2}) |
手势识别 | Android: 自定义实现 HarmonyOS: Component().gesture(TapGesture({count: 2}).onAction(() => {})) |
OnContextClickListener |
BindContextMenu |
上下文菜单 | Android: view.setOnContextClickListener { }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(() => {})onAction((event) => {})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 -> }HarmonyOS: Component().onFocus(() => {}).onBlur(() => {}) |
setOnFocusChangeListener() |
onFocus() / onBlur() |
焦点变化监听 | Component().onFocus(() => { /* 获得焦点 */ }).onBlur(() => { /* 失去焦点 */ }) |
5.2 焦点请求与管理
| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例对比 |
|---|---|---|---|
requestFocus() |
focusControl.requestFocus() |
请求焦点 | Android: editText.requestFocus()HarmonyOS: focusControl.requestFocus(this.input) |
clearFocus() |
focusControl.requestFocus(null) |
清除焦点 | Android: editText.clearFocus()HarmonyOS: focusControl.requestFocus(null) |
isFocused() |
组件属性 focused |
检查焦点状态 | Android: view.isFocused()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, _ -> }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)HarmonyOS: Container().onTouchIntercept(() => false) |
stopPropagation() |
event.stopPropagation() |
停止事件冒泡 | HarmonyOS: event.stopPropagation()（API 21+） |
return true / return false |
事件消费 | 事件消费控制 | Android: return true 消费事件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 冲突解决 |
多层级事件处理 | 多层级手势事件官方文档 |
| Button onClick 父组件 onTouch 冲突 | stopPropagation() 或配置 |
事件优先级处理 | onTouch与onClick事件冲突 FAQ |
八、生命周期事件映射
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()HarmonyOS: animateTo({ duration: 1000 }, () => { this.x = 100 }) |
ValueAnimator.ofFloat(0, 100) |
animateTo() |
值动画 | Android: ValueAnimator.ofFloat(0, 100)HarmonyOS: animateTo({ duration: 1000 }, () => { this.value = 100 }) |
AnimatorSet |
组合 animateTo 调用 |
动画集合 | Android: AnimatorSet.playTogether(animator1, animator2)HarmonyOS: animateTo({ duration: 1000 }, () => { this.x = 100; this.y = 200; }) |
9.2 补间动画
| Android 动画 | HarmonyOS 动画 | 映射说明 | 代码示例对比 |
|---|---|---|---|
TranslateAnimation |
animateTo + translate |
平移动画 | Android: TranslateAnimation(0, 100, 0, 0)HarmonyOS: Component().translate({ x: this.x }).animation({ duration: 1000 }) |
ScaleAnimation |
animateTo + scale |
缩放动画 | Android: ScaleAnimation(1, 1.5f, 1, 1.5f)HarmonyOS: Component().scale({ x: this.scale }).animation({ duration: 1000 }) |
RotateAnimation |
animateTo + rotate |
旋转动画 | Android: RotateAnimation(0, 360)HarmonyOS: Component().rotate({ angle: this.angle }).animation({ duration: 1000 }) |
AlphaAnimation |
animateTo + opacity |
透明度动画 | Android: AlphaAnimation(1, 0)HarmonyOS: Component().opacity(this.opacity).animation({ duration: 1000 }) |
9.3 转场动画
| Android 转场 | HarmonyOS 转场 | 映射说明 | 代码示例对比 |
|---|---|---|---|
ActivityOptions.makeCustomAnimation() |
pageTransition() |
页面转场 | Android: startActivity(intent, options.toBundle())HarmonyOS: @Entry @Component struct Page { pageTransition() { PageTransitionEnter({ type: RouteType.None, duration: 1000 }).slide({ type: SlideEffect.Right }) } } |
SharedElementCallback |
sharedTransition() |
共享元素转场 | Android: ActivityOptions.makeSceneTransitionAnimation()HarmonyOS: Component().sharedTransition('id', { duration: 1000 }) |
Transition |
transition |
组件转场 | Android: TransitionSetHarmonyOS: 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) {} })HarmonyOS: animateTo({ duration: 1000, onFinish: () => { /* 动画结束 */ } }, () => { /* 动画内容 */ }) |
ValueAnimator.AnimatorUpdateListener |
AnimatorResult 回调 |
动画更新 | Android: valueAnimator.addUpdateListener { animation -> val value = animation.animatedValue as Float }HarmonyOS: 状态自动更新，无需回调 |
9.5 动画控制
| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例对比 |
|---|---|---|---|
animator.start() |
animateTo() 自动执行 |
启动动画 | Android: animator.start()HarmonyOS: animateTo({}, () => { /* 状态变化即启动 */ }) |
animator.cancel() |
AnimatorResult.cancel() |
取消动画 | Android: animator.cancel()HarmonyOS: animatorResult.cancel() |
animator.pause() |
无直接对应 | 暂停动画 | HarmonyOS 需自定义实现 |
animator.resume() |
无直接对应 | 恢复动画 | HarmonyOS 需自定义实现 |
十、拖放功能映射
10.1 拖拽系统
| Android 功能 | HarmonyOS 功能 | 映射说明 | 代码示例对比 |
|---|---|---|---|
View.startDragAndDrop() |
Drag 装饰器 |
拖拽启动 | Android: view.startDragAndDrop(clipData, myShadow, null, 0)HarmonyOS: Component().gesture(Drag()) |
OnDragListener |
Drag 回调 |
拖拽监听 | Android: view.setOnDragListener { _, event -> when (event.action) { DragEvent.ACTION_DROP -> } }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("描述文本")HarmonyOS: Component().accessibilityText("描述文本") |
setImportantForAccessibility(int) |
accessibilityLevel |
无障碍重要性 | Android: view.setImportantForAccessibility(View.IMPORTANT_FOR_ACCESSIBILITY_YES)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 交互功能迁移优先级
-
高优先级（完全支持）：
- 点击事件、长按事件
- 基础手势（点击、长按、拖动）
- 焦点事件、键盘事件
- 基础动画
-
中优先级（部分支持）：
- 复杂手势（缩放、旋转）
- 事件分发与拦截
- 转场动画
- 无障碍功能
-
低优先级（暂不支持或困难）：
- 系统拖放
- 多窗口交互
- 高级键盘事件
- 动画暂停/恢复
14.2 交互功能迁移策略
-
声明式思维转换：
- Android：命令式，监听器 + 回调
- HarmonyOS：声明式，状态 + 绑定
- 需要改变编程范式
-
手势系统优先：
- 优先使用 HarmonyOS 手势系统（TapGesture、PanGesture 等）
- 避免在 onTouch 中手动解析手势
-
状态驱动动画：
- 动画通过状态变化触发
- 使用 @State 装饰器管理动画状态
-
事件冒泡处理：
- 理解 HarmonyOS 事件冒泡机制
- 合理使用 stopPropagation()
14.3 注意事项
-
事件模型差异：
- Android：事件分发机制复杂
- HarmonyOS：手势系统更简洁
-
焦点处理方式：
- Android：复杂的焦点查找和管理
- HarmonyOS：focusControl API 简化
-
动画架构差异：
- Android：基于对象的动画系统
- HarmonyOS：基于状态的声明式动画
-
手势识别方式：
- Android：GestureDetector + 监听器
- HarmonyOS：手势装饰器 + 回调
-
测试重点：
- 多点触控场景
- 手势冲突处理
- 性能优化（避免过度重绘）
参考链接
Android 官方文档
- 处理多点触控手势 | Android Developers
- 检测常用手势 | Android Developers
- 了解手势 | Jetpack Compose
- ViewGroup中管理触摸事件 | Android Developers
- 属性动画概览 | Android Developers
- Android 触摸手势基础官方文档概览
- Android 手势识别类 GestureDetector 基本介绍
HarmonyOS 官方文档
技术博客与实战文章
- ArkUI交互事件与手势处理全解析 - HarmonyOS 手势处理
- 触摸事件机制深入解析 - Android 触摸事件详解
- Android触摸事件分发、手势识别与输入优化实战 - 事件分发机制
- 探秘Android手势事件机制与优化技巧 - 手势事件机制
本文档基于 Android 14 和 HarmonyOS NEXT API 20/21 (6.0.0/6.0.1) 整理，具体 API 以官方最新文档为准。UI 交互功能的映射涉及复杂的编程范式转换和 API 20/21 新增的事件响应链机制，建议在实际迁移中结合具体场景灵活应用。