鸿蒙NEXT开发：ArkTS组件-手势处理（设置组件绑定的手势）

最新推荐文章于 2025-09-12 16:46:56 发布
原创 最新推荐文章于 2025-09-12 16:46:56 发布 · 804 阅读 · 25 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #android #鸿蒙系统 #前端 #ArkUI #ArkTS

 往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

设置组件绑定的手势

用于设置组件绑定的手势。可以通过UIGestureEvent对象调用其接口添加或删除手势。

说明

本模块首批接口从API version 12开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。

UIGestureEvent

用于设置组件绑定的手势。

addGesture

addGesture(gesture: GestureHandler<T>, priority?: GesturePriority, mask?: GestureMask): void

添加手势。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
gestureGestureHandler<T>是手势处理器对象。
priorityGesturePriority否绑定手势的优先级。
maskGestureMask否事件响应设置。

addParallelGesture

addParallelGesture(gesture: GestureHandler<T>, mask?: GestureMask): void

绑定可与子组件手势同时触发的手势。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
gestureGestureHandler<T>是手势处理器对象。
maskGestureMask否事件响应设置。

removeGestureByTag

removeGestureByTag(tag: string): void

移除该组件上通过modifier绑定的设置为指定标志的手势。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
tagstring是手势处理器标志。

clearGestures

clearGestures(): void

清除该组件上通过modifier绑定的所有手势。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

GestureHandler<T>

手势对象的基础类型。

tag

tag(tag: string): T

设置手势处理器的标志。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

名称类型必填描述
tagstring是设置手势处理器标志。

allowedTypes14+

allowedTypes(types: Array<SourceTool>): T

设置手势处理器所支持的事件输入源。

元服务API： 从API version 14开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

名称类型必填描述
typesArray<SourceTool>是设置手势处理器所支持的事件输入源。

TapGestureHandler

点击手势处理器对象类型。

constructor

