大网数据广告活动
OpenHarmony 设备与应用开发

手势公共接口

· 52CE 我爱测

在手指全部抬起前阻止手势识别器参与当前手势识别。如果系统已确定该手势识别器的结果(无论成功与否),调用此接口将无效。此方法与GestureRecognizer.setEnabled(isEnabled: boolean)不同,setEnabled并不会阻止手势识别器对象参与手势识别过程,而只会影响手势对应的回调函数是否执行。

手势公共接口

为开发者提供手势相关的公共接口。

说明:

本模块首批接口从API version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

GestureInterface<T>11+

定义Gesture接口。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

tag11+

tag(tag: string): T

设置手势的标志。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

参数:

参数名 类型 必填 说明
tag string 是 手势的标志。

返回值:

类型 说明
T 返回当前组件。

allowedTypes14+

allowedTypes(types: Array<SourceTool>): T

设置手势响应的输入类型。

原子化服务API: 从API version 14开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

参数:

参数名 类型 必填 说明
types Array<SourceTool> 是 手势响应的输入类型。

返回值:

类型 说明
T 返回当前组件。

ScrollableTargetInfo12+

手势识别器对应的滚动类容器组件的信息,继承于EventTargetInfo。

isBegin12+

isBegin(): boolean

返回当前滚动类容器组件是否在顶部,如果为Swiper组件且在循环模式下返回false。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 当前滚动类容器组件是否在顶部。true表示组件在顶部,false表示组件不在顶部。

isEnd12+

isEnd(): boolean

返回当前滚动类容器组件是否在底部,如果为Swiper组件且在循环模式下返回false。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 当前滚动类容器组件是否在底部。true表示组件在底部,false表示组件不在底部。

EventTargetInfo12+

手势识别器对应组件的信息。

getId12+

getId(): string

返回当前组件的组件标识。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
string 当前组件的组件标识。

getUniqueId

getUniqueId(): number

返回当前组件的唯一id。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

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

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
number 当前组件的唯一id。

TouchRecognizer20+

触摸识别器对象。

原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

getEventTargetInfo20+

getEventTargetInfo(): EventTargetInfo

返回当前触摸识别器对应组件的信息。

原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
EventTargetInfo 当前触摸识别器对应组件的信息。

cancelTouch20+

cancelTouch(): void

向当前触摸识别器发送触摸取消事件的信息。

原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

isHostBelongsTo

isHostBelongsTo(uniqueId: number): boolean

返回当前触摸识别器绑定节点是否为传入组件的后代节点。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

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

模型约束: 此接口仅可在Stage模型下使用。

参数:

参数名 类型 必填 说明
uniqueId number 是 组件的唯一ID。可以通过getUniqueId接口获取该ID。

返回值:

类型 说明
boolean 当前触摸识别器绑定节点是否为传入组件的后代节点。true表示当前绑定节点为传入组件的后代节点,false表示当前绑定节点非传入组件的后代节点。

GestureRecognizer12+

手势识别器对象。

getTag12+

getTag(): string

返回当前手势识别器的tag。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
string 当前手势识别器的标志。

getType12+

getType(): GestureControl.GestureType

返回当前手势识别器的类型。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
GestureControl.GestureType 当前手势识别器的类型。

isBuiltIn12+

isBuiltIn(): boolean

返回当前手势识别器是否为系统内置手势。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 当前手势识别器是否为系统内置手势。true表示手势识别器为系统内置手势,false表示非系统内置手势。

setEnabled12+

setEnabled(isEnabled: boolean): void

设置当前手势识别器的使能状态。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

参数:

参数名 类型 必填 说明
isEnabled boolean 是 手势识别器的使能状态。true表示当前手势识别器能够回调应用事件,false表示当前手势识别器不回调应用事件。

isEnabled12+

isEnabled(): boolean

返回当前手势识别器的使能状态。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 当前手势识别器的使能状态。true表示当前手势识别器能够回调应用事件,false表示当前手势识别器不回调应用事件。

getState12+

getState(): GestureRecognizerState

返回当前手势识别器的状态。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
GestureRecognizerState 当前手势识别器的状态。

getEventTargetInfo12+

getEventTargetInfo(): EventTargetInfo

