
OpenHarmony应用开发-绑定手势方法/基础手势
版本:v3.2 Release
绑定手势方法
为组件绑定不同类型的手势事件,并设置事件的响应方法。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
绑定手势识别
通过如下属性给组件绑定手势识别,手势识别成功后可以通过事件回调通知组件。
名称 | 参数类型 | 默认值 | 描述 |
gesture | gesture: GestureType, mask?: GestureMask | gesture: -, mask: GestureMask.Normal | 绑定手势。 - gesture: 绑定的手势类型, - mask: 事件响应设置。 |
priorityGesture | gesture: GestureType, mask?: GestureMask | gesture: -, mask: GestureMask.Normal | 绑定优先识别手势。 - gesture: 绑定的手势类型, - mask: 事件响应设置。 默认情况下,子组件优先识别通过gesture绑定的手势,当父组件配置priorityGesture时,子组件优先识别priorityGesture绑定的手势。 |
parallelGesture | gesture: GestureType, mask?: GestureMask | gesture: -, mask: GestureMask.Normal | 绑定可与子组件手势同时触发的手势。 - gesture: 绑定的手势类型。 - mask: 事件响应设置。 手势事件为非冒泡事件。父组件设置parallelGesture时,父子组件相同的手势事件都可以触发,实现类似冒泡效果。若父子组件中同时绑定单击手势事件和双击手势事件,则只响应单击手势事件。 |
GestureType
名称 | 描述 |
点击手势,支持单次点击、多次点击识别。 | |
长按手势。 | |
平移手势,滑动最小距离为5vp时识别成功。 | |
捏合手势。 | |
旋转手势。 | |
滑动手势,滑动最小速度为100vp/s时识别成功。 | |
手势识别组,多种手势组合为复合手势,支持连续识别、并行识别和互斥识别。 |
GestureMask枚举说明
名称 | 描述 |
Normal | 不屏蔽子组件的手势,按照默认手势识别顺序进行识别。 |
IgnoreInternal | 屏蔽子组件的手势,包括子组件上系统内置的手势,如子组件为List组件时,内置的滑动手势同样会被屏蔽。 |
响应手势事件
组件通过手势事件绑定不同GestureType的手势对象,各手势对象在响应手势操作的事件回调中提供手势相关信息。下面通过TapGesture手势对象的onAction事件响应点击事件,获取事件相关信息。其余手势对象的事件定义见各个手势对象章节。 若需绑定多种手势请使用 组合手势。
TapGesture事件说明
名称 | 功能描述 |
onAction((event?:GestureEvent) => void) | Tap手势识别成功回调。 |
GestureEvent对象说明
名称 | 类型 | 描述 |
repeat | boolean | 是否为重复触发事件,用于LongPressGesture手势触发场景。 |
offsetX | number | 手势事件x轴相对偏移量,单位为vp,用于PanGesture手势触发场景,从左向右滑动offsetX为正,反之为负。 |
offsetY | number | 手势事件y轴相对偏移量,单位为vp,用于PanGesture手势触发场景,从上向下滑动offsetY为正,反之为负。 |
angle | number | 用于RotationGesture手势触发场景时,表示旋转角度。 用于SwipeGesture手势触发场景时,表示滑动手势的角度,即两根手指间的线段与水平方向的夹角变化的度数。 > 说明: > 角度计算方式:滑动手势被识别到后,连接两根手指之间的线被识别为起始线条,随着手指的滑动,手指之间的线条会发生旋转,根据起始线条两端点和当前线条两端点的坐标,使用反正切函数分别计算其相对于水平方向的夹角,最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系,顺时针旋转为0到180度,逆时针旋转为-180到0度。 |
scale | number | 缩放比例,用于PinchGesture手势触发场景。 |
pinchCenterX | number | 捏合手势中心点相对于当前组件元素左上角x轴坐标,单位为vp,用于PinchGesture手势触发场景。 |
pinchCenterY | number | 捏合手势中心点相对于当前组件元素左上角y轴坐标,单位为vp,用于PinchGesture手势触发场景。 |
speed8+ | number | 滑动手势速度,即所有手指滑动的平均速度,单位为vp/秒,用于SwipeGesture手势触发场景。 |
fingerList8+ | FingerInfo[] | 触发事件的所有手指信息,用于LongPressGesture与TapGesture手势触发场景。 |
timestamp8+ | number | 事件时间戳。 |
target8+ | 触发手势事件的元素对象显示区域。 | |
source8+ | 事件输入设备。 | |
pressure9+ | number | 按压的压力大小。 |
tiltX9+ | number | 手写笔在设备平面上的投影与设备平面X轴的夹角。 |
tiltY9+ | number | 手写笔在设备平面上的投影与设备平面Y轴的夹角。 |
sourceTool9+ | 事件输入源。 |
SourceType枚举说明
名称 | 描述 |
Unknown | 未知设备。 |
Mouse | 鼠标。 |
TouchScreen | 触摸屏。 |
FingerInfo对象说明
名称 | 类型 | 描述 |
id | number | 手指的索引编号。 |
globalX | number | 相对于应用窗口左上角的x轴坐标。 |
globalY | number | 相对于应用窗口左上角的y轴坐标。 |
localX | number | 相对于当前组件元素左上角的x轴坐标。 |
localY | number | 相对于当前组件元素左上角的y轴坐标。 |
SourceTool枚举说明
名称 | 描述 |
Unknown | 未知输入源。 |
Finger | 手指输入。 |
Pen | 手写笔输入。 |
示例
基础手势
TapGesture
支持单击、双击和多次点击事件的识别。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
TapGesture(value?: { count?: number, fingers?: number })
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
count | number | 否 | 识别的连续点击次数。当设置的值小于1或不设置时,会被转化为默认值。 默认值:1 说明: 如配置多击,上一次抬起和下一次按下的超时时间为300毫秒。 |
fingers | number | 否 | 触发点击的手指数,最小为1指, 最大为10指。当设置小于1的值或不设置时,会被转化为默认值。 默认值:1 说明: 1. 当配置多指时,第一根手指按下后300毫秒内未有足够的手指数按下,手势识别失败。 2. 实际点击手指数超过配置值,手势识别失败。 |
事件
名称 | 功能描述 |
onAction(event: (event?: GestureEvent) => void) | Tap手势识别成功回调。 |
示例
LongPressGesture
用于触发长按手势事件,触发长按手势的最少手指数为1,最短长按时间为500毫秒。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
LongPressGesture(value?: { fingers?: number, repeat?: boolean, duration?: number })
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
fingers | number | 否 | 触发长按的最少手指数,最小为1指, 最大取值为10指。 默认值:1 |
repeat | boolean | 否 | 是否连续触发事件回调。 默认值:false |
duration | number | 否 | 触发长按的最短时间,单位为毫秒(ms)。 默认值:500 |
事件
名称 | 功能描述 |
onAction(event:(event?: GestureEvent) => void) | LongPress手势识别成功回调。 |
onActionEnd(event:(event?: GestureEvent) => void) | LongPress手势识别成功,手指抬起后触发回调。 |
onActionCancel(event: () => void) | LongPress手势识别成功,接收到触摸取消事件触发回调。 |
示例
PanGesture
用于触发拖动手势事件,滑动的最小距离为5vp时拖动手势识别成功。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
PanGesture(value?: { fingers?: number; direction?: PanDirection; distance?: number } | PanGestureOptions)
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
fingers | number | 否 | 触发拖动的最少手指数,最小为1指, 最大取值为10指。 默认值:1 取值范围:[1,10] 说明: 当设置的值小于1或不设置时,会被转化为默认值。 |
direction | PanDirection | 否 | 触发拖动的手势方向,此枚举值支持逻辑与(&)和逻辑或(|)运算。 默认值:PanDirection.All |
distance | number | 否 | 最小拖动识别距离,单位为vp。 默认值:5 说明: Tabs组件滑动与该拖动手势事件同时存在时,可将distance值设为1,使拖动更灵敏,避免造成事件错乱。 |
PanDirection枚举说明
名称 | 描述 |
All | 所有方向。 |
Horizontal | 水平方向。 |
Vertical | 竖直方向。 |
Left | 向左拖动。 |
Right | 向右拖动。 |
Up | 向上拖动。 |
Down | 向下拖动。 |
None | 任何方向都不可触发拖动手势事件。 |
PanGestureOptions
通过PanGestureOptions对象接口可以动态修改滑动手势识别器的属性,从而避免通过状态变量修改属性(状态变量修改会导致UI刷新)。
PanGestureOptions(value?: { fingers?: number; direction?: PanDirection; distance?: number })
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
fingers | number | 否 | 触发滑动的最少手指数,最小为1指, 最大取值为10指。 默认值:1 |
direction | PanDirection | 否 | 设置滑动方向,此枚举值支持逻辑与(&)和逻辑或(|)运算。 默认值:All |
distance | number | 否 | 最小滑动识别距离,单位为vp。 默认值:5.0 说明: > Tabs组件滑动与该拖动手势事件同时存在时,可将distance值设为1,使拖动更灵敏,避免造成事件错乱。 |
接口
名称 | 功能描述 |
setDirection(value: PanDirection) | 设置direction属性。 |
setDistance(value: number) | 设置distance属性。 |
setFingers(value: number) | 设置fingers属性。 |
事件
名称 | 功能描述 |
onActionStart(event: (event?: GestureEvent) => void) | Pan手势识别成功回调。 |
onActionUpdate(event: (event?: GestureEvent) => void) | Pan手势移动过程中回调。 |
onActionEnd(event: (event?: GestureEvent) => void) | Pan手势识别成功,手指抬起后触发回调。 |
onActionCancel(event: () => void) | Pan手势识别成功,接收到触摸取消事件触发回调。 |
示例
示意图:
向左拖动:
点击按钮修改PanGesture触发条件,双指向左下方拖动:
