常见鸿蒙ArkTS事件功能

一、基础事件类型

1.1 点击事件

事件名称 方法签名 触发条件 用途示例
onClick onClick(event: Callback<ClickEvent>): T 组件被点击时触发 按钮交互、导航跳转
onClickWithDistance onClick(event: Callback<ClickEvent>, distanceThreshold: number): T 点击且移动距离不超过阈值时触发 精确点击控制

1.2 触摸事件

事件名称 方法签名 触发条件 用途示例
onTouch onTouch(event: (event: TouchEvent) => void): T 手指触摸屏幕时触发 手势识别、拖拽操作
onTouchStart onTouchStart(event: (event: TouchEvent) => void): T 触摸开始时触发 触摸反馈动画
onTouchMove onTouchMove(event: (event: TouchEvent) => void): T 触摸移动时触发 滑动操作、绘图功能
onTouchEnd onTouchEnd(event: (event: TouchEvent) => void): T 触摸结束时触发 完成手势操作
onTouchCancel onTouchCancel(event: (event: TouchEvent) => void): T 触摸被系统取消时触发 中断操作处理

1.3 焦点事件

事件名称 方法签名 触发条件 用途示例
onFocus onFocus(event: () => void): T 组件获得焦点时触发 输入框聚焦效果
onBlur onBlur(event: () => void): T 组件失去焦点时触发 表单验证、保存输入

1.4 按键事件

事件名称 方法签名 触发条件 用途示例
onKeyEvent onKeyEvent(event: (event: KeyEvent) => void): T 键盘按键被按下时触发 快捷键功能、游戏控制
onKeyPreIme onKeyPreIme(event: Callback<KeyEvent, boolean>): T 输入法按键事件触发前 输入法预处理

1.5 鼠标事件

事件名称 方法签名 触发条件 用途示例
onMouse onMouse(event: (event: MouseEvent) => void): T 鼠标操作时触发 鼠标悬停效果、点击操作
onHover onHover(event: (isHover: boolean, event: HoverEvent) => void): T 鼠标悬停时触发 悬停显示详情
onHoverMove onHoverMove(event: Callback<HoverEvent>): T 鼠标在悬停状态下移动时 精细控制交互

1.6 滚动事件

事件名称 方法签名 触发条件 用途示例
onScroll onScroll(event: (event: ScrollEvent) => void): T 组件滚动时触发 无限滚动加载、滚动动画
onScrollEnd onScrollEnd(event: () => void): T 滚动结束时触发 滚动结束后的操作

二、生命周期事件

2.1 组件生命周期

事件名称 方法签名 触发条件 用途示例
onAttach onAttach(callback: Callback<void>): T 组件挂载到DOM时触发 初始化数据、订阅事件
onDetach onDetach(callback: Callback<void>): T 组件从DOM卸载时触发 清理资源、取消订阅
onAppear onAppear(event: () => void): T 组件显示时触发 显示动画、加载数据
onDisAppear onDisAppear(event: () => void): T 组件隐藏时触发 暂停动画、保存状态

2.2 视图生命周期

事件名称 方法签名 触发条件 用途示例
onPageShow onPageShow(callback: () => void): void 页面显示时触发 页面数据刷新
onPageHide onPageHide(callback: () => void): void 页面隐藏时触发 页面状态保存

三、拖拽与拖放事件

3.1 拖拽源事件

事件名称 方法签名 触发条件 用途示例
onDragStart `onDragStart(event: (event: DragEvent, extraParams?: string) => CustomBuilder DragItemInfo): T` 拖拽开始时触发
onDragEnd onDragEnd(event: (event: DragEvent, extraParams?: string) => void): T 拖拽结束时触发 清理拖拽状态

3.2 拖放目标事件

事件名称 方法签名 触发条件 用途示例
onDragEnter onDragEnter(event: (event: DragEvent, extraParams?: string) => void): T 拖拽物进入目标区域时 高亮目标区域
onDragMove onDragMove(event: (event: DragEvent, extraParams?: string) => void): T 拖拽物在目标区域内移动时 实时反馈
onDragLeave onDragLeave(event: (event: DragEvent, extraParams?: string) => void): T 拖拽物离开目标区域时 移除高亮效果
onDrop onDrop(eventCallback: OnDragEventCallback, dropOptions?: DropOptions): T 拖拽物在目标区域释放时 处理拖放数据

3.3 拖拽预处理

事件名称 方法签名 触发条件 用途示例
onPreDrag onPreDrag(event: (preDragStatus: PreDragStatus) => void): T 拖拽前的准备阶段 确认是否允许拖拽

四、区域与可见性事件

4.1 区域变化

事件名称 方法签名 触发条件 用途示例
onAreaChange onAreaChange(event: (oldValue: Area, newValue: Area) => void): T 组件区域变化时触发 响应式布局调整

4.2 可见性变化

事件名称 方法签名 触发条件 用途示例
onVisibleAreaChange onVisibleAreaChange(ratios: Array<number>, event: (isVisible: boolean, currentRatio: number) => void): T 可见区域比例变化时 懒加载、曝光统计

五、自定义事件

5.1 自定义事件触发

事件名称 方法签名 触发条件 用途示例
emit emit(eventName: string, ...args: any[]): void 手动触发自定义事件 组件间通信

5.2 自定义事件监听

事件名称 方法签名 触发条件 用途示例
on on(eventName: string, callback: (...args: any[]) => void): T 监听自定义事件 父组件监听子组件事件

六、手势事件

6.1 手势识别

事件名称 方法签名 触发条件 用途示例
onGesture onGesture(gesture: Gesture, callback: () => void): T 特定手势识别成功时 双指缩放、旋转操作
onPan onPan(event: (event: GestureEvent) => void, options?: PanGestureOptions): T 平移手势时 滑动翻页、拖拽排序
onPinch onPinch(event: (event: GestureEvent) => void, options?: PinchGestureOptions): T 缩放手势时 图片缩放、地图缩放
onRotate onRotate(event: (event: GestureEvent) => void, options?: RotateGestureOptions): T 旋转手势时 图片旋转、角度调整
onDoubleClick onDoubleClick(event: (event: GestureEvent) => void): T 双击手势时 放大查看详情
onLongPress onLongPress(event: (event: GestureEvent) => void, options?: LongPressGestureOptions): T 长按手势时 显示菜单、删除确认

七、动画事件

7.1 动画生命周期

事件名称 方法签名 触发条件 用途示例
onAnimationStart onAnimationStart(callback: () => void): T 动画开始时触发 准备动画状态
onAnimationUpdate onAnimationUpdate(callback: (progress: number) => void): T 动画更新时触发 实时更新UI
onAnimationEnd onAnimationEnd(callback: () => void): T 动画结束时触发 清理动画状态

八、数据绑定事件

8.1 状态变化

事件名称 方法签名 触发条件 用途示例
@State @State value: type 状态值变化时 响应式UI更新
@Link @Link value: type 链接状态变化时 双向数据绑定
@Provide @Provide value: type 提供状态变化时 向下传递状态
@Consume @Consume value: type 消费状态变化时 接收父组件状态

九、权限与资源事件

9.1 权限请求

事件名称 方法签名 触发条件 用途示例
requestPermissionsFromUser requestPermissionsFromUser(permissions: Array<string>, requestCode: number): Promise<Array<PermissionResult>> 请求权限时 获取相机、位置权限

9.2 资源加载

事件名称 方法签名 触发条件 用途示例
onResourceLoad onResourceLoad(callback: () => void): T 资源加载完成时 图片加载完成回调
onResourceError onResourceError(callback: (error: ResourceError) => void): T 资源加载失败时 错误处理、重试机制

十、设备与系统事件

10.1 设备状态

事件名称 方法签名 触发条件 用途示例
onOrientationChange onOrientationChange(callback: (orientation: Orientation) => void): T 屏幕方向变化时 横屏/竖屏适配
onWindowStageShow onWindowStageShow(callback: () => void): void 窗口显示时 窗口显示初始化
onWindowStageHide onWindowStageHide(callback: () => void): void 窗口隐藏时 窗口隐藏清理

10.2 系统事件

事件名称 方法签名 触发条件 用途示例
onMemoryLevel onMemoryLevel(callback: (level: number) => void): void 内存级别变化时 内存优化
onBatteryLevel onBatteryLevel(callback: (level: number) => void): void 电池电量变化时 省电模式切换

十一、输入事件

11.1 文本输入

事件名称 方法签名 触发条件 用途示例
onInput onInput(callback: (value: string) => void): T 输入内容变化时 实时搜索、表单验证
onConfirm onConfirm(callback: (value: string) => void): T 确认输入时 搜索提交、表单提交

11.2 选择器事件

