
一、手势通用事件
点击事件
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
event | ClickEvent | 是 | 获得ClickEvent对象。 |
distanceThreshold | number | 是 | 点击事件移动阈值。当设置的值小于等于0时,会被转化为默认值。 默认值:2^31-1 说明:当手指的移动距离超出开发者预设的移动阈值时,点击识别失败。如果初始化为默认阈值时,手指移动超过组件热区范围,点击识别失败。 |
ClickEvent对象说明
继承于BaseEvent。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 描述 |
---|---|---|
x | number | 点击位置相对于被点击元素左边缘的X坐标。 单位:vp 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
y | number | 点击位置相对于被点击元素原始区域左上角的Y坐标。 单位:vp 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
target8+ | EventTarget | 触发事件的元素对象显示区域。 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
windowX10+ | number | 点击位置相对于应用窗口左上角的X坐标。 单位:vp 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
windowY10+ | number | 点击位置相对于应用窗口左上角的Y坐标。 单位:vp 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
displayX10+ | number | 点击位置相对于应用屏幕左上角的X坐标。 单位:vp 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
displayY10+ | number | 点击位置相对于应用屏幕左上角的Y坐标。 单位:vp 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
screenX(deprecated) | number | 点击位置相对于应用窗口左上角的X坐标。从API Version 10开始不再维护,建议使用windowX代替。 |
screenY(deprecated) | number | 点击位置相对于应用窗口左上角的Y坐标。从API Version 10开始不再维护,建议使用windowY代替。 |
preventDefault12+ | () => void | 阻止默认事件。 说明: 该接口仅支持部分组件使用,当前支持组件:RichEditor。 元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
EventTarget(8+)对象说明
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 参数类型 | 描述 |
---|---|---|
area | Area | 目标元素的区域信息。 |
示例:
1 | import { hilog } from "@kit.PerformanceAnalysisKit" |
触摸事件
onTouch
onTouch(event: (event: TouchEvent) => void): T
手指触摸动作触发该回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
event | TouchEvent | 是 | 获得TouchEvent对象。 |
返回值:
类型 | 说明 |
---|---|
T | 返回当前组件。 |
TouchEvent对象说明
继承于BaseEvent。非事件注入场景下,changedTouches是按屏幕显示刷新率重采样的点,touches是按器件刷新率报上来的点,changedTouches的数据可能会和touches里面的不相同。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 描述 |
---|---|---|
type | TouchType | 触摸事件的类型。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
touches | Array<TouchObject> | 全部手指信息。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
changedTouches | Array<TouchObject> | 当前发生变化的手指信息。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
stopPropagation | () => void | 阻塞事件冒泡。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
preventDefault12+ | () => void | 阻止默认事件,具体功能暂未实现。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
getHistoricalPoints(10+)
getHistoricalPoints(): Array
获取当前帧所有的历史点。不同设备每帧的触摸事件频率不同,且该接口只能在TouchEvent中调用,可以通过该接口获取触发onTouch时当前帧历史点的相关信息。onTouch一帧只会调用一次,若当前帧收到的TouchEvent大于1,会将该帧最后一个点通过onTouch返还,剩余点作为历史点。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 描述 |
---|---|
Array<HistoricalPoint> | 由历史点组成的数组。 |
TouchObject对象说明
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 描述 |
---|---|---|
type | TouchType | 触摸事件的类型。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
id | number | 手指唯一标识符。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
x | number | 触摸点相对于事件响应组件的左上角的X坐标。 单位:vp 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
y | number | 触摸点相对于事件响应组件的左上角的Y坐标。 单位:vp 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
windowX10+ | number | 触摸点相对于应用窗口左上角的X坐标。 单位:vp 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
windowY10+ | number | 触摸点相对于应用窗口左上角的Y坐标。 单位:vp 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
displayX10+ | number | 触摸点相对于应用屏幕左上角的X坐标。 单位:vp 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
displayY10+ | number | 触摸点相对于应用屏幕左上角的Y坐标。 单位:vp 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
screenX(deprecated) | number | 触摸点相对于应用窗口左上角的X坐标。 单位:vp 从API version 10开始不再维护,建议使用windowX代替。 |
screenY(deprecated) | number | 触摸点相对于应用窗口左上角的Y坐标。 单位:vp 从API version 10开始不再维护,建议使用windowY代替。 |
HistoricalPoint(10+)对象说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 描述 |
---|---|---|
touchObject | TouchObject | 历史点对应触摸事件的基础信息。 |
size | number | 历史点对应触摸事件的手指与屏幕的触摸区域大小。默认值:0 |
force | number | 历史点对应触摸事件的压力大小。默认值:0取值范围:[0,65535),压力越大值越大。 |
timestamp | number | 历史点对应触摸事件的时间戳。触发事件时距离系统启动的时间间隔。单位:ns |
示例
该示例通过按钮设置了触摸事件,手指点击按钮时可获取触摸事件的相关参数。
1 | // 触摸事件 |
无障碍悬浮事件
在开启无障碍模式后,Touch事件会转换为无障碍悬浮事件。
onAccessibilityHover
onAccessibilityHover(callback: AccessibilityCallback): T
开启无障碍模式后,单指触摸绑定该回调的组件时触发该回调。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
callback | AccessibilityCallback | 是 | 提供开启无障碍模式后的无障碍悬浮回调事件,当开启无障碍模式后,单指触摸绑定该回调的组件时触发该回调。 |
返回值:
类型 | 说明 |
---|---|
T | 返回当前组件。 |
AccessibilityCallback
type AccessibilityCallback = (isHover: boolean, event: AccessibilityHoverEvent) => void
提供开启无障碍模式后的无障碍悬浮回调事件类型。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
isHover | boolean | 是 | 表示开启无障碍模式后,手指是否悬浮在组件上,手指进入时为true, 退出时为false。 |
event | AccessibilityHoverEvent | 是 | 获得AccessibilityHoverEvent对象。 |
AccessibilityHoverEvent对象说明
继承于BaseEvent。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 属性类型 | 描述 |
---|---|---|
type | AccessibilityHoverType | 无障碍悬浮动作。 |
x | number | 手指位置相对于当前组件左上角的x轴坐标。单位:vp |
y | number | 手指位置相对于当前组件左上角的y轴坐标。单位:vp |
windowX | number | 手指位置相对于应用窗口左上角的x轴坐标。单位:vp |
windowY | number | 手指位置相对于应用窗口左上角的y轴坐标。单位:vp |
displayX | number | 手指位置相对于应用屏幕左上角的x轴坐标。单位:vp |
displayY | number | 手指位置相对于应用屏幕左上角的y轴坐标。单位:vp |
AccessibilityHoverType
定义无障碍悬浮类型。
名称 | 值 | 描述 |
---|---|---|
HOVER_ENTER | 0 | 手指按下时触发。 |
HOVER_MOVE | 1 | 触摸移动时触发。 |
HOVER_EXIT | 2 | 抬手触发。 |
HOVER_CANCEL | 3 | 打断取消当前触发的事件。 |
示例
1 | // xxx.ets |
二、通用属性
动态手势设置
动态设置组件绑定的手势,支持开发者在属性设置时使用if/else语法。
gestureModifier
gestureModifier(modifier: GestureModifier)
动态设置组件绑定的手势。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
modifier | GestureModifier | 是 | 在当前组件上,动态设置组件绑定的手势,支持使用if/else语法。modifier: 手势修改器,开发者需要自定义class实现GestureModifier接口。 |
GestureModifier
开发者需要自定义class实现GestureModifier接口。
applyGesture
applyGesture(event: UIGestureEvent): void
组件需要绑定的手势。
开发者可根据需要自定义实现这个方法,对组件设置需要绑定的手势,支持使用if/else语法进行动态设置。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
参数:
参数名 | 类型 | 说明 |
---|---|---|
event | UIGestureEvent | UIGestureEvent对象,用于设置组件需要绑定的手势。 |
示例
该示例通过gestureModifier动态设置组件绑定的手势。
1 | class MyButtonModifier implements GestureModifier { |
触摸热区设置
适用于支持通用点击事件、通用触摸事件、通用手势处理的组件。
responseRegion
responseRegion(value: Array
设置一个或多个触摸热区。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | Array<Rectangle> | Rectangle | 是 | 设置一个或多个触摸热区,包括位置和大小。默认触摸热区为整个组件,默认值:{x:0,y:0,width:’100%’,height:’100%’} 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
Rectangle对象说明
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
x | Length | 否 | 触摸点相对于组件左上角的x轴坐标。默认值:0vp |
y | Length | 否 | 触摸点相对于组件左上角的y轴坐标。默认值:0vp |
width | Length | 否 | 触摸热区的宽度。默认值:’100%’ |
height | Length | 否 | 触摸热区的高度。默认值:’100%’ |
说明
x和y可以设置正负值百分比。当x设置为’100%’时表示热区往右偏移组件本身宽度大小,当x设置为’-100%’时表示热区往左偏移组件本身宽度大小。当y设置为’100%’时表示热区往下偏移组件本身高度大小,当y设置为’-100%’时表示热区往上偏移组件本身高度大小。
width和height只能设置正值百分比。width:’100%’表示热区宽度设置为该组件本身的宽度。比如组件本身宽度是100vp,那么’100%’表示热区宽度也为100vp。height:’100%’表示热区高度设置为该组件本身的高度。
百分比相对于组件自身宽高进行计算。
示例
该示例通过responseRegion对按钮设置触摸热区响应点击事件。
1 | // 触摸热区设置 |
触摸测试控制
设置组件的触摸测试类型。ArkUI开发框架在处理触屏事件时,会在触屏事件触发前,进行按压点和组件区域的触摸测试来收集需要响应触屏事件的组件,然后基于触摸测试结果分发相应的触屏事件。hitTestBehavior属性可以设置不同的触摸测试响应模式,影响组件的触摸测试收集结果,最终影响后续的触屏事件分发,具体影响参考HitTestMode枚举说明。
说明
- 从API Version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
- 当Stack组件中有多个节点触摸区域重叠时,如两个节点,默认只会对显示在最上层的节点做触摸测试,若需要显示在下层的节点触发触摸测试,请给显示在上层的节点设置hitTestBehavior为HitTestMode.Transparent。
hitTestBehavior
hitTestBehavior(value: HitTestMode)
设置组件的触摸测试类型。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | HitTestMode | 是 | 设置当前组件的触摸测试类型。默认值: HitTestMode.Default |
HitTestMode枚举说明
名称 | 枚举值 | 描述 |
---|---|---|
Default | 0 | 默认触摸测试效果,自身和子节点都响应触摸测试,但会阻塞兄弟节点的触摸测试。不会影响祖先节点的触摸测试。 |
Block | 1 | 自身响应触摸测试,阻塞子节点和兄弟节点的触摸测试。会阻塞祖先节点的触摸测试。 |
Transparent | 2 | 自身和子节点都响应触摸测试,不会阻塞兄弟节点的触摸测试。不会影响祖先节点的触摸测试。 |
None | 3 | 自身不响应触摸测试,不会阻塞子节点和兄弟节点的触摸测试。不会影响祖先节点的触摸测试。 |
示例
该示例通过设置不同的HitTestMode值演示了Block和Transparent的触摸类型效果。
1 | // 触摸测试控制 |
三、手势处理
onClick > Gesture 触发,onClick 会先吞噬所有触摸的事件
绑定手势方法
通过如下属性给组件绑定手势识别,手势识别成功后可以通过事件回调通知组件。
可以通过触摸热区指定可识别手势的区域。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 参数类型 | 默认值 | 描述 |
---|---|---|---|
gesture | gesture: GestureType,mask?: GestureMask | gesture: -,mask: GestureMask.Normal | 绑定手势。- gesture: 绑定的手势类型。- mask: 事件响应设置。 |
priorityGesture | gesture: GestureType,mask?: GestureMask | gesture: -,mask: GestureMask.Normal | 绑定优先识别手势。- gesture: 绑定的手势类型。- mask: 事件响应设置。1、默认情况下,子组件优先识别通过gesture绑定的手势,当父组件配置priorityGesture时,父组件优先识别priorityGesture绑定的手势。2、长按手势时,设置触发长按的最短时间小的组件会优先响应,会忽略priorityGesture设置。 |
parallelGesture | gesture: GestureType,mask?: GestureMask | gesture: -,mask: GestureMask.Normal | 绑定可与子组件手势同时触发的手势。- gesture: 绑定的手势类型。- mask: 事件响应设置。手势事件为非冒泡事件。父组件设置parallelGesture时,父子组件相同的手势事件都可以触发,实现类似冒泡效果。 |
GestureType
元服务API: 从API version 12开始,该接口支持在元服务中使用。
名称 | 描述 |
---|---|
TapGesture | 点击手势,支持单次点击、多次点击识别。 |
LongPressGesture | 长按手势。 |
PanGesture | 平移手势,滑动最小距离为5vp时识别成功。 |
PinchGesture | 捏合手势。 |
RotationGesture | 旋转手势。 |
SwipeGesture | 滑动手势,滑动最小速度为100vp/s时识别成功。 |
GestureGroup | 手势识别组,多种手势组合为复合手势,支持连续识别、并行识别和互斥识别。 |
GestureMask枚举说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 描述 |
---|---|
Normal | 不屏蔽子组件的手势,按照默认手势识别顺序进行识别。 |
IgnoreInternal | 屏蔽子组件的手势,包括子组件上系统内置的手势,如子组件为List组件时,内置的滑动手势同样会被屏蔽。 若父子组件区域存在部分重叠,则只会屏蔽父子组件重叠的部分。 |
响应手势事件
组件通过手势事件绑定不同GestureType的手势对象,各手势对象在响应手势操作的事件回调中提供手势相关信息。下面通过TapGesture手势对象的onAction事件响应点击事件,获取事件相关信息。其余手势对象的事件定义见各个手势对象章节。 若需绑定多种手势请使用 组合手势。
TapGesture事件说明
名称 | 功能描述 |
---|---|
onAction((event:GestureEvent) => void) | Tap手势识别成功回调。 |
GestureEvent对象说明
继承于BaseEvent。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
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[] | 输入源为触屏产生的手势,fingerList中会包含触发事件的所有触点信息;由鼠标发起的手势,fingerList中只会有一条记录;触摸板的事件大类与鼠标一致,所以由触摸板发起的手势,fingerList只会携带一条记录。说明:手指索引编号与位置对应,即fingerList[index]的id为index。先按下且未参与当前手势触发的手指在fingerList中对应位置为空。 |
velocityX10+ | number | 用于PanGesture手势中,获取当前手势的x轴方向速度。坐标轴原点为屏幕左上角,分正负方向速度,从左往右为正,反之为负。单位为vp/s。 |
velocityY10+ | number | 用于PanGesture手势中,获取当前手势的y轴方向速度。坐标轴原点为屏幕左上角,分正负方向速度,从上往下为正,反之为负。单位为vp/s。 |
velocity10+ | number | 用于PanGesture手势中,获取当前手势的主方向速度。为xy轴方向速度的平方和的算术平方根。单位为vp/s。 |
SourceType枚举说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 描述 |
---|---|
Unknown | 未知设备。 |
Mouse | 鼠标。 |
TouchScreen | 触摸屏。 |
FingerInfo对象说明(8+)
名称 | 类型 | 描述 |
---|---|---|
id | number | 手指的索引编号。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
globalX | number | 相对于应用窗口左上角的x轴坐标,单位为vp。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
globalY | number | 相对于应用窗口左上角的y轴坐标,单位为vp。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
localX | number | 相对于当前组件元素原始区域左上角的x轴坐标,单位为vp。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
localY | number | 相对于当前组件元素原始区域左上角的y轴坐标,单位为vp。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
displayX12+ | number | 相对于屏幕左上角的x轴坐标,单位为vp。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
displayY12+ | number | 相对于屏幕左上角的y轴坐标,单位为vp。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
SourceTool枚举说明(9+)
名称 | 描述 |
---|---|
Unknown | 未知输入源。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
Finger | 手指输入。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
Pen | 手写笔输入。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
Mouse12+ | 鼠标输入。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
Touchpad12+ | 触控板输入。触控板单指输入被视为鼠标输入操作。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
Joystick12+ | 手柄输入。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
示例
该示例通过配置priorityGesture和parallelGesture分别实现了父组件优先识别手势和父子组件同时触发手势。
1 | // 绑定手势方法 |
TapGesture
支持单击、双击和多次点击事件的识别。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
TapGesture(value?: TapGestureParameters)
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
value | TapGestureParameters | 否 | 点击手势的相关参数。 |
TapGestureParameters(12+)对象说明
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
count | number | 否 | 识别的连续点击次数。当设置的值小于1或不设置时,会被转化为默认值。默认值:1说明:1. 当配置多击时,上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。2. 当上次点击的位置与当前点击的位置距离超过60vp时,手势识别失败。在多指情况下,点击的位置为所有参与手势响应手指的平均位置。 |
fingers | number | 否 | 触发点击的手指数,最小为1指, 最大为10指。当设置小于1的值或不设置时,会被转化为默认值。默认值:1说明:1. 当配置多指时,第一根手指按下后300毫秒内未有足够的手指数按下,手势识别失败;手指抬起时,抬起后剩余的手指数小于阈值时开始计时,如300ms内未全部抬起则手势识别失败。2. 实际点击手指数超过配置值,手势识别成功。 |
distanceThreshold | number | 否 | 点击手势移动阈值。当设置的值小于等于0或不设置时,会被转化为默认值。默认值:2^31-1说明:当手指的移动距离超出开发者预设的移动阈值时,点击识别失败。如果初始化为默认阈值时,手指移动超过组件热区范围,点击识别失败。 |
事件
名称 | 功能描述 |
---|---|
onAction(event: (event: GestureEvent) => void) | Tap手势识别成功回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
属性
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag11+ | string | 设置Tap手势标志,用于自定义手势判定时区分绑定的手势。 |
示例
该示例通过TapGesture实现了双击手势的识别。
1 | // xxx.ets |
LongPressGesture
用于触发长按手势事件,触发长按手势的最少手指数为1,最短长按时间为500毫秒。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
LongPressGesture(value?: { fingers?: number, repeat?: boolean, duration?: number })
当组件默认支持可拖拽时,如Text、TextInput、TextArea、HyperLink、Image和RichEditor等组件。长按手势与拖拽会出现冲突,事件优先级如下:
长按触发时间 < 500ms,长按事件优先拖拽事件响应。
长按触发时间 >= 500ms,拖拽事件优先长按事件响应。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
fingers | number | 否 | 触发长按的最少手指数,最小为1指, 最大取值为10指。默认值:1说明:手指按下后若发生超过15px的移动,则判定当前长按手势识别失败。 |
repeat | boolean | 否 | 是否连续触发事件回调。默认值:false |
duration | number | 否 | 触发长按的最短时间,单位为毫秒(ms)。默认值:500说明:设置小于等于0时,按照默认值500处理。 |
事件
名称 | 功能描述 |
---|---|
onAction(event:(event: GestureEvent) => void) | LongPress手势识别成功回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionEnd(event:(event: GestureEvent) => void) | LongPress手势识别成功,最后一根手指抬起后触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionCancel(event: () => void) | LongPress手势识别成功,接收到触摸取消事件触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
属性
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag11+ | string | 设置LongPress手势标志,用于自定义手势判定时区分绑定的手势。 |
示例
1 | // 长按手势 |
PanGesture
滑动手势事件,当滑动的最小距离达到设定的最小值时触发滑动手势事件。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
PanGesture(value?: { fingers?: number, direction?: PanDirection, distance?: number } | PanGestureOptions)
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
fingers | number | 否 | 用于指定触发拖动的最少手指数,最小为1指, 最大取值为10指。默认值:1取值范围:[1,10]说明:当设置的值小于1或不设置时,会被转化为默认值。 |
direction | PanDirection | 否 | 用于指定触发拖动的手势方向,此枚举值支持逻辑与(&)和逻辑或(|)运算。默认值:PanDirection.All |
distance | number | 否 | 用于指定触发拖动手势事件的最小拖动距离,单位为vp。默认值:5说明:Tabs组件滑动与该拖动手势事件同时存在时,可将distance值设为1,使拖动更灵敏,避免造成事件错乱。当设定的值小于0时,按默认值5处理。 |
PanDirection枚举说明
与SwipeDirection不同,PanDirection没有角度限制。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 描述 |
---|---|
All | 所有方向。 |
Horizontal | 水平方向。 |
Vertical | 竖直方向。 |
Left | 向左拖动。 |
Right | 向右拖动。 |
Up | 向上拖动。 |
Down | 向下拖动。 |
None | 任何方向都不可触发拖动手势事件。 |
PanGestureOptions
通过PanGestureOptions对象接口可以动态修改平移手势识别器的属性,从而避免通过状态变量修改属性(状态变量修改会导致UI刷新)。
PanGestureOptions(value?: { fingers?: number, direction?: PanDirection, distance?: number })
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
fingers | number | 否 | 用于指定触发滑动的最少手指数,最小为1指, 最大取值为10指。默认值:1 |
direction | PanDirection | 否 | 用于指定设置滑动方向,此枚举值支持逻辑与(&)和逻辑或(|)运算。默认值:PanDirection.All |
distance | number | 否 | 用于指定触发拖动手势事件的最小拖动距离,单位为vp。默认值:5说明:Tabs组件滑动与该拖动手势事件同时存在时,可将distance值设为1,使拖动更灵敏,避免造成事件错乱。当设定的值小于0时,按默认值5处理。建议设置合理的拖动距离,拖动距离设置过大时会导致滑动不跟手(响应时延慢)的问题。 |
接口
名称 | 功能描述 |
---|---|
setDirection(value: PanDirection) | 设置direction属性。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
setDistance(value: number) | 设置distance属性。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
setFingers(value: number) | 设置fingers属性。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
getDirection()12+: PanDirection | 获取direction属性。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
事件
名称 | 功能描述 |
---|---|
onActionStart(event: (event: GestureEvent) => void) | Pan手势识别成功回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionUpdate(event: (event: GestureEvent) => void) | Pan手势移动过程中回调。fingerList为多根手指时,该回调监听每次只会更新一根手指的位置信息。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionEnd(event: (event: GestureEvent) => void) | Pan手势识别成功,手指抬起后触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionCancel(event: () => void) | Pan手势识别成功,接收到触摸取消事件触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
属性
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag11+ | string | 设置Pan手势标志,用于自定义手势判定时区分绑定的手势。 |
示例
该示例通过PanGesture实现了单指/双指滑动手势的识别。
1 |
|
示意图:
向左滑动:
点击按钮修改PanGesture触发条件,双指向左下方滑动:
PinchGesture
用于触发捏合手势,触发捏合手势的最少手指为2指,最大为5指,最小识别距离为5vp。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
PinchGesture(value?: { fingers?: number, distance?: number })
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
fingers | number | 否 | 触发捏合的最少手指数, 最小为2指,最大为5指。默认值:2触发手势手指可以多于fingers数目,但只有先落下的与fingers相同数目的手指参与手势计算。 |
distance | number | 否 | 最小识别距离,单位为vp。默认值:5说明:当识别距离的值小于等于0时,会被转化为默认值。 |
事件
名称 | 功能描述 |
---|---|
onActionStart(event:(event: GestureEvent) => void) | Pinch手势识别成功回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionUpdate(event:(event: GestureEvent) => void) | Pinch手势移动过程中回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionEnd(event:(event: GestureEvent) => void) | Pinch手势识别成功,手指抬起后触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionCancel(event: () => void) | Pinch手势识别成功,接收到触摸取消事件触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
属性
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag11+ | string | 设置Pinch手势标志,用于自定义手势判定时区分绑定的手势。 |
示例
该示例通过配置PinchGesture实现了三指捏合手势的识别。
1 | // 三指捏合手势 |
RotationGesture
用于触发旋转手势事件,触发旋转手势的最少手指为2指,最大为5指,最小改变度数为1度。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
RotationGesture(value?: { fingers?: number, angle?: number })
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
fingers | number | 否 | 触发旋转的最少手指数, 最小为2指,最大为5指。默认值:2触发手势手指可以多于fingers数目,但只有先落下的两指参与手势计算。 |
angle | number | 否 | 触发旋转手势的最小改变度数,单位为deg。默认值:1说明:当改变度数的值小于等于0或大于360时,会被转化为默认值。 |
事件
名称 | 功能描述 |
---|---|
onActionStart(event:(event: GestureEvent) => void) | Rotation手势识别成功回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionUpdate(event:(event: GestureEvent) => void) | Rotation手势移动过程中回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionEnd(event:(event: GestureEvent) => void) | Rotation手势识别成功,手指抬起后触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
onActionCancel(event: () => void) | Rotation手势识别成功,接收到触摸取消事件触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
属性
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag11+ | string | 设置Rotation手势标志,用于自定义手势判定时区分绑定的手势。 |
示例
该示例通过配置RotationGesture实现了双指旋转手势的识别。
1 | // 旋转手势 |
SwipeGesture
用于触发滑动事件,滑动速度大于100vp/s时可识别成功。
说明
从API Version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
SwipeGesture(value?: { fingers?: number, direction?: SwipeDirection, speed?: number })
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名称 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
fingers | number | 否 | 触发滑动的最少手指数,默认为1,最小为1指,最大为10指。默认值:1 |
direction | SwipeDirection | 否 | 触发滑动手势的滑动方向。默认值:SwipeDirection.All |
speed | number | 否 | 识别滑动的最小速度。默认值:100VP/s说明:当滑动速度的值小于等于0时,会被转化为默认值。 |
SwipeDirection枚举说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 描述 |
---|---|
All | 所有方向。 |
Horizontal | 水平方向,手指滑动方向与x轴夹角小于45度时触发。 |
Vertical | 竖直方向,手指滑动方向与y轴夹角小于45度时触发。 |
None | 任何方向均不可触发。 |
事件
名称 | 功能描述 |
---|---|
onAction(event:(event: GestureEvent) => void) | Swipe手势识别成功回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
属性
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag11+ | string | 设置Swipe手势标志,用于自定义手势判定时区分绑定的手势。 |
示例
该示例通过配置SwipeGesture实现了滑动手势的识别。
1 | // 清扫手势 |
组合手势
手势识别组合,即多种手势组合为复合手势,支持连续识别、并行识别和互斥识别。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
接口
GestureGroup(mode: GestureMode, …gesture: GestureType[])
元服务API: 从API version 11开始,该接口支持在元服务中使用。
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
mode | GestureMode | 是 | 设置组合手势识别模式。默认值:GestureMode.Sequence |
gesture | TapGesture| LongPressGesture| PanGesture| PinchGesture| RotationGesture| SwipeGesture| GestureGroup | 否 | 设置1个或者多个基础手势类型时,这些手势会被识别为组合手势。若此参数不填则组合手势识别功能不生效。说明:当需要为一个组件同时添加单击和双击手势时,可在组合手势中添加两个TapGesture,需要双击手势在前,单击手势在后,否则不生效。 |
GestureMode枚举说明
元服务API: 从API version 11开始,该接口支持在元服务中使用。
名称 | 描述 |
---|---|
Sequence | 顺序识别,按照手势的注册顺序识别手势,直到所有手势识别成功。若有一个手势识别失败,后续手势识别均失败。顺序识别手势组仅有最后一个手势可以响应onActionEnd。 |
Parallel | 并发识别,注册的手势同时识别,直到所有手势识别结束,手势识别互相不影响。 |
Exclusive | 互斥识别,注册的手势同时识别,若有一个手势识别成功,则结束手势识别。 |
事件
名称 | 功能描述 |
---|---|
onCancel(event: () => void) | 顺序组合手势(GestureMode.Sequence)取消后触发回调。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
示例
该示例通过配置GestureGroup实现了长按和拖动的组合手势顺序识别。
1 |
|
示意图:
按顺序首先触发长按事件:
按顺序首先触发长按事件,长按事件识别结束之后,其次触发拖动事件,向右下方拖动:
自定义手势判定
为组件提供自定义手势判定能力。开发者可根据需要,在手势识别期间,决定是否响应手势。
说明
从API Version 11开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
onGestureJudgeBegin
onGestureJudgeBegin(callback: (gestureInfo: GestureInfo, event: BaseGestureEvent) => GestureJudgeResult): T
元服务API: 从API version 12开始,该接口支持在元服务中使用。
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
callback | (gestureInfo: GestureInfo, event: BaseGestureEvent) => GestureJudgeResult | 是 | 给组件绑定自定义手势判定回调,当绑定到该组件的手势被接受时,会触发用户定义的回调来获取结果。 |
返回值:
类型 | 说明 |
---|---|
T | 返回当前组件。 |
GestureJudgeResult(11+)
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 描述 |
---|---|
CONTINUE | 不影响系统手势判定流程。 |
REJECT | 对于用户自定义的手势判定结果为失败。 |
GestureInfo对象说明
元服务API: 从API version 12开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
tag | string | 手势标记。说明:如果未设置事件标识tag属性的情况下,此处tag不返回或者返回undefined。 |
type | GestureControl.GestureType | 手势类型。说明:当手势为未暴露类型的系统内置手势事件时,type的值为-1。 |
isSystemGesture | boolean | 判断当前手势是否是组件自带的手势。默认值:false |
GestureType(11+)
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 值 | 描述 |
---|---|---|
TAP_GESTURE | 0 | 点击手势 |
LONG_PRESS_GESTURE | 1 | 长按手势 |
PAN_GESTURE | 2 | 拖动手势 |
PINCH_GESTURE | 3 | 捏合手势 |
SWIPE_GESTURE | 4 | 滑动手势 |
ROTATION_GESTURE | 5 | 旋转手势 |
DRAG | 6 | 拖拽 |
CLICK | 7 | 点击 |
BaseEvent对象说明
名称 | 类型 | 描述 |
---|---|---|
target | EventTarget | 触发手势事件的元素对象显示区域。卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
timestamp | number | 事件时间戳,触发事件时距离系统启动的时间间隔。单位:ns卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
source | SourceType | 事件输入设备。卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
pressure | number | 按压的压力大小。默认值:0取值范围:[0,1],典型值0.913168,压感大小与数值正相关。卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
tiltX | number | 手写笔在设备平面上的投影与设备平面X轴的夹角。卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
tiltY | number | 手写笔在设备平面上的投影与设备平面Y轴的夹角。卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
sourceTool | SourceTool | 事件输入源。卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
axisHorizontal12+ | number | 水平轴值。说明:当前仅在由鼠标滚轮或者触控板双指滑动场景下触发的Pan手势中可以获取。卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
axisVertical12+ | number | 垂直轴值。说明:当前仅在由鼠标滚轮或者触控板双指滑动场景下触发的Pan手势中可以获取。卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
getModifierKeyState12+ | (Array |
获取功能键按压状态。报错信息请参考以下错误码。支持功能键 ‘Ctrl’|’Alt’|’Shift’|’Fn’,设备外接带Fn键的键盘不支持Fn键查询。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
deviceId12+ | number | 触发当前事件的输入设备ID。卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。元服务API: 从API version 12开始,该接口支持在元服务中使用。 |
错误码:
以下错误码详细介绍请参考通用错误码。
错误码ID | 错误信息 |
---|---|
401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. |
BaseGestureEvent对象说明
继承于BaseEvent。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
fingerList | [FingerInfo] | 触发事件的所有手指信息。 |
TapGestureEvent对象说明
继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
LongPressGestureEvent对象说明
继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
repeat | boolean | 是否为重复触发事件。 |
PanGestureEvent对象说明
继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
offsetX | number | 手势事件x轴相对当前组件元素原始区域的偏移量,单位为vp,从左向右滑动offsetX为正,反之为负。 |
offsetY | number | 手势事件y轴相对当前组件元素原始区域的偏移量,单位为vp,从上向下滑动offsetY为正,反之为负。 |
velocityX | number | 获取当前手势的x轴方向速度。坐标轴原点为屏幕左上角,分正负方向速度,从左往右为正,反之为负。单位为vp/s。 |
velocityY | number | 获取当前手势的y轴方向速度。坐标轴原点为屏幕左上角,分正负方向速度,从上往下为正,反之为负。单位为vp/s。 |
velocity | number | 获取当前的主方向速度。为xy轴方向速度的平方和的算术平方根。单位为vp/s。 |
PinchGestureEvent对象说明
元服务API: 从API version 12开始,该接口支持在元服务中使用。
继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。
名称 | 类型 | 描述 |
---|---|---|
scale | number | 缩放比例。 |
pinchCenterX | number | 捏合手势中心点相对于当前组件元素原始区域左上角x轴坐标,单位为vp。 |
pinchCenterY | number | 捏合手势中心点相对于当前组件元素原始区域左上角y轴坐标,单位为vp。 |
RotationGestureEvent对象说明
元服务API: 从API version 12开始,该接口支持在元服务中使用。
继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。
名称 | 类型 | 描述 |
---|---|---|
angle | number | 表示旋转角度,单位为deg。说明:角度计算方式:滑动手势被识别到后,连接两根手指之间的线被识别为起始线条,随着手指的滑动,手指之间的线条会发生旋转,根据起始线条两端点和当前线条两端点的坐标,使用反正切函数分别计算其相对于水平方向的夹角,最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系,顺时针旋转为0到180度,逆时针旋转为-180到0度。 |
SwipeGestureEvent对象说明
继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
名称 | 类型 | 描述 |
---|---|---|
angle | number | 表示滑动手势的角度,即两根手指间的线段与水平方向的夹角变化的度数,单位为deg。说明:角度计算方式:滑动手势被识别到后,连接两根手指之间的线被识别为起始线条,随着手指的滑动,手指之间的线条会发生旋转,根据起始线条两端点和当前线条两端点的坐标,使用反正切函数分别计算其相对于水平方向的夹角,最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系,顺时针旋转为0到180度,逆时针旋转为-180到0度。 |
speed | number | 滑动手势速度,即所有手指相对当前组件元素原始区域滑动的平均速度,单位为vp/s。 |
示例
示例1(自定义手势判定)
该示例通过配置onGestureJudgeBegin实现了对长按、滑动和拖动手势的自定义判定。
1 | import { promptAction } from '@kit.ArkUI'; |
示例2(自定义区域手势判定)
该示例通过配置onGestureJudgeBegin判定区域决定长按手势和拖拽是否响应。
1 | import { promptAction } from '@kit.ArkUI'; |
手势拦截增强
为组件提供手势拦截能力。开发者可根据需要,将系统内置手势和比其优先级高的手势做并行化处理,并可以动态控制手势事件的触发。
说明
从API Version 12开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
shouldBuiltInRecognizerParallelWith
shouldBuiltInRecognizerParallelWith(callback: ShouldBuiltInRecognizerParallelWithCallback): T
提供系统内置手势与响应链上其他组件的手势设置并行关系的回调事件。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
callback | ShouldBuiltInRecognizerParallelWithCallback | 是 | 提供系统内置手势与响应链上其他组件的手势设置并行关系的回调事件,当该组件做触摸碰撞测试时,会触发用户定义的回调来形成手势并行关系。 |
返回值:
类型 | 说明 |
---|---|
T | 返回当前组件。 |
ShouldBuiltInRecognizerParallelWithCallback
type ShouldBuiltInRecognizerParallelWithCallback = (current: GestureRecognizer, others: Array
提供系统内置手势与响应链上其他组件的手势设置并行关系的回调事件类型。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
current | GestureRecognizer | 是 | 当前组件的系统内置手势识别器,当前版本只提供内置的PAN_GESTURE类型的手势识别器。 |
others | Array<GestureRecognizer> | 是 | 响应链上更高优先级的其他组件相同类别的手势识别器。 |
返回值:
类型 | 说明 |
---|---|
GestureRecognizer | 与current识别器绑定并行关系的某个手势识别器。 |
GestureRecognizer
手势识别器对象。
getTag
getTag(): string
返回当前手势识别器的tag。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
string | 当前手势识别器的tag。 |
getType
getType(): GestureControl.GestureType
返回当前手势识别器的类型。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
GestureControl.GestureType | 当前手势识别器的类型。 |
isBuiltIn
isBuiltIn(): boolean
返回当前手势识别器是否为系统内置手势。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
boolean | 当前手势识别器是否为系统内置手势。 |
setEnabled
setEnabled(isEnabled: boolean): void
设置当前手势识别器的使能状态。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
isEnabled | boolean | 是 | 手势识别器的使能状态。 |
isEnabled
isEnabled(): boolean
返回当前手势识别器的使能状态。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
boolean | 当前手势识别器的使能状态。 |
getState
getState(): GestureRecognizerState
返回当前手势识别器的状态。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
GestureRecognizerState | 当前手势识别器的状态。 |
getEventTargetInfo
getEventTargetInfo(): EventTargetInfo
返回当前手势识别器对应组件的信息。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
EventTargetInfo | 当前手势识别器对应组件的信息。 |
isValid
isValid(): boolean;
返回当前手势识别器是否有效。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
boolean | 当前手势识别器是否有效。当该识别器绑定的组件被析构或者该识别器不在响应链上时返回false。 |
GestureRecognizerState
定义手势识别器状态。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
名称 | 值 | 描述 |
---|---|---|
READY | 0 | 准备状态。 |
DETECTING | 1 | 检测状态。 |
PENDING | 2 | 等待状态。 |
BLOCKED | 3 | 阻塞状态。 |
SUCCESSFUL | 4 | 成功状态。 |
FAILED | 5 | 失败状态。 |
EventTargetInfo
手势识别器对应组件的信息。
getId
getId(): string
返回当前组件的组件标识。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
string | 当前组件的组件标识。 |
ScrollableTargetInfo
手势识别器对应的滚动类容器组件的信息,继承于EventTargetInfo。
isBegin
isBegin(): boolean
返回当前滚动类容器组件是否在顶部,如果为Swiper组件且在循环模式下返回false。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
boolean | 当前滚动类容器组件是否在顶部。 |
isEnd
isEnd(): boolean
返回当前滚动类容器组件是否在底部,如果为Swiper组件且在循环模式下返回false。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
boolean | 当前滚动类容器组件是否在底部。 |
PanRecognizer
拖动手势识别器对象,继承于GestureRecognizer。
getPanGestureOptions
getPanGestureOptions(): PanGestureOptions
返回当前拖动手势识别器的属性。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
PanGestureOptions | 当前拖动手势识别器的属性。 |
onGestureRecognizerJudgeBegin(13+)
onGestureRecognizerJudgeBegin(callback: GestureRecognizerJudgeBeginCallback, exposeInnerGesture: boolean): T
给组件绑定自定义手势识别器判定回调。
新增exposeInnerGesture参数作为是否将回调暴露给ArkUI原生组合组件的内置组件的标识,当该标识置为true时,将回调暴露给ArkUI原生组合组件的内置组件。
对于不需要将回调暴露给ArkUI原生组合组件内置组件的场景,建议采用原有onGestureRecognizerJudgeBegin接口。若要求将回调暴露给ArkUI原生组合组件的内置组件,建议使用该接口并将exposeInnerGesture设置为true。
元服务API: 从API version 13开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
callback | GestureRecognizerJudgeBeginCallback | 是 | 给组件绑定自定义手势识别器判定回调,当绑定到该组件的手势被接受时,会触发用户定义的回调来获取结果。 |
exposeInnerGesture | boolean | 是 | 暴露内部手势标识。默认值:false说明:如果是组合组件,此参数设置true,则会在current参数回调出组合组件内部的手势识别器。当前仅支持Tabs,其他组件请不要设置此参数。设置为false时,功能与原接口onGestureRecognizerJudgeBegin相同。 |
onGestureRecognizerJudgeBegin
onGestureRecognizerJudgeBegin(callback: GestureRecognizerJudgeBeginCallback): T
给组件绑定自定义手势识别器判定回调。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
callback | GestureRecognizerJudgeBeginCallback | 是 | 给组件绑定自定义手势识别器判定回调,当绑定到该组件的手势被接受时,会触发用户定义的回调来获取结果。 |
返回值:
类型 | 说明 |
---|---|
T | 返回当前组件。 |
GestureRecognizerJudgeBeginCallback
type GestureRecognizerJudgeBeginCallback = (event: BaseGestureEvent, current: GestureRecognizer, recognizers: Array
自定义手势识别器判定回调类型。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
event | BaseGestureEvent | 是 | 当前基础手势事件信息。 |
current | GestureRecognizer | 是 | 当前即将要响应的识别器对象。 |
others | Array<GestureRecognizer> | 是 | 响应链上的其他手势识别器对象。 |
返回值:
类型 | 说明 |
---|---|
GestureJudgeResult | 手势是否裁决成功的判定结果。 |
示例
示例1(嵌套滚动)
该示例通过shouldBuiltInrecognizerParallelWith和onGestureRecognizerJudgeBegin实现了嵌套滚动的功能。内部组件优先响应滑动手势,当内部组件滑动至顶部或底部时,外部组件能够接替滑动。
1 |
|
示例2(嵌套场景下拦截内部容器手势)
本示例通过将参数exposeInnerGesture设置为true,实现了一级Tabs容器在嵌套二级Tabs的场景下,能够屏蔽二级Tabs内置Swiper的滑动手势,从而触发一级Tabs内置Swiper滑动手势的功能。
开发者自行定义变量来记录内层Tabs的索引值,通过该索引值判断当滑动达到内层Tabs的边界处时,触发回调返回屏蔽使外层Tabs产生滑动手势。
1 | // 手势拦截 Demo2 |
四、触摸事件原理
Harmony触摸事件捕获和事件冒泡
事件处理原理
- 事件监听: 在 ArkUI 中,事件监听是通过在组件上指定事件属性来实现的。例如,你可以为按钮组件添加一个 onClick 属性来监听点击事件。
- 事件对象: 当事件被触发时,一个事件对象会被传递给事件处理函数。这个对象包含了事件的详细信息,如事件类型、触发事件的元素、事件坐标等。
- 事件传播: 事件传播包括捕获阶段和冒泡阶段。在捕获阶段,事件从根元素向下传播到目标元素;在冒泡阶段,事件从目标元素向上传播回根元素。
- 事件处理函数: 事件处理函数可以是内联函数,也可以是组件方法中的一个函数。在函数内部,你可以执行任何逻辑来响应事件。
暂时无法在飞书文档外展示此内容
iOS触摸事件捕获
H5 触摸事件捕获和事件冒泡
DOM 事件标准描述了事件传播的 3 个阶段:
- 捕获阶段(Capturing phase)—— 事件(从 Window)向下走近元素。
- 目标阶段(Target phase)—— 事件到达目标元素。
- 冒泡阶段(Bubbling phase)—— 事件从元素上开始冒泡。