# Bound Gesture Configuration You can set the gestures that are bound to a component. Specifically, you can add or remove gestures by calling the APIs of the **UIGestureEvent** object. >**NOTE** > >The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. > > In **fingerList** of [GestureEvent](ts-gesture-settings.md#gestureevent), the index of a finger corresponds to its position, that is, the ID of a finger in **fingerList[index]** refers to its index. If a finger is pressed first and does not participate in triggering of the current gesture, its position in **fingerList** is left empty. You are advised to use **fingerInfos** when possible. ## UIGestureEvent Provides APIs for configuring gestures bound to a component. ### addGesture addGesture\(gesture: GestureHandler\, priority?: GesturePriority, mask?: GestureMask): void Adds a gesture. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------- | | gesture | [GestureHandler\](#gesturehandlert) | Yes | Gesture handler object.| | priority | [GesturePriority](#gesturepriority) | No | Priority of the bound gesture.
Default value: **GesturePriority.NORMAL**.| | mask | [GestureMask](./ts-gesture-settings.md#gesturemask) | No | Mask for gesture events.
Default value: **GestureMask.Normal**.| ### addParallelGesture addParallelGesture\(gesture: GestureHandler\, mask?: GestureMask): void Adds a gesture that can be recognized at once by the component and its child component. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------- | | gesture | [GestureHandler\](#gesturehandlert) | Yes | Gesture handler object.| | mask | [GestureMask](./ts-gesture-settings.md#gesturemask) | No | Mask for gesture events.
Default value: **GestureMask.Normal**.| ### removeGestureByTag removeGestureByTag(tag: string): void Remove a gesture from a component that has been bound with a specific tag through a modifier. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------- | | tag | string | Yes | Gesture handler flag.| ### clearGestures clearGestures(): void Clears all gestures that have been bound to the component through a modifier. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full ## GestureHandler\ Defines the basic type of the gesture handler. ### tag tag(tag: string): T Sets the tag for the gesture handler. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type| Mandatory|Description | | ---- | ------ | ------|---------------------------------- | | tag | string | Yes|Tag of the gesture handler.| ### allowedTypes14+ allowedTypes(types: Array\): T Sets the event input sources supported by the gesture handler. **Atomic service API**: This API can be used in atomic services since API version 14. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type| Mandatory|Description | | ---- | ------ | ------|---------------------------------- | | types | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | Yes|Event input sources supported by the gesture handler.| ## BaseHandlerOptions15+ Provides the parameters of the basic gesture handler. **Atomic service API**: This API can be used in atomic services since API version 15. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only| Optional| Description | |---------------|---------------|-----|------|----------------| | isFingerCountLimited | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen.
**true**: Enforce the exact number of fingers touching the screen.
**false**: Do not enforce the exact number of fingers touching the screen.
With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.
Default value: **false**.| ## TapGestureHandler Defines a type of gesture handler object for tap gestures. ### constructor constructor(options?: TapGestureHandlerOptions) A constructor used to create a **TapGestureHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [TapGestureHandlerOptions](#tapgesturehandleroptions) | No | Parameters of the tap gesture handler.| ### onAction onAction(event: Callback\): TapGestureHandler Invoked when a tap gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a tap gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | TapGestureHandler | Tap gesture handler object.| ## TapGestureHandlerOptions Provides the parameters of the tap gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only| Optional| Description | | ------------ | -------------------------------------|------ | ---- | -------------------- | | count | number | No| Yes| Number of consecutive taps. If the value is less than 1 or is not set, the default value is used.
Default value: **1**
**NOTE**
1. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms.
2. If the distance between the last tapped position and the current tapped position exceeds 60 vp, gesture recognition fails.| | fingers | number | No| Yes| Number of fingers required to trigger a tap. The value ranges from 1 to 10. If the value is less than 1 or is not set, the default value is used.
Default value: **1**
**NOTE**
1. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers pressing the screen within 300 ms of the first finger's being pressed is less than the required number, or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted is less than the required number.
2. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized.| | isFingerCountLimited15+ | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen.
**true**: Enforce the exact number of fingers touching the screen.
**false**: Do not enforce the exact number of fingers touching the screen.
With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.
In multi-tap events (where the **count** parameter is greater than 1), each tap must have the same number of fingers as the configured value; otherwise, the gesture recognition fails.
Default value: **false**.| ## LongPressGestureHandler Defines a type of gesture handler object for long press gestures. ### constructor constructor(options?: LongPressGestureHandlerOptions) A constructor used to create a **LongPressGestureHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [LongPressGestureHandlerOptions](#longpressgesturehandleroptions) | No | Parameters of the long press gesture handler.| ### onAction onAction(event: Callback\): LongPressGestureHandler Invoked when a long press gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a long press gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| ### onActionEnd onActionEnd(event: Callback\): LongPressGestureHandler Invoked when the last finger is lifted after the long press gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when the last finger is lifted after the long press gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| ### onActionCancel onActionCancel(event: Callback\): LongPressGestureHandler Invoked when a tap cancellation event is received after a long press gesture is recognized. No gesture event information is returned. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)\ | Yes| Callback invoked when a tap cancellation event is received after a long press gesture is recognized. No gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| ### onActionCancel18+ onActionCancel(event: Callback\): LongPressGestureHandler Invoked when a tap cancellation event is received after a long press gesture is recognized. Compared with [onActionCancel](#onactioncancel), this API returns gesture event information. **Atomic service API**: This API can be used in atomic services since API version 18. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a tap cancellation event is received after a long press gesture is recognized. Gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| ## LongPressGestureHandlerOptions Provides the parameters of the long press gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only | Optional| Description | | ------------ | ---------------------------------|----- | ---- | -------------------- | | fingers | number | No| Yes| Minimum number of fingers to trigger a long press gesture. The value ranges from 1 to 10.
Default value: **1**
**NOTE**
If a finger moves more than 15 px after being pressed, the gesture recognition fails.| | repeat | boolean | No| Yes| Whether to continuously trigger the event callback. The value **true** means to continuously trigger the event callback, and **false** means the opposite.
Default value: **false**.| | duration | number | No| Yes| Minimum hold-down time, in ms.
Default value: **500**
**NOTE**
Value range: [0, +∞). If the value is less than or equal to 0, the default value **500** is used.| | isFingerCountLimited15+ | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen.
**true**: Enforce the exact number of fingers touching the screen.
**false**: Do not enforce the exact number of fingers touching the screen.
With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.
For gestures that have already been successfully recognized, changes in the number of fingers touching the screen will not trigger the repeat event. However, if the number of fingers touching the screen returns to the configured minimum number, the [onAction](ts-basic-gestures-longpressgesture.md#events) event can be triggered. The [onActionEnd](ts-basic-gestures-longpressgesture.md#events) event can also be triggered regardless of the finger count.
Default value: **false**.| ## PanGestureHandler Defines a type of gesture handler object for pan gestures. ### constructor constructor(options?: PanGestureHandlerOptions) A constructor used to create a **PanGestureHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [PanGestureHandlerOptions](#pangesturehandleroptions) | No | Parameters of the pan gesture handler.| ### onActionStart onActionStart(event: Callback\): PanGestureHandler Invoked when a pan gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a pan gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| ### onActionUpdate onActionUpdate(event: Callback\): PanGestureHandler Invoked during the movement of a pan gesture. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked during the movement of a pan gesture.
If **fingerList** contains multiple fingers, this callback updates the location information of only one finger each time.| **Return value** | Type| Description| | -------- | -------- | | [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| ### onActionEnd onActionEnd(event: Callback\): PanGestureHandler Invoked when the finger used for a pan gesture is lifted. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when the finger used for a pan gesture is lifted.| **Return value** | Type| Description| | -------- | -------- | | [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| ### onActionCancel onActionCancel(event: Callback\): PanGestureHandler Invoked when a tap cancellation event is received after a pan gesture is recognized. No gesture event information is returned. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)\ | Yes| Callback invoked when a tap cancellation event is received after a pan gesture is recognized. No gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| ### onActionCancel18+ onActionCancel(event: Callback\): PanGestureHandler Invoked when a tap cancellation event is received after a pan gesture is recognized. Compared with [onActionCancel](#onactioncancel-1), this API returns gesture event information. **Atomic service API**: This API can be used in atomic services since API version 18. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a tap cancellation event is received after a pan gesture is recognized. Gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| ## PanGestureHandlerOptions Provides the parameters of the pan gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only| Optional| Description | | ------------ | ---------------------------------|----- | ---- | -------------------- | | fingers | number | No| Yes| Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.
Default value: **1**
Value range: [1, 10]
**NOTE**
If the value is less than 1 or is not set, the default value is used.| | direction | [PanDirection](./ts-basic-gestures-pangesture.md#pandirection) | No| Yes| Pan direction. The value supports the AND (&) and OR (\|) operations.
Default value: **PanDirection.All**| | distance | number | No| Yes| Minimum pan distance to trigger the gesture, in vp.
Default value: **8** for the stylus and **5** for other input sources.
**NOTE**
If a pan gesture and a [tab](ts-container-tabs.md) swipe occur at the same time, set **distance** to **1** so that the gesture can be more easily recognized.
Value range: [0, +∞).
If the value specified is less than 0, the default value is used.
Since API version 19, the default value is **8**, in vp, for the stylus.| | distanceMap19+ | Map<[SourceTool](ts-gesture-settings.md#sourcetool9), number> | No| Yes| Minimum pan distance for different input sources to trigger the gesture, in vp.
Default value: **8** for the stylus and **5** for other input sources.
Value range: [0, +∞).
If the value specified is less than 0, the default value is used.| ## SwipeGestureHandler Defines a type of gesture handler object for swipe gestures. ### constructor constructor(options?: SwipeGestureHandlerOptions) A constructor used to create a **SwipeGestureHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [SwipeGestureHandlerOptions](#swipegesturehandleroptions) | No | Parameters of the swipe gesture handler.| ### onAction onAction(event: Callback\): SwipeGestureHandlerOptions Invoked when a swipe gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a swipe gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | SwipeGestureHandler | Swipe gesture handler object.| ## SwipeGestureHandlerOptions Provides the parameters of the swipe gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only| Optional| Description | | ------------ | -------------------------------------- | ---- | -----|--------------- | | fingers | number | No| Yes| Minimum number of fingers to trigger a swipe gesture. The value ranges from 1 to 10.
Default value: **1**| | direction | [SwipeDirection](./ts-basic-gestures-swipegesture.md#swipedirection) | No| Yes| Swipe direction.
Default value: **SwipeDirection.All**| | speed | number | No| Yes| Minimum speed of the swipe gesture.
Default value: 100 vp/s
**NOTE**
If the value is less than or equal to 0, it will be converted to the default value.| | isFingerCountLimited15+ | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen.
**true**: Enforce the exact number of fingers touching the screen.
**false**: Do not enforce the exact number of fingers touching the screen.
With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.
Default value: **false**.| ## PinchGestureHandler Defines a type of gesture handler object for pinch gestures. ### constructor constructor(options?: PinchGestureHandlerOptions) A constructor used to create a **PinchGestureHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [PinchGestureHandlerOptions](#pinchgesturehandleroptions) | No | Parameters of the pinch gesture handler.| ### onActionStart onActionStart(event: Callback\): PinchGestureHandler Invoked when a pinch gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a pinch gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| ### onActionUpdate onActionUpdate(event: Callback\): PinchGestureHandler Invoked during the movement of a pinch gesture. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked during the movement of a pinch gesture.| **Return value** | Type| Description| | -------- | -------- | | [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| ### onActionEnd onActionEnd(event: Callback\): PinchGestureHandler Invoked when the finger used for a pinch gesture is lifted. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when the finger used for a pinch gesture is lifted.| **Return value** | Type| Description| | -------- | -------- | | [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| ### onActionCancel onActionCancel(event: Callback\): PinchGestureHandler Invoked when a tap cancellation event is received after a pinch gesture is recognized. No gesture event information is returned. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)\ | Yes| Callback invoked when a tap cancellation event is received after a pinch gesture is recognized. No gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| ### onActionCancel18+ onActionCancel(event: Callback\): PinchGestureHandler Invoked when a tap cancellation event is received after a pinch gesture is recognized. Compared with [onActionCancel](#onactioncancel-2), this API returns gesture event information. **Atomic service API**: This API can be used in atomic services since API version 18. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a tap cancellation event is received after a pinch gesture is recognized. Gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| ## PinchGestureHandlerOptions Provides the parameters of the pinch gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only | Optional| Description | | ------------ | ----------------------------------|---- | ---- | -------------------- | | fingers | number | No| Yes| Minimum number of fingers to trigger a pinch. The value ranges from 2 to 5.
Default value: **2**
While more fingers than the minimum number can be pressed to trigger the gesture, only the first fingers of the minimum number participate in gesture calculation.| | distance | number | No| Yes| Minimum recognition distance, in vp.
Default value: **5**
**NOTE**
If the value is less than or equal to 0, it will be converted to the default value.| | isFingerCountLimited15+ | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen.
**true**: Enforce the exact number of fingers touching the screen.
**false**: Do not enforce the exact number of fingers touching the screen.
With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**. The gesture can only be successfully recognized if the number of fingers equals the configured minimum and the swipe distance meets the threshold. Note that only the first two fingers that touch the screen are considered for the gesture. If one of these fingers is lifted, the gesture recognition fails. For gestures that have already been successfully recognized, changing the number of fingers touching the screen will not trigger the [onActionUpdate](ts-basic-gestures-pinchgesture.md#events) event, but the [onActionEnd](ts-basic-gestures-pinchgesture.md#events) event can still be triggered.
Default value: **false**.| ## RotationGestureHandler Defines a type of gesture handler object for rotation gestures. ### constructor constructor(options?: RotationGestureHandlerOptions) A constructor used to create a **RotationGestureHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [RotationGestureHandlerOptions](#rotationgesturehandleroptions) | No | Parameters of the rotation gesture handler.| ### onActionStart onActionStart(event: Callback\): RotationGestureHandler Invoked when a rotation gesture is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a rotation gesture is recognized.| **Return value** | Type| Description| | -------- | -------- | | [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| ### onActionUpdate onActionUpdate(event: Callback\): RotationGestureHandler Invoked during the movement of the rotation gesture. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked during the movement of the rotation gesture.| **Return value** | Type| Description| | -------- | -------- | | [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| ### onActionEnd onActionEnd(event: Callback\): RotationGestureHandler Invoked when the finger used for the rotation gesture is lifted. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when the finger used for the rotation gesture is lifted.| **Return value** | Type| Description| | -------- | -------- | | [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| ### onActionCancel onActionCancel(event: Callback\): RotationGestureHandler Invoked when a tap cancellation event is received after the rotation gesture is recognized. No gesture event information is returned. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)\ | Yes| Callback invoked when a tap cancellation event is received after the rotation gesture is recognized. No gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| ### onActionCancel18+ onActionCancel(event: Callback\): RotationGestureHandler Invoked when a tap cancellation event is received after the rotation gesture is recognized. Compared with [onActionCancel](#onactioncancel-3), this API returns gesture event information. **Atomic service API**: This API can be used in atomic services since API version 18. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a tap cancellation event is received after the rotation gesture is recognized. Gesture event information is returned.| **Return value** | Type| Description| | -------- | -------- | | [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| ## RotationGestureHandlerOptions Provides the parameters of the rotation gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type |Read-Only |Optional| Description | | ------------ | ---------------------------------|----- | ---- | -------------------- | | fingers | number | No| Yes| Minimum number of fingers to trigger a rotation. The value ranges from 2 to 5.
Default value: **2**
While more fingers than the minimum number can be pressed to trigger the gesture, only the first two fingers participate in gesture calculation.| | angle | number | No| Yes| Minimum degree that can trigger the rotation gesture.
Default value: **1**
**NOTE**
If the value is less than or equal to 0 or greater than 360, it will be converted to the default value.| | isFingerCountLimited15+ | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen.
**true**: Enforce the exact number of fingers touching the screen.
**false**: Do not enforce the exact number of fingers touching the screen.
With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**. The gesture can only be successfully recognized if the number of fingers equals the configured minimum and the swipe distance meets the threshold. Note that only the first two fingers that touch the screen are considered for the gesture. If one of these fingers is lifted, the gesture recognition fails.
For gestures that have already been successfully recognized, changing the number of fingers touching the screen will not trigger the[onActionUpdate](ts-basic-gestures-rotationgesture.md#events) event, but the [onActionEnd](ts-basic-gestures-rotationgesture.md#events) event can still be triggered.
Default value: **false**.| ## GestureGroupHandler Defines a type of gesture handler object for gesture groups. ### constructor constructor(options?: GestureGroupGestureHandlerOptions) A constructor used to create a **GestureGroupHandler** object. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [GestureGroupGestureHandlerOptions](#gesturegroupgesturehandleroptions) | No | Parameters of the gesture group handler.| ### onCancel onCancel(event: Callback\): GestureGroupHandler Invoked when a cancellation event is received after the gesture group in sequential gesture recognition (**GestureMode.Sequence**) is recognized. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [Callback](./ts-types.md#callback12)\ | Yes| Callback invoked when a cancellation event is received after the gesture group in sequential gesture recognition **GestureMode.Sequence**) is recognized.| **Return value** | Type| Description| | -------- | -------- | | GestureGroupHandler | Gesture group handler object.| ## GestureGroupGestureHandlerOptions Provides the parameters of the gesture group handler. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Read-Only | Optional| Description | | ------------ | ---------------------------------|----- | ---- | -------------------- | | mode | [GestureMode](./ts-combined-gestures.md#gesturemode) | No| No | Recognition mode of combined gestures.
Default value: **GestureMode.Sequence** | | gestures | [GestureHandler](#gesturehandlert)\<[TapGestureHandler](#tapgesturehandler) \| [LongPressGestureHandler](#longpressgesturehandler) \| [PanGestureHandler](#pangesturehandler) \| [SwipeGestureHandler](#swipegesturehandler) \| [PinchGestureHandler](#pinchgesturehandler) \| [RotationGestureHandler](#rotationgesturehandler) \| [GestureGroupHandler](#gesturegrouphandler)>[] | No| No | Gestures that need to be included in the gesture group.
**NOTE**
To add both tap and double-tap gestures for a component, add two TapGestures, with the tap gesture added after the double-tap gesture.| ## GesturePriority **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name| Value| Description| | ------| -- | -------- | | NORMAL | 0 | Normal priority.| | PRIORITY | 1 | High priority.| ## Example See the example in [Gesture Modifier](ts-universal-attributes-gesture-modifier.md).