事件名称 方法签名 触发条件 用途示例
onSelect onSelect(callback: (index: number, value: string) => void): T 选项被选中时 下拉菜单选择
onChange onChange(callback: (value: string) => void): T 值变化时 滑块、开关状态变化

十二、多媒体事件

12.1 音频事件

事件名称 方法签名 触发条件 用途示例
onPlay onPlay(callback: () => void): T 音频播放时 播放状态更新
onPause onPause(callback: () => void): T 音频暂停时 暂停状态更新
onEnd onEnd(callback: () => void): T 音频播放结束时 播放下一首
onError onError(callback: (error: MediaError) => void): T 音频播放错误时 错误提示

12.2 视频事件

事件名称 方法签名 触发条件 用途示例
onStateChange onStateChange(callback: (state: number) => void): T 视频状态变化时 加载、播放、暂停状态切换
onProgress onProgress(callback: (progress: number) => void): T 视频进度更新时 进度条更新
onBufferStart onBufferStart(callback: () => void): T 视频缓冲开始时 显示加载提示
onBufferEnd onBufferEnd(callback: () => void): T 视频缓冲结束时 隐藏加载提示

十三、网络事件

13.1 网络状态

事件名称 方法签名 触发条件 用途示例
onNetworkStateChange onNetworkStateChange(callback: (networkState: NetworkState) => void): void 网络状态变化时 网络连接提示

13.2 HTTP请求

事件名称 方法签名 触发条件 用途示例
onSuccess onSuccess(callback: (data: string) => void): T 请求成功时 处理响应数据
onFail onFail(callback: (data: string, code: number) => void): T 请求失败时 错误处理
onComplete onComplete(callback: () => void): T 请求完成时 清理状态

十四、传感器事件

14.1 加速度传感器

事件名称 方法签名 触发条件 用途示例
onAccelerometerDataChange onAccelerometerDataChange(callback: (data: AccelerometerData) => void): void 加速度数据变化时 摇一摇功能

14.2 陀螺仪传感器

事件名称 方法签名 触发条件 用途示例
onGyroscopeDataChange onGyroscopeDataChange(callback: (data: GyroscopeData) => void): void 陀螺仪数据变化时 3D视图控制

14.3 位置传感器

事件名称 方法签名 触发条件 用途示例
onLocationChange onLocationChange(callback: (location: Location) => void): void 位置变化时 地图定位、导航

十五、通知事件

15.1 系统通知

事件名称 方法签名 触发条件 用途示例
onNotificationReceived onNotificationReceived(callback: (notification: Notification) => void): void 收到通知时 显示通知提示
onNotificationClicked onNotificationClicked(callback: (notification: Notification) => void): void 通知被点击时 跳转到对应页面

15.2 自定义通知

事件名称 方法签名 触发条件 用途示例
sendCustomEvent sendCustomEvent(event: CustomEvent): void 发送自定义事件时 组件间通信
onCustomEvent onCustomEvent(callback: (event: CustomEvent) => void): void 接收自定义事件时 跨组件监听
# 开发语言
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

HarmonyOS NEXT 华为账号登录全流程（客户端 + Go 后端）

avatar HarmonyOS开发者社区

HarmonyOS ArkUI技术实践：番茄计时器应用的设计与实现

本文介绍了一款基于HarmonyOS ArkUI开发的番茄计时器应用，实现了番茄工作法的核心功能。应用采用单页面架构，通过状态管理实现专注计时（25分钟）、短休（5分钟）和长休（15分钟）模式的切换。关键技术包括定时器管理（setInterval）、时间格式化、状态同步（@State装饰器）和事件驱动逻辑。文章详细阐述了功能实现方案，包括计时器启停控制、自动模式切换和UI状态更新等核心模块的设计思

avatar HarmonyOS开发者社区

鸿蒙6.1小艺伴随式AI体验：让阅读效率翻倍

HarmonyOS 6.1 AI能力更进一步，华为Pura X Max大阔折手机依托全新小艺智慧大脑，推出业界首个"伴随式AI"——"小艺伴随式AI"。小艺通过侧边常驻、展开、后台静默三种模式，在不抢占主界面、不中断当前操作的前提下，在合适的场景主动提供服务。小艺伴随式AI智慧伴读让阅读效率大幅提升，从阅读前的向导到阅读中的互动工具，再到断点续读，全程伴随。阅读时支持边读边提问、划重点，并集成表格

avatar HarmonyOS开发者社区