返回当前手势识别器对应组件的信息。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
EventTargetInfo 当前手势识别器对应组件的信息。

isValid12+

isValid(): boolean;

返回当前手势识别器是否有效。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 当前手势识别器是否有效。
当该识别器绑定的组件被析构或该识别器不在响应链上时返回false。
当该识别器绑定的组件未被析构且该识别器在响应链上时返回true。

getFingerCount18+

getFingerCount(): number

返回预设手指识别数阈值。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 预设手指识别数阈值。
取值范围:[1, 10], 整数。

isFingerCountLimit18+

isFingerCountLimit(): boolean

返回预设手势是否会检测触摸屏幕上手指识别数量。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 预设手势是否会检测触摸屏幕上手指识别数量。当绑定手势事件且会检测触摸屏幕上手指的数量时,返回true。当绑定手势事件且不会检测触摸屏幕上手指的数量时,返回false。

preventBegin20+

preventBegin(): void

在手指全部抬起前阻止手势识别器参与当前手势识别。如果系统已确定该手势识别器的结果(无论成功与否),调用此接口将无效。此方法与GestureRecognizer.setEnabled(isEnabled: boolean)不同,setEnabled并不会阻止手势识别器对象参与手势识别过程,而只会影响手势对应的回调函数是否执行。

原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

isHostBelongsTo

isHostBelongsTo(uniqueId: number): boolean

返回当前手势识别器绑定节点是否为传入组件的后代节点。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

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

模型约束: 此接口仅可在Stage模型下使用。

参数:

参数名 类型 必填 说明
uniqueId number 是 组件的唯一ID。可以通过getUniqueId接口获取该ID。

返回值:

类型 说明
boolean 当前手势识别器绑定节点是否为传入组件的后代节点。true表示当前绑定节点为传入组件的后代节点,false表示当前绑定节点非传入组件的后代节点。

TapRecognizer18+

点击手势识别器对象,继承自GestureRecognizer。

getTapCount18+

getTapCount(): number

返回预设点击手势识别器连续点击次数阈值。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 预设点击手势识别器连续点击次数阈值。
取值范围:[0, +∞)

LongPressRecognizer18+

长按手势识别器对象,继承于GestureRecognizer。

isRepeat18+

isRepeat(): boolean

返回预设长按手势识别器是否连续触发事件回调。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
boolean 预设长按手势识别器是否连续触发事件回调。当绑定长按手势且不会连续触发回调时,返回false。当绑定长按手势且会连续触发回调时,返回true。

getDuration18+

getDuration(): number

返回预设长按手势识别器触发长按最短时间阈值。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 返回预设长按手势识别器触发长按最短时间阈值,单位为ms。
取值范围:[0, +∞)

getAllowableMovement22+

getAllowableMovement(): number

获取长按手势识别器识别的手势的最大移动距离。

原子化服务API: 从API version 22开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 长按手势识别器识别的手势的最大移动距离,单位为px。
取值范围:(0, +∞)

SwipeRecognizer18+

快滑手势识别器对象,继承于GestureRecognizer。

getVelocityThreshold18+

getVelocityThreshold(): number

返回预设快滑手势识别器识别滑动最小速度阈值。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 预设快滑手势识别器识别滑动最小速度阈值,单位为vp/s。
取值范围:[0, +∞)

getDirection18+

getDirection(): SwipeDirection

返回预设快滑手势识别器触发快滑手势滑动方向。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
SwipeDirection 预设快滑手势识别器触发快滑手势滑动方向。

PinchRecognizer18+

捏合手势识别器对象,继承于GestureRecognizer。

getDistance18+

getDistance(): number

返回预设捏合手势识别器最小识别距离阈值。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 预设捏合手势识别器最小识别距离阈值,单位为vp。
取值范围:[0, +∞)

RotationRecognizer18+

旋转手势识别器对象,继承于GestureRecognizer。

getAngle18+

getAngle(): number

返回预设旋转手势识别器触发旋转手势最小改变度数阈值。

原子化服务API: 从API version 18开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 预设旋转手势识别器触发旋转手势最小改变度数阈值,单位为deg。
取值范围:[0, +∞)
说明:
当输入的改变度数的值小于等于0或大于360时,会被转化为默认值,默认值为1。

