# 手势公共接口

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

本模块首批接口从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手势触发场景时，表示旋转角度，单位为deg。 用于SwipeGesture手势触发场景时，表示快滑手势的角度，即手指滑动的瞬时方向与水平正方向的夹角，单位为deg。 说明： 旋转角度计算方式：RotationGesture手势被识别到后，连接两根手指之间的线被识别为起始线条，随着手指的滑动，手指之间的线条会发生旋转，根据起始线条两端点和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角，最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系，顺时针旋转为0到180度，逆时针旋转为0到-180度。 取值范围：[-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。 |