constructor(options?: TapGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsTapGestureHandlerOptions否点击手势处理器配置参数。

onAction

onAction(event: Callback<GestureEvent>): TapGestureHandler

Tap手势识别成功回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Tap手势识别成功回调。

返回值：

类型说明
TapGestureHandler返回当前点击手势处理器对象。

TapGestureHandlerOptions

点击手势处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
countnumber否

识别的连续点击次数。当设置的值小于1或不设置时，会被转化为默认值。

默认值：1

说明：

1. 当配置多击时，上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。

2. 当上次点击的位置与当前点击的位置距离超过60vp时，手势识别失败。

fingersnumber否

触发点击的手指数，最小为1指， 最大为10指。当设置小于1的值或不设置时，会被转化为默认值。

默认值：1

说明：

1. 当配置多指时，第一根手指按下后300毫秒内未有足够的手指数按下，手势识别失败，第一根手指抬起后300毫秒内未有足够的手指抬起，手势识别失败。

2. 实际点击手指数超过配置值，手势识别成功。

LongPressGestureHandler

长按手势处理器对象类型。

constructor

constructor(options?: LongPressGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsLongPressGestureHandlerOptions否长按手势处理器配置参数。

onAction

onAction(event: Callback<GestureEvent>): LongPressGestureHandler

LongPress手势识别成功回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是LongPress手势识别成功回调。

返回值：

类型说明
LongPressGestureHandler返回当前长按手势处理器对象。

onActionEnd

onActionEnd(event: Callback<GestureEvent>): LongPressGestureHandler

LongPress手势识别成功，最后一根手指抬起后触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是LongPress手势识别成功，最后一根手指抬起后触发回调。

返回值：

类型说明
LongPressGestureHandler返回当前长按手势处理器对象。

onActionCancel

onActionCancel(event: Callback<void>): LongPressGestureHandler

LongPress手势识别成功，接收到触摸取消事件触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<void>是LongPress手势识别成功，接收到触摸取消事件触发回调。

返回值：

类型说明
LongPressGestureHandler返回当前长按手势处理器对象。

LongPressGestureHandlerOptions

长按手势处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
fingersnumber否

触发长按的最少手指数，最小为1指， 最大取值为10指。

默认值：1

说明：

手指按下后若发生超过15px的移动，则判定当前长按手势识别失败。

repeatboolean否

是否连续触发事件回调。

默认值：false

durationnumber否

触发长按的最短时间，单位为毫秒（ms）。

默认值：500

说明：

设置小于等于0时，按照默认值500处理。

PanGestureHandler

拖动手势处理器对象类型。

constructor

constructor(options?: PanGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsPanGestureHandlerOptions否拖动手势处理器配置参数。

onActionStart

onActionStart(event: Callback<GestureEvent>): PanGestureHandler

Pan手势识别成功回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Pan手势识别成功回调。

返回值：

类型说明
PanGestureHandler返回当前拖动手势处理器对象。

onActionUpdate

onActionUpdate(event: Callback<GestureEvent>): PanGestureHandler

Pan手势移动过程中回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是

Pan手势移动过程中回调。

fingerList为多根手指时，该回调监听每次只会更新一根手指的位置信息。

返回值：

类型说明
PanGestureHandler返回当前拖动手势处理器对象。

onActionEnd

onActionEnd(event: Callback<GestureEvent>): PanGestureHandler

Pan手势识别成功，手指抬起后触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Pan手势识别成功，手指抬起后触发回调。

返回值：

类型说明
PanGestureHandler返回当前拖动手势处理器对象。

onActionCancel

onActionCancel(event: Callback<void>): PanGestureHandler

Pan手势识别成功，接收到触摸取消事件触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<void>是Pan手势识别成功，接收到触摸取消事件触发回调。

返回值：

类型说明
PanGestureHandler返回当前拖动手势处理器对象。

PanGestureHandlerOptions

拖动手势处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
fingersnumber否

用于指定触发拖动的最少手指数，最小为1指， 最大取值为10指。

默认值：1

取值范围：[1,10]

说明：

当设置的值小于1或不设置时，会被转化为默认值。

directionPanDirection否

用于指定触发拖动的手势方向，此枚举值支持逻辑与(&)和逻辑或（|）运算。

默认值：PanDirection.All

distancenumber否

用于指定触发拖动手势事件的最小拖动距离，单位为vp。

默认值：5

说明：

Tabs组件滑动与该拖动手势事件同时存在时，可将distance值设为1，使拖动更灵敏，避免造成事件错乱。

当设定的值小于0时，按默认值5处理。

SwipeGestureHandler

滑动手势处理器对象类型。

constructor

constructor(options?: SwipeGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsSwipeGestureHandlerOptions否滑动手势处理器配置参数。

onAction

onAction(event: Callback<GestureEvent>): SwipeGestureHandlerOptions

Swipe手势识别成功回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Swipe手势识别成功回调。

返回值：

类型说明
SwipeGestureHandler返回当前滑动手势处理器对象。

SwipeGestureHandlerOptions

滑动事件处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
fingersnumber否

触发滑动的最少手指数，默认为1，最小为1指，最大为10指。

默认值：1

directionSwipeDirection否

触发滑动手势的滑动方向。

默认值：SwipeDirection.All

speednumber否

识别滑动的最小速度。

默认值：100VP/s

说明：

当滑动速度的值小于等于0时，会被转化为默认值。

PinchGestureHandler

捏合手势处理器对象类型。

constructor

constructor(options?: PinchGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsPinchGestureHandlerOptions否捏合手势处理器配置参数。

onActionStart

onActionStart(event: Callback<GestureEvent>): PinchGestureHandler

Pinch手势识别成功回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Pinch手势识别成功回调。

返回值：

类型说明
PinchGestureHandler返回当前拖动手势处理器对象。

onActionUpdate

onActionUpdate(event: Callback<GestureEvent>): PinchGestureHandler

Pinch手势移动过程中回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Pinch手势移动过程中回调。

返回值：

类型说明
PinchGestureHandler返回当前拖动手势处理器对象。

onActionEnd

onActionEnd(event: Callback<GestureEvent>): PinchGestureHandler

Pinch手势识别成功，手指抬起后触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Pinch手势识别成功，手指抬起后触发回调。

返回值：

类型说明
PinchGestureHandler返回当前拖动手势处理器对象。

onActionCancel

onActionCancel(event: Callback<void>): PinchGestureHandler

Pinch手势识别成功，接收到触摸取消事件触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<void>是Pinch手势识别成功，接收到触摸取消事件触发回调。

返回值：

类型说明
PinchGestureHandler返回当前拖动手势处理器对象。

PinchGestureHandlerOptions

捏合手势处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
fingersnumber否

触发捏合的最少手指数, 最小为2指，最大为5指。

默认值：2

触发手势手指可以多于fingers数目，但只有先落下的与fingers相同数目的手指参与手势计算。

distancenumber否

最小识别距离，单位为vp。

默认值：5

说明：

当识别距离的值小于等于0时，会被转化为默认值。

RotationGestureHandler

旋转手势处理器对象类型。

constructor

constructor(options?: RotationGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsRotationGestureHandlerOptions否旋转手势处理器配置参数。

onActionStart

onActionStart(event: Callback<GestureEvent>): RotationGestureHandler

Rotation手势识别成功回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Rotation手势识别成功回调。

返回值：

类型说明
RotationGestureHandler返回当前拖动手势处理器对象。

onActionUpdate

onActionUpdate(event: Callback<GestureEvent>): RotationGestureHandler

Rotation手势移动过程中回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Rotation手势移动过程中回调。

返回值：

类型说明
RotationGestureHandler返回当前拖动手势处理器对象。

onActionEnd

onActionEnd(event: Callback<GestureEvent>): RotationGestureHandler

Rotation手势识别成功，手指抬起后触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<GestureEvent>是Rotation手势识别成功，手指抬起后触发回调。

返回值：

类型说明
RotationGestureHandler返回当前拖动手势处理器对象。

onActionCancel

onActionCancel(event: Callback<void>): RotationGestureHandler

Rotation手势识别成功，接收到触摸取消事件触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<void>是Rotation手势识别成功，接收到触摸取消事件触发回调。

返回值：

类型说明
RotationGestureHandler返回当前拖动手势处理器对象。

RotationGestureHandlerOptions

旋转手势处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
fingersnumber否

触发旋转的最少手指数, 最小为2指，最大为5指。

默认值：2

触发手势手指可以多于fingers数目，但只有先落下的两指参与手势计算。

anglenumber否

触发旋转手势的最小改变度数，单位为deg。

默认值：1

说明：

当改变度数的值小于等于0或大于360时，会被转化为默认值。

GestureGroupHandler

手势组处理器对象类型。

constructor

constructor(options?: GestureGroupGestureHandlerOptions)

构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

参数：

参数名类型必填说明
optionsGestureGroupGestureHandlerOptions否手势组处理器配置参数。

onCancel

onCancel(event: Callback<void>): GestureGroupHandler

Rotation手势识别成功，接收到触摸取消事件触发回调。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
eventCallback<void>是顺序组合手势（GestureMode.Sequence）取消后触发回调。

返回值：

类型说明
GestureGroupHandler返回当前手势组处理器对象。

GestureGroupGestureHandlerOptions

手势组处理器配置参数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性类型必填描述
modeGestureMode是

设置组合手势识别模式。

默认值：GestureMode.Sequence

gesturesGestureHandler<TapGestureHandler | LongPressGestureHandler | PanGestureHandler | SwipeGestureHandler | PinchGestureHandler | RotationGestureHandler | GestureGroupHandler>[]是

手势组下需要包含的手势。

说明：

当需要为一个组件同时添加单击和双击手势时，可在组合手势中添加两个TapGesture，需要双击手势在前，单击手势在后，否则不生效。

GesturePriority枚举说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。

名称描述
NORMAL普通优先级手势。
PRIORITY高优先级手势。

鸿蒙HarmonyOS NEXT开发：设置组件绑定的手势
shudaoshanBBQ的博客
08-14 1118
用于设置组件绑定的手势。
OpenHarmony实战开发-网格元素交换案例。
2401_82546228的博客
04-19 1149
直接进行交换和删除元素会给用户带来不好的体验效果，因此需要在此过程中注入一些特色的动画来提升体验效果，本案例通过Grid组件、attributeModifier、以 及animateTo函数实现了拖拽动画和删除动画。
【HarmonyOS NEXT】如何拖拽调整列表项顺序
Mayism123的博客
03-22 956
拖拽 / 列表 / List / ListItem / 排序 / 顺序。如何拖拽调整列表项顺序，实现如下的效果。
Harmonyos NEXT开发实战：地址交换动画案列
m0_72493819的博客
07-02 993
本示例介绍使用显式动画animateTo实现左右地址交换动画。
HarmonyOS Next开发学习手册——使用NDK接口构建UI(使用动画)
maniuT的博客
07-08 1191
组件内转场通过NODE_XX_TRANSITION属性（XX包括：OPACITY、TRANSLATE、SCALE、ROTATE、MOVE）配置转场参数，在组件插入和删除时显示过渡动效（通过NODE_TRANSFORM_CENTER属性设置NODE_SCALE_TRANSITION和NODE_ROTATE_ROTATE动效的中心点坐标）。ArkUI开发框架在NDK接口主要提供属性动画，实现组件出现/消失转场。同时，可以通过Node-API桥接ArkTS侧帧动画能力，实现Native侧的动画效果。
鸿蒙5.0版开发：ArkTS组件-自定义手势判定
m0_69424697的博客
09-11 898
为组件提供自定义手势判定能力。开发者可根据需要，在手势识别期间，决定是否响应手势。
鸿蒙5.0版开发：ArkTS组件-Slider
m0_69424697的博客
11-10 1043
滑动条组件，通常用于快速调节设置值，如音量调节、亮度调节等应用场景。
鸿蒙5.0版开发：ArkTS组件-Swiper
m0_69424697的博客
11-05 498
滑块视图容器，提供子组件滑动轮播显示的能力。
鸿蒙5.0版开发：ArkTS组件-ListItem
m0_69424697的博客
11-04 918
用来展示列表具体item，必须配合List来使用。
鸿蒙NEXT版实战开发：UI框架-如何解决滚动类容器的滚动事件和手势之间的冲突？
qq_39652397的博客
12-02 315
可以通过添加并行手势绑定方法parallelGesture来处理.....
OpenHarmony实战开发-如何实现单一手势
m0_70749039的博客
04-28 1361
点击手势支持单次点击和多次点击，拥有两个可选参数：
鸿蒙手势密码
m0_60880588的博客
07-25 471
手势密码组件
鸿蒙5.0版开发：ArkTS组件基础手势（LongPressGesture）
m0_69424697的博客
09-10 1136
用于触发长按手势事件，触发长按手势的最少手指数为1，最短长按时间为500毫秒。
鸿蒙5.0开发进阶：UI框架-ArkTS组件（RotationGesture）
Androidbye的博客
12-31 705
用于触发旋转手势事件，触发旋转手势的最少手指为2指，最大为5指，最小改变度数为1度。
鸿蒙Harmony应用开发—ArkTS声明式开发（基础手势：PanGesture）
m0_64420071的博客
03-06 2011
ArkTS声明式开发（基础手势：PanGesture）
ArkTS开发系列之事件（2.8.2手势事件）
jay_chess的博客
06-25 893
【代码】ArkTS开发系列之事件（2.8.2手势事件）
鸿蒙的编程软件的介绍
FZD的博客
09-11 417
本文介绍了多款HarmonyOS开发工具的最新版本更新。DevEco Studio 5.1.1优化了构建效率，新增AI编程助手DevEco CodeGenie 6.0 Beta版，支持图片转页面和代码续写功能。Command Line Tools 5.1.1集成了开发所需工具链，ohpm-repo 5.1.5优化了三方库私有仓服务。DevEco Testing 5.1.5扩展了应用测试格式支持，HiSmartPerf 15.2.1新增了对Pad/PC设备的投屏性能分析功能，为开发者提供更完善的开发测试支持。
鸿蒙app日志存储
最新发布
llw21680的专栏
09-12 57
使用hilog --pid xxxx指令可以实现Android中logcat --pid xxxx的相同的功能。在Android中可以使用logcat --pid xxxx 获取特定进程xxxx的打印日志。在鸿蒙中也有类似的功能。
鸿蒙Next Web组件生命周期详解：从加载到销毁的全流程掌控
专注于移动开发的干货分享。提供高效解决方案、避坑指南与前沿技术解析。为开发者创造价值。
09-11 720
ArkUI的Web组件提供了9个关键生命周期回调，覆盖了从组件初始化、网页加载、进度监控到异常处理和资源清理的全过程。这些回调函数让我们能够像开了"上帝视角"一样掌控网页加载的每个细节。为了帮助你快速建立整体认识，下面这张图梳理了Web组件的核心生命周期回调及其典型触发场景：图表代码通过熟练掌握Web组件的9大生命周期回调，我们能够：- 精准控制网页加载过程 🤖 - 优化性能体验 🚀 - 有效处理异常情况 🚑 - 避免内存泄漏和资源浪费 💾终极提示：使用预加载次级资源，用。
鸿蒙原生应用开发：ArkTS语言快速上手
01-27
此外，《鸿蒙之光HarmonyOS NEXT原生应用开发入门》这本书籍和技术文档也是很好的参考资料之一，书中不仅介绍了理论知识还涵盖了大量实际案例分析帮助读者更好地理解如何运用这些技巧到具体场景当中去[^4]。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值