PanRecognizer12+

滑动手势识别器对象,继承于GestureRecognizer。

getPanGestureOptions12+

getPanGestureOptions(): PanGestureOptions

返回当前滑动手势识别器的属性。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
PanGestureOptions 当前滑动手势识别器的属性。

getDirection19+

getDirection(): PanDirection

返回当前滑动手势识别器的识别方向。

原子化服务API: 从API version 19开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
PanDirection 当前滑动手势识别器的识别方向。

getDistance19+

getDistance(): number

返回当前滑动手势识别器触发的最小滑动距离。

原子化服务API: 从API version 19开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
number 当前滑动手势识别器触发的最小滑动距离。单位:vp

getDistanceMap19+

getDistanceMap(): Map<SourceTool, number>

返回滑动手势识别器在不同输入源的情况下触发的最小滑动距离。

说明:

仅支持对通过Pan手势初始化配置修改的设备类型进行阈值查询。对于默认滑动阈值,可通过查询SourceTool.Unknown类型获取。其他未主动设置的类型则无法获取。

原子化服务API: 从API version 19开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

返回值:

类型 说明
Map<SourceTool, number> 不同输入源的滑动手势识别器触发的最小滑动距离。滑动距离的单位:vp

GestureRecognizerState12+

定义手势识别器状态。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 值 说明
READY 0 准备状态。
DETECTING 1 检测状态。
PENDING 2 等待状态。
BLOCKED 3 阻塞状态。
SUCCESSFUL 4 成功状态。
FAILED 5 失败状态。

GestureEvent对象说明

定义手势的事件信息。继承自BaseEvent。

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

名称 类型 只读 可选 说明
repeat boolean 否 否 是否为重复触发事件,用于LongPressGesture手势触发场景。true表示重复触发事件,false表示非重复触发事件。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
offsetX number 否 否 手势事件相对于手指按下时的偏移量X,单位为vp,用于PanGesture手势触发场景,从左向右滑动offsetX为正,反之为负。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
取值范围:(-∞, +∞)
offsetY number 否 否 手势事件相对于手指按下时的偏移量Y,单位为vp,用于PanGesture手势触发场景,从上向下滑动offsetY为正,反之为负。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
取值范围:(-∞, +∞)
angle number 否 否 用于RotationGesture手势触发场景时,表示旋转角度。
用于SwipeGesture手势触发场景时,表示快滑手势的角度,即两根手指间的线段与水平方向的夹角变化的度数。
说明:
角度计算方式:快滑手势被识别到后,连接两根手指之间的线被识别为起始线条,随着手指的滑动,手指之间的线条会发生旋转,根据起始线条两端点和当前线条两端点的坐标,使用反正切函数分别计算其相对于水平方向的夹角,最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系,顺时针旋转为0到180度,逆时针旋转为-180到0度。
取值范围:[-180, +180]
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
scale number 否 否 缩放比例,用于PinchGesture手势触发场景。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
pinchCenterX number 否 否 捏合手势中心点相对于当前组件元素原始区域左上角的x轴坐标,单位为vp,用于PinchGesture手势触发场景。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
pinchCenterY number 否 否 捏合手势中心点相对于当前组件元素原始区域左上角的y轴坐标,单位为vp,用于PinchGesture手势触发场景。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
speed8+ number 否 否 快滑手势速度,即所有手指相对当前组件元素原始区域滑动的平均速度,单位为vp/s,用于SwipeGesture手势触发场景。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
fingerList8+ FingerInfo[] 否 否 输入源为触屏产生的手势,fingerList中会包含触发事件的所有触点信息;由鼠标发起的手势,fingerList中只会有一条记录;触摸板的事件大类与鼠标一致,所以由触摸板发起的手势,fingerList只会携带一条记录。
说明:
1. 手指索引编号与位置对应,即fingerList[index]的id为index。先按下且未参与当前手势触发的手指在fingerList中对应位置为空。
2. 当使用键盘或手柄触发手势时,不存在手指信息,fingerList为空。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
fingerInfos20+ FingerInfo[] 否 是 由触屏产生的手势,fingerInfos中会包含触发事件的所有触点信息;由鼠标发起的手势,fingerInfos中只会有一条记录;触摸板的事件大类与鼠标一致,所以由触摸板发起的手势,fingerInfos只会携带一条记录。
说明:
fingerInfos只会记录参与触摸的有效手指信息,先按下但未参与当前手势触发的手指在fingerInfos中不会显示。默认值为空数组[],返回空数组时,表示当前无有效触点信息。
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
velocityX10+ number 否 否 用于PanGesture手势中,获取当前手势的x轴方向速度。坐标轴原点为屏幕左上角,分正负方向速度,从左往右为正,反之为负。单位为vp/s。
取值范围:(-∞, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
velocityY10+ number 否 否 用于PanGesture手势中,获取当前手势的y轴方向速度。坐标轴原点为屏幕左上角,分正负方向速度,从上往下为正,反之为负。单位为vp/s。
取值范围:(-∞, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
velocity10+ number 否 否 用于PanGesture手势中,获取当前手势的主方向速度。为xy轴方向速度的平方和的算术平方根。单位为vp/s。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
tapLocation20+ EventLocationInfo 否 是 用于点击手势中,获取当前手势的坐标信息。在非点击手势中,tapLocation返回值为undefined。
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。

GestureMask枚举说明

定义是否屏蔽子组件手势。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

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

名称 值 说明
Normal - 不屏蔽子组件的手势,按照默认手势识别顺序进行识别。
IgnoreInternal - 屏蔽子组件的手势,包括子组件上系统内置的手势,如子组件为List组件时,内置的滑动手势同样会被屏蔽。 若父子组件区域存在部分重叠,则只会屏蔽父子组件重叠的部分。

GestureJudgeResult11+

定义手势竞争结果。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 值 说明
CONTINUE 0 不影响系统手势判定流程。
REJECT 1 手势判定结果为失败。

GestureType11+

定义手势类型。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 值 说明
TAP_GESTURE 0 点击手势。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
LONG_PRESS_GESTURE 1 长按手势。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
PAN_GESTURE 2 滑动手势。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
PINCH_GESTURE 3 捏合手势。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
SWIPE_GESTURE 4 快滑手势。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
ROTATION_GESTURE 5 旋转手势。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
DRAG 6 拖拽。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
CLICK 7 点击。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
BOX_SELECT_GESTURE23+ 8 滚动类容器鼠标框选手势,是一种特殊的滑动手势,用于在滚动容器中通过鼠标拖拽创建选择区域,批量选择多个元素。
模型约束: 此接口仅可在Stage模型下使用。
原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。
WEB_SCROLL_GESTURE23+ 9 Web组件滚动手势,是一种特殊的滑动手势,用于控制Web组件内的滚动行为。
模型约束: 此接口仅可在Stage模型下使用。
原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。
TEXT_FIELD_SELECT_GESTURE23+ 10 文本选择手势,是一种特殊的滑动手势,用于在输入框组件中通过拖拽选择文本内容。
模型约束: 此接口仅可在Stage模型下使用。
原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。
CONTEXT_MENU_HOVER_GESTURE23+ 11 上下文菜单悬停手势是一种特殊的长按手势,用于在长按过程中触发菜单的hoverScale动画效果(需启用ContextMenuAnimationOptions的hoverScaleInterruption属性以支持该行为)。
模型约束: 此接口仅可在Stage模型下使用。
原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。

GestureInfo11+对象说明

手势信息类型。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
tag string 否 是 手势标志。
说明:
未设置事件标志tag属性时,tag不返回或返回undefined。
type GestureControl.GestureType 否 否 手势类型。
说明:
当手势为未暴露类型的系统内置手势事件时,type的值为-1。
isSystemGesture boolean 否 否 当前手势是否为组件自带手势。true表示是,false表示否。
默认值:false

FingerInfo8+对象说明

手指信息类型。

属性

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

名称 类型 只读 可选 说明
id number 否 否 手指的索引编号,由按下手指的数量决定,按下一根手指为0,之后每按下1根手指索引编号加一。
说明:
鼠标(索引编号为1001)、手写笔(索引编号为102)、鼠标滚轮(索引编号为0)、触摸板双指滑动(索引编号为0)的索引编号也会被转化为手指的索引编号。
取值范围:[0, 9)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
globalX number 否 否 相对于应用窗口左上角的x轴坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
globalY number 否 否 相对于应用窗口左上角的y轴坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
localX number 否 否 相对于当前组件元素原始区域左上角的x轴坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
localY number 否 否 相对于当前组件元素原始区域左上角的y轴坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
displayX12+ number 否 否 相对于屏幕左上角的x轴坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
displayY12+ number 否 否 相对于屏幕左上角的y轴坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
hand15+ InteractionHand 否 是 表示事件是由左手点击还是右手点击触发。
原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
globalDisplayX20+ number 否 是 相对于全局屏幕的左上角的X坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
globalDisplayY20+ number 否 是 相对于全局屏幕的左上角的Y坐标,单位为vp。
取值范围:[0, +∞)
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。

getCurrentLocalPosition

getCurrentLocalPosition?(): Coordinate2D

获取手指位置相对于当前组件实时位置的左上角坐标。

起始版本: 26.0.0

模型约束: 此接口仅可在Stage模型下使用。

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

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

返回值:

类型 说明
Coordinate2D 手指位置相对于当前组件实时位置的左上角坐标。

GestureType

type GestureType = TapGesture | LongPressGesture | PanGesture | PinchGesture | SwipeGesture | RotationGesture | GestureGroup

定义手势类型。取值类型为下表类型中的并集。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

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

类型 说明
TapGesture 点击手势,支持单次点击、多次点击识别。
LongPressGesture 长按手势。
PanGesture 滑动手势,当滑动的距离达到最小阈值时触发滑动手势事件,默认滑动阈值为5vp。
PinchGesture 捏合手势。
RotationGesture 旋转手势。
SwipeGesture 快滑手势,滑动速度大于等于速度阈值时可识别成功,默认最小速度为100vp/s。
GestureGroup 手势识别组,多种手势组合为复合手势,支持连续识别、并行识别和互斥识别。

BaseGestureEvent11+对象说明

基础手势事件类型。继承自BaseEvent。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
fingerList FingerInfo[] 否 否 触发事件的所有手指信息。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
fingerInfos20+ FingerInfo[] 否 是 参与触发事件的所有有效触点信息。默认值为空数组[],返回空数组时,表示当前无有效触点信息。
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。

TapGestureEvent11+对象说明

继承自BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
tapLocation20+ EventLocationInfo 否 是 获取点击手势的坐标信息。
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。

LongPressGestureEvent11+对象说明

继承自BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
repeat boolean 否 否 是否为重复触发事件。true表示为重复触发事件,false表示非重复触发事件。

PanGestureEvent11+对象说明

继承自BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
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。

PinchGestureEvent11+对象说明

继承自BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
scale number 否 否 缩放比例。
pinchCenterX number 否 否 捏合手势中心点相对于当前组件元素原始区域左上角x轴坐标,单位为vp。
pinchCenterY number 否 否 捏合手势中心点相对于当前组件元素原始区域左上角y轴坐标,单位为vp。

RotationGestureEvent11+对象说明

继承自BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
angle number 否 否 表示旋转角度,单位为deg。
说明:
角度计算方式:当滑动手势被识别后,连接两根手指之间的线被识别为起始线条。随着手指的滑动,手指之间的线条会发生旋转。根据起始线条和当前线条两端点的坐标,使用反正切函数分别计算其相对于水平方向的夹角。
最终的旋转角度为:arctan2(cy2-cy1, cx2-cx1) - arctan2(y2-y1, x2-x1)
在起始线条为坐标系的情况下,顺时针旋转为0到180度,逆时针旋转为0到-180度。

SwipeGestureEvent11+对象说明

继承自BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
angle number 否 否 表示快滑手势的角度,即手指滑动的瞬时方向与水平正方向的夹角,单位为deg。
说明:
以水平正方向为基准,滑动方向位于水平正方向顺时针侧时,角度范围为0到180度;位于水平正方向逆时针侧时,角度范围为0到-180度。
speed number 否 否 快滑手势速度,即所有手指相对当前组件元素原始区域滑动的平均速度,单位为vp/s。

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。