1# Bound Gesture Configuration 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9You 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. 10 11>**NOTE** 12> 13>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. 14> 15> 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. 16 17## UIGestureEvent 18 19Provides APIs for configuring gestures bound to a component. 20 21### addGesture 22 23addGesture\<T>(gesture: GestureHandler\<T>, priority?: GesturePriority, mask?: GestureMask): void 24 25Adds a gesture. 26 27**Atomic service API**: This API can be used in atomic services since API version 12. 28 29**System capability**: SystemCapability.ArkUI.ArkUI.Full 30 31**Parameters** 32 33| Name| Type | Mandatory| Description | 34| ------ | ------ | ---- | -------------------------- | 35| gesture | [GestureHandler\<T>](#gesturehandlert) | Yes | Gesture handler object.| 36| priority | [GesturePriority](#gesturepriority) | No | Priority of the bound gesture.<br>Default value: **GesturePriority.NORMAL**.| 37| mask | [GestureMask](./ts-gesture-settings.md#gesturemask) | No | Mask for gesture events.<br>Default value: **GestureMask.Normal**.| 38 39### addParallelGesture 40 41addParallelGesture\<T>(gesture: GestureHandler\<T>, mask?: GestureMask): void 42 43Adds a gesture that can be recognized at once by the component and its child component. 44 45**Atomic service API**: This API can be used in atomic services since API version 12. 46 47**System capability**: SystemCapability.ArkUI.ArkUI.Full 48 49**Parameters** 50 51| Name| Type | Mandatory| Description | 52| ------ | ------ | ---- | -------------------------- | 53| gesture | [GestureHandler\<T>](#gesturehandlert) | Yes | Gesture handler object.| 54| mask | [GestureMask](./ts-gesture-settings.md#gesturemask) | No | Mask for gesture events.<br>Default value: **GestureMask.Normal**.| 55 56### removeGestureByTag 57 58removeGestureByTag(tag: string): void 59 60Remove a gesture from a component that has been bound with a specific tag through a modifier. 61 62**Atomic service API**: This API can be used in atomic services since API version 12. 63 64**System capability**: SystemCapability.ArkUI.ArkUI.Full 65 66**Parameters** 67 68| Name| Type | Mandatory| Description | 69| ------ | ------ | ---- | -------------------------- | 70| tag | string | Yes | Gesture handler flag.| 71 72### clearGestures 73 74clearGestures(): void 75 76Clears all gestures that have been bound to the component through a modifier. 77 78**Atomic service API**: This API can be used in atomic services since API version 12. 79 80**System capability**: SystemCapability.ArkUI.ArkUI.Full 81 82## GestureHandler\<T> 83 84Defines the basic type of the gesture handler. 85 86### tag 87 88tag(tag: string): T 89 90Sets the tag for the gesture handler. 91 92**Atomic service API**: This API can be used in atomic services since API version 12. 93 94**System capability**: SystemCapability.ArkUI.ArkUI.Full 95 96**Parameters** 97 98| Name| Type| Mandatory|Description | 99| ---- | ------ | ------|---------------------------------- | 100| tag | string | Yes|Tag of the gesture handler.| 101 102### allowedTypes<sup>14+</sup> 103 104allowedTypes(types: Array\<SourceTool>): T 105 106Sets the event input sources supported by the gesture handler. 107 108**Atomic service API**: This API can be used in atomic services since API version 14. 109 110**System capability**: SystemCapability.ArkUI.ArkUI.Full 111 112**Parameters** 113 114| Name| Type| Mandatory|Description | 115| ---- | ------ | ------|---------------------------------- | 116| types | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | Yes|Event input sources supported by the gesture handler.| 117 118## BaseHandlerOptions<sup>15+</sup> 119 120Provides the parameters of the basic gesture handler. 121 122**Atomic service API**: This API can be used in atomic services since API version 15. 123 124**System capability**: SystemCapability.ArkUI.ArkUI.Full 125 126| Name | Type | Read-Only| Optional| Description | 127|---------------|---------------|-----|------|----------------| 128| isFingerCountLimited | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen. <br>**true**: Enforce the exact number of fingers touching the screen.<br>**false**: Do not enforce the exact number of fingers touching the screen.<br> With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.<br>Default value: **false**.| 129 130## TapGestureHandler 131 132Defines a type of gesture handler object for tap gestures. 133 134### constructor 135 136constructor(options?: TapGestureHandlerOptions) 137 138A constructor used to create a **TapGestureHandler** object. 139 140**Atomic service API**: This API can be used in atomic services since API version 12. 141 142**System capability**: SystemCapability.ArkUI.ArkUI.Full 143 144**Parameters** 145 146| Name | Type | Mandatory| Description | 147| ------- | ------------------------------------------------------------ | ---- | ------------------ | 148| options | [TapGestureHandlerOptions](#tapgesturehandleroptions) | No | Parameters of the tap gesture handler.| 149 150### onAction 151 152onAction(event: Callback\<GestureEvent>): TapGestureHandler 153 154Invoked when a tap gesture is recognized. 155 156**Atomic service API**: This API can be used in atomic services since API version 12. 157 158**System capability**: SystemCapability.ArkUI.ArkUI.Full 159 160**Parameters** 161 162| Name| Type | Mandatory| Description | 163| ------ | --------------------------------- | ---- | -------------------- | 164| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a tap gesture is recognized.| 165 166**Return value** 167 168| Type| Description| 169| -------- | -------- | 170| TapGestureHandler | Tap gesture handler object.| 171 172## TapGestureHandlerOptions 173 174Provides the parameters of the tap gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). 175 176**Atomic service API**: This API can be used in atomic services since API version 12. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180| Name | Type | Read-Only| Optional| Description | 181| ------------ | -------------------------------------|------ | ---- | -------------------- | 182| count | number | No| Yes| Number of consecutive taps. If the value is less than 1 or is not set, the default value is used.<br>Default value: **1**<br>**NOTE**<br>1. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms.<br>2. If the distance between the last tapped position and the current tapped position exceeds 60 vp, gesture recognition fails.| 183| 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.<br>Default value: **1**<br>**NOTE**<br>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.<br>2. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized.| 184| isFingerCountLimited<sup>15+</sup> | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen. <br>**true**: Enforce the exact number of fingers touching the screen.<br>**false**: Do not enforce the exact number of fingers touching the screen.<br> With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.<br>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.<br>Default value: **false**.| 185 186## LongPressGestureHandler 187 188Defines a type of gesture handler object for long press gestures. 189 190### constructor 191 192constructor(options?: LongPressGestureHandlerOptions) 193 194A constructor used to create a **LongPressGestureHandler** object. 195 196**Atomic service API**: This API can be used in atomic services since API version 12. 197 198**System capability**: SystemCapability.ArkUI.ArkUI.Full 199 200**Parameters** 201 202 203| Name | Type | Mandatory| Description | 204| ------- | ------------------------------------------------------------ | ---- | ------------------ | 205| options | [LongPressGestureHandlerOptions](#longpressgesturehandleroptions) | No | Parameters of the long press gesture handler.| 206 207### onAction 208 209onAction(event: Callback\<GestureEvent>): LongPressGestureHandler 210 211Invoked when a long press gesture is recognized. 212 213**Atomic service API**: This API can be used in atomic services since API version 12. 214 215**System capability**: SystemCapability.ArkUI.ArkUI.Full 216 217**Parameters** 218 219| Name| Type | Mandatory| Description | 220| ------ | --------------------------------- | ---- | -------------------- | 221| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a long press gesture is recognized.| 222 223**Return value** 224 225| Type| Description| 226| -------- | -------- | 227| [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| 228 229### onActionEnd 230 231onActionEnd(event: Callback\<GestureEvent>): LongPressGestureHandler 232 233Invoked when the last finger is lifted after the long press gesture is recognized. 234 235**Atomic service API**: This API can be used in atomic services since API version 12. 236 237**System capability**: SystemCapability.ArkUI.ArkUI.Full 238 239**Parameters** 240 241| Name| Type | Mandatory| Description | 242| ------ | --------------------------------- | ---- | -------------------- | 243| 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.| 244 245**Return value** 246 247| Type| Description| 248| -------- | -------- | 249| [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| 250 251### onActionCancel 252 253onActionCancel(event: Callback\<void>): LongPressGestureHandler 254 255Invoked when a tap cancellation event is received after a long press gesture is recognized. No gesture event information is returned. 256 257**Atomic service API**: This API can be used in atomic services since API version 12. 258 259**System capability**: SystemCapability.ArkUI.ArkUI.Full 260 261**Parameters** 262 263| Name| Type | Mandatory| Description | 264| ------ | --------------------------------- | ---- | -------------------- | 265| event | [Callback](./ts-types.md#callback12)\<void> | Yes| Callback invoked when a tap cancellation event is received after a long press gesture is recognized. No gesture event information is returned.| 266 267**Return value** 268 269| Type| Description| 270| -------- | -------- | 271| [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| 272 273### onActionCancel<sup>18+</sup> 274 275onActionCancel(event: Callback\<GestureEvent>): LongPressGestureHandler 276 277Invoked when a tap cancellation event is received after a long press gesture is recognized. Compared with [onActionCancel](#onactioncancel), this API returns gesture event information. 278 279**Atomic service API**: This API can be used in atomic services since API version 18. 280 281**System capability**: SystemCapability.ArkUI.ArkUI.Full 282 283**Parameters** 284 285| Name| Type | Mandatory| Description | 286| ------ | --------------------------------- | ---- | -------------------- | 287| 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.| 288 289**Return value** 290 291| Type| Description| 292| -------- | -------- | 293| [LongPressGestureHandler](#longpressgesturehandler) | Long press gesture handler object.| 294 295## LongPressGestureHandlerOptions 296 297Provides the parameters of the long press gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). 298 299**Atomic service API**: This API can be used in atomic services since API version 12. 300 301**System capability**: SystemCapability.ArkUI.ArkUI.Full 302 303| Name | Type | Read-Only | Optional| Description | 304| ------------ | ---------------------------------|----- | ---- | -------------------- | 305| fingers | number | No| Yes| Minimum number of fingers to trigger a long press gesture. The value ranges from 1 to 10.<br>Default value: **1**<br> **NOTE**<br>If a finger moves more than 15 px after being pressed, the gesture recognition fails.| 306| 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.<br>Default value: **false**.| 307| duration | number | No| Yes| Minimum hold-down time, in ms.<br>Default value: **500**<br>**NOTE**<br>Value range: [0, +∞). If the value is less than or equal to 0, the default value **500** is used.| 308| isFingerCountLimited<sup>15+</sup> | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen. <br>**true**: Enforce the exact number of fingers touching the screen.<br>**false**: Do not enforce the exact number of fingers touching the screen.<br> With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.<br>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.<br>Default value: **false**.| 309 310## PanGestureHandler 311 312Defines a type of gesture handler object for pan gestures. 313 314### constructor 315 316constructor(options?: PanGestureHandlerOptions) 317 318A constructor used to create a **PanGestureHandler** object. 319 320**Atomic service API**: This API can be used in atomic services since API version 12. 321 322**System capability**: SystemCapability.ArkUI.ArkUI.Full 323 324**Parameters** 325 326 327| Name | Type | Mandatory| Description | 328| ------- | ------------------------------------------------------------ | ---- | ------------------ | 329| options | [PanGestureHandlerOptions](#pangesturehandleroptions) | No | Parameters of the pan gesture handler.| 330 331### onActionStart 332 333onActionStart(event: Callback\<GestureEvent>): PanGestureHandler 334 335Invoked when a pan gesture is recognized. 336 337**Atomic service API**: This API can be used in atomic services since API version 12. 338 339**System capability**: SystemCapability.ArkUI.ArkUI.Full 340 341**Parameters** 342 343| Name| Type | Mandatory| Description | 344| ------ | --------------------------------- | ---- | -------------------- | 345| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a pan gesture is recognized.| 346 347**Return value** 348 349| Type| Description| 350| -------- | -------- | 351| [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| 352 353### onActionUpdate 354 355onActionUpdate(event: Callback\<GestureEvent>): PanGestureHandler 356 357Invoked during the movement of a pan gesture. 358 359**Atomic service API**: This API can be used in atomic services since API version 12. 360 361**System capability**: SystemCapability.ArkUI.ArkUI.Full 362 363**Parameters** 364 365| Name| Type | Mandatory| Description | 366| ------ | --------------------------------- | ---- | -------------------- | 367| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked during the movement of a pan gesture.<br>If **fingerList** contains multiple fingers, this callback updates the location information of only one finger each time.| 368 369**Return value** 370 371| Type| Description| 372| -------- | -------- | 373| [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| 374 375### onActionEnd 376 377onActionEnd(event: Callback\<GestureEvent>): PanGestureHandler 378 379Invoked when the finger used for a pan gesture is lifted. 380 381**Atomic service API**: This API can be used in atomic services since API version 12. 382 383**System capability**: SystemCapability.ArkUI.ArkUI.Full 384 385**Parameters** 386 387| Name| Type | Mandatory| Description | 388| ------ | --------------------------------- | ---- | -------------------- | 389| 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.| 390 391**Return value** 392 393| Type| Description| 394| -------- | -------- | 395| [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| 396 397### onActionCancel 398 399onActionCancel(event: Callback\<void>): PanGestureHandler 400 401Invoked when a tap cancellation event is received after a pan gesture is recognized. No gesture event information is returned. 402 403**Atomic service API**: This API can be used in atomic services since API version 12. 404 405**System capability**: SystemCapability.ArkUI.ArkUI.Full 406 407**Parameters** 408 409| Name| Type | Mandatory| Description | 410| ------ | --------------------------------- | ---- | -------------------- | 411| event | [Callback](./ts-types.md#callback12)\<void> | Yes| Callback invoked when a tap cancellation event is received after a pan gesture is recognized. No gesture event information is returned.| 412 413**Return value** 414 415| Type| Description| 416| -------- | -------- | 417| [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| 418 419### onActionCancel<sup>18+</sup> 420 421onActionCancel(event: Callback\<GestureEvent>): PanGestureHandler 422 423Invoked when a tap cancellation event is received after a pan gesture is recognized. Compared with [onActionCancel](#onactioncancel-1), this API returns gesture event information. 424 425**Atomic service API**: This API can be used in atomic services since API version 18. 426 427**System capability**: SystemCapability.ArkUI.ArkUI.Full 428 429**Parameters** 430 431| Name| Type | Mandatory| Description | 432| ------ | --------------------------------- | ---- | -------------------- | 433| 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.| 434 435**Return value** 436 437| Type| Description| 438| -------- | -------- | 439| [PanGestureHandler](#pangesturehandler) | Pan gesture handler object.| 440 441## PanGestureHandlerOptions 442 443Provides the parameters of the pan gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). 444 445**Atomic service API**: This API can be used in atomic services since API version 12. 446 447**System capability**: SystemCapability.ArkUI.ArkUI.Full 448 449| Name | Type | Read-Only| Optional| Description | 450| ------------ | ---------------------------------|----- | ---- | -------------------- | 451| fingers | number | No| Yes| Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**<br>Value range: [1, 10]<br>**NOTE**<br>If the value is less than 1 or is not set, the default value is used.| 452| direction | [PanDirection](./ts-basic-gestures-pangesture.md#pandirection) | No| Yes| Pan direction. The value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**| 453| distance | number | No| Yes| Minimum pan distance to trigger the gesture, in vp.<br>Default value: **8** for the stylus and **5** for other input sources.<br>**NOTE**<br>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.<br>Value range: [0, +∞).<br>If the value specified is less than 0, the default value is used.<br>Since API version 19, the default value is **8**, in vp, for the stylus.| 454| distanceMap<sup>19+</sup> | Map<[SourceTool](ts-gesture-settings.md#sourcetool9), number> | No| Yes| Minimum pan distance for different input sources to trigger the gesture, in vp.<br>Default value: **8** for the stylus and **5** for other input sources.<br>Value range: [0, +∞).<br>If the value specified is less than 0, the default value is used.| 455 456## SwipeGestureHandler 457 458Defines a type of gesture handler object for swipe gestures. 459 460### constructor 461 462constructor(options?: SwipeGestureHandlerOptions) 463 464A constructor used to create a **SwipeGestureHandler** object. 465 466**Atomic service API**: This API can be used in atomic services since API version 12. 467 468**System capability**: SystemCapability.ArkUI.ArkUI.Full 469 470**Parameters** 471 472| Name | Type | Mandatory| Description | 473| ------- | ------------------------------------------------------------ | ---- | ------------------ | 474| options | [SwipeGestureHandlerOptions](#swipegesturehandleroptions) | No | Parameters of the swipe gesture handler.| 475 476### onAction 477 478onAction(event: Callback\<GestureEvent>): SwipeGestureHandlerOptions 479 480Invoked when a swipe gesture is recognized. 481 482**Atomic service API**: This API can be used in atomic services since API version 12. 483 484**System capability**: SystemCapability.ArkUI.ArkUI.Full 485 486**Parameters** 487 488| Name| Type | Mandatory| Description | 489| ------ | --------------------------------- | ---- | -------------------- | 490| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a swipe gesture is recognized.| 491 492**Return value** 493 494| Type| Description| 495| -------- | -------- | 496| SwipeGestureHandler | Swipe gesture handler object.| 497 498## SwipeGestureHandlerOptions 499 500Provides the parameters of the swipe gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). 501 502**Atomic service API**: This API can be used in atomic services since API version 12. 503 504**System capability**: SystemCapability.ArkUI.ArkUI.Full 505 506| Name | Type | Read-Only| Optional| Description | 507| ------------ | -------------------------------------- | ---- | -----|--------------- | 508| fingers | number | No| Yes| Minimum number of fingers to trigger a swipe gesture. The value ranges from 1 to 10.<br>Default value: **1**| 509| direction | [SwipeDirection](./ts-basic-gestures-swipegesture.md#swipedirection) | No| Yes| Swipe direction.<br>Default value: **SwipeDirection.All**| 510| speed | number | No| Yes| Minimum speed of the swipe gesture.<br>Default value: 100 vp/s<br>**NOTE**<br>If the value is less than or equal to 0, it will be converted to the default value.| 511| isFingerCountLimited<sup>15+</sup> | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen. <br>**true**: Enforce the exact number of fingers touching the screen.<br>**false**: Do not enforce the exact number of fingers touching the screen.<br> With the value **true**, the gesture recognition fails if the number of fingers touching the screen does not match the configured value of **fingers**.<br>Default value: **false**.| 512 513## PinchGestureHandler 514 515Defines a type of gesture handler object for pinch gestures. 516 517### constructor 518 519constructor(options?: PinchGestureHandlerOptions) 520 521A constructor used to create a **PinchGestureHandler** object. 522 523**Atomic service API**: This API can be used in atomic services since API version 12. 524 525**System capability**: SystemCapability.ArkUI.ArkUI.Full 526 527**Parameters** 528 529 530| Name | Type | Mandatory| Description | 531| ------- | ------------------------------------------------------------ | ---- | ------------------ | 532| options | [PinchGestureHandlerOptions](#pinchgesturehandleroptions) | No | Parameters of the pinch gesture handler.| 533 534### onActionStart 535 536onActionStart(event: Callback\<GestureEvent>): PinchGestureHandler 537 538Invoked when a pinch gesture is recognized. 539 540**Atomic service API**: This API can be used in atomic services since API version 12. 541 542**System capability**: SystemCapability.ArkUI.ArkUI.Full 543 544**Parameters** 545 546| Name| Type | Mandatory| Description | 547| ------ | --------------------------------- | ---- | -------------------- | 548| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a pinch gesture is recognized.| 549 550**Return value** 551 552| Type| Description| 553| -------- | -------- | 554| [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| 555 556### onActionUpdate 557 558onActionUpdate(event: Callback\<GestureEvent>): PinchGestureHandler 559 560Invoked during the movement of a pinch gesture. 561 562**Atomic service API**: This API can be used in atomic services since API version 12. 563 564**System capability**: SystemCapability.ArkUI.ArkUI.Full 565 566**Parameters** 567 568| Name| Type | Mandatory| Description | 569| ------ | --------------------------------- | ---- | -------------------- | 570| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked during the movement of a pinch gesture.| 571 572**Return value** 573 574| Type| Description| 575| -------- | -------- | 576| [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| 577 578### onActionEnd 579 580onActionEnd(event: Callback\<GestureEvent>): PinchGestureHandler 581 582Invoked when the finger used for a pinch gesture is lifted. 583 584**Atomic service API**: This API can be used in atomic services since API version 12. 585 586**System capability**: SystemCapability.ArkUI.ArkUI.Full 587 588**Parameters** 589 590| Name| Type | Mandatory| Description | 591| ------ | --------------------------------- | ---- | -------------------- | 592| 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.| 593 594**Return value** 595 596| Type| Description| 597| -------- | -------- | 598| [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| 599 600### onActionCancel 601 602onActionCancel(event: Callback\<void>): PinchGestureHandler 603 604Invoked when a tap cancellation event is received after a pinch gesture is recognized. No gesture event information is returned. 605 606**Atomic service API**: This API can be used in atomic services since API version 12. 607 608**System capability**: SystemCapability.ArkUI.ArkUI.Full 609 610**Parameters** 611 612| Name| Type | Mandatory| Description | 613| ------ | --------------------------------- | ---- | -------------------- | 614| event | [Callback](./ts-types.md#callback12)\<void> | Yes| Callback invoked when a tap cancellation event is received after a pinch gesture is recognized. No gesture event information is returned.| 615 616**Return value** 617 618| Type| Description| 619| -------- | -------- | 620| [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| 621 622### onActionCancel<sup>18+</sup> 623 624onActionCancel(event: Callback\<GestureEvent>): PinchGestureHandler 625 626Invoked when a tap cancellation event is received after a pinch gesture is recognized. Compared with [onActionCancel](#onactioncancel-2), this API returns gesture event information. 627 628**Atomic service API**: This API can be used in atomic services since API version 18. 629 630**System capability**: SystemCapability.ArkUI.ArkUI.Full 631 632**Parameters** 633 634| Name| Type | Mandatory| Description | 635| ------ | --------------------------------- | ---- | -------------------- | 636| 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.| 637 638**Return value** 639 640| Type| Description| 641| -------- | -------- | 642| [PinchGestureHandler](#pinchgesturehandler) | Pinch gesture handler object.| 643 644## PinchGestureHandlerOptions 645 646Provides the parameters of the pinch gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). 647 648**Atomic service API**: This API can be used in atomic services since API version 12. 649 650**System capability**: SystemCapability.ArkUI.ArkUI.Full 651 652| Name | Type | Read-Only | Optional| Description | 653| ------------ | ----------------------------------|---- | ---- | -------------------- | 654| fingers | number | No| Yes| Minimum number of fingers to trigger a pinch. The value ranges from 2 to 5.<br>Default value: **2**<br>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.| 655| distance | number | No| Yes| Minimum recognition distance, in vp.<br>Default value: **5**<br>**NOTE**<br> If the value is less than or equal to 0, it will be converted to the default value.| 656| isFingerCountLimited<sup>15+</sup> | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen. <br>**true**: Enforce the exact number of fingers touching the screen.<br>**false**: Do not enforce the exact number of fingers touching the screen.<br> 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.<br>Default value: **false**.| 657 658## RotationGestureHandler 659 660Defines a type of gesture handler object for rotation gestures. 661 662### constructor 663 664constructor(options?: RotationGestureHandlerOptions) 665 666A constructor used to create a **RotationGestureHandler** object. 667 668**Atomic service API**: This API can be used in atomic services since API version 12. 669 670**System capability**: SystemCapability.ArkUI.ArkUI.Full 671 672**Parameters** 673 674 675| Name | Type | Mandatory| Description | 676| ------- | ------------------------------------------------------------ | ---- | ------------------ | 677| options | [RotationGestureHandlerOptions](#rotationgesturehandleroptions) | No | Parameters of the rotation gesture handler.| 678 679### onActionStart 680 681onActionStart(event: Callback\<GestureEvent>): RotationGestureHandler 682 683Invoked when a rotation gesture is recognized. 684 685**Atomic service API**: This API can be used in atomic services since API version 12. 686 687**System capability**: SystemCapability.ArkUI.ArkUI.Full 688 689**Parameters** 690 691| Name| Type | Mandatory| Description | 692| ------ | --------------------------------- | ---- | -------------------- | 693| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked when a rotation gesture is recognized.| 694 695**Return value** 696 697| Type| Description| 698| -------- | -------- | 699| [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| 700 701### onActionUpdate 702 703onActionUpdate(event: Callback\<GestureEvent>): RotationGestureHandler 704 705Invoked during the movement of the rotation gesture. 706 707**Atomic service API**: This API can be used in atomic services since API version 12. 708 709**System capability**: SystemCapability.ArkUI.ArkUI.Full 710 711**Parameters** 712 713| Name| Type | Mandatory| Description | 714| ------ | --------------------------------- | ---- | -------------------- | 715| event | [Callback](./ts-types.md#callback12)<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes| Callback invoked during the movement of the rotation gesture.| 716 717**Return value** 718 719| Type| Description| 720| -------- | -------- | 721| [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| 722 723### onActionEnd 724 725onActionEnd(event: Callback\<GestureEvent>): RotationGestureHandler 726 727Invoked when the finger used for the rotation gesture is lifted. 728 729**Atomic service API**: This API can be used in atomic services since API version 12. 730 731**System capability**: SystemCapability.ArkUI.ArkUI.Full 732 733**Parameters** 734 735| Name| Type | Mandatory| Description | 736| ------ | --------------------------------- | ---- | -------------------- | 737| 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.| 738 739**Return value** 740 741| Type| Description| 742| -------- | -------- | 743| [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| 744 745### onActionCancel 746 747onActionCancel(event: Callback\<void>): RotationGestureHandler 748 749Invoked when a tap cancellation event is received after the rotation gesture is recognized. No gesture event information is returned. 750 751**Atomic service API**: This API can be used in atomic services since API version 12. 752 753**System capability**: SystemCapability.ArkUI.ArkUI.Full 754 755**Parameters** 756 757| Name| Type | Mandatory| Description | 758| ------ | --------------------------------- | ---- | -------------------- | 759| event | [Callback](./ts-types.md#callback12)\<void> | Yes| Callback invoked when a tap cancellation event is received after the rotation gesture is recognized. No gesture event information is returned.| 760 761**Return value** 762 763| Type| Description| 764| -------- | -------- | 765| [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| 766 767### onActionCancel<sup>18+</sup> 768 769onActionCancel(event: Callback\<GestureEvent>): RotationGestureHandler 770 771Invoked when a tap cancellation event is received after the rotation gesture is recognized. Compared with [onActionCancel](#onactioncancel-3), this API returns gesture event information. 772 773**Atomic service API**: This API can be used in atomic services since API version 18. 774 775**System capability**: SystemCapability.ArkUI.ArkUI.Full 776 777**Parameters** 778 779| Name| Type | Mandatory| Description | 780| ------ | --------------------------------- | ---- | -------------------- | 781| 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.| 782 783**Return value** 784 785| Type| Description| 786| -------- | -------- | 787| [RotationGestureHandler](#rotationgesturehandler) | Rotation gesture handler object.| 788 789## RotationGestureHandlerOptions 790 791Provides the parameters of the rotation gesture handler. Inherits from [BaseHandlerOptions](#basehandleroptions15). 792 793**Atomic service API**: This API can be used in atomic services since API version 12. 794 795**System capability**: SystemCapability.ArkUI.ArkUI.Full 796 797| Name | Type |Read-Only |Optional| Description | 798| ------------ | ---------------------------------|----- | ---- | -------------------- | 799| fingers | number | No| Yes| Minimum number of fingers to trigger a rotation. The value ranges from 2 to 5.<br>Default value: **2**<br>While more fingers than the minimum number can be pressed to trigger the gesture, only the first two fingers participate in gesture calculation.| 800| angle | number | No| Yes| Minimum degree that can trigger the rotation gesture.<br>Default value: **1**<br>**NOTE**<br>If the value is less than or equal to 0 or greater than 360, it will be converted to the default value.| 801| isFingerCountLimited<sup>15+</sup> | boolean | No| Yes| Whether to enforce the exact number of fingers touching the screen. <br>**true**: Enforce the exact number of fingers touching the screen.<br>**false**: Do not enforce the exact number of fingers touching the screen.<br> 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.<br>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.<br>Default value: **false**.| 802 803## GestureGroupHandler 804 805Defines a type of gesture handler object for gesture groups. 806 807### constructor 808 809constructor(options?: GestureGroupGestureHandlerOptions) 810 811A constructor used to create a **GestureGroupHandler** object. 812 813**Atomic service API**: This API can be used in atomic services since API version 12. 814 815**System capability**: SystemCapability.ArkUI.ArkUI.Full 816 817**Parameters** 818 819| Name | Type | Mandatory| Description | 820| ------- | ------------------------------------------------------------ | ---- | ------------------ | 821| options | [GestureGroupGestureHandlerOptions](#gesturegroupgesturehandleroptions) | No | Parameters of the gesture group handler.| 822 823### onCancel 824 825onCancel(event: Callback\<void>): GestureGroupHandler 826 827Invoked when a cancellation event is received after the gesture group in sequential gesture recognition (**GestureMode.Sequence**) is recognized. 828 829**Atomic service API**: This API can be used in atomic services since API version 12. 830 831**System capability**: SystemCapability.ArkUI.ArkUI.Full 832 833**Parameters** 834 835| Name| Type | Mandatory| Description | 836| ------ | --------------------------------- | ---- | -------------------- | 837| event | [Callback](./ts-types.md#callback12)\<void> | Yes| Callback invoked when a cancellation event is received after the gesture group in sequential gesture recognition **GestureMode.Sequence**) is recognized.| 838 839**Return value** 840 841| Type| Description| 842| -------- | -------- | 843| GestureGroupHandler | Gesture group handler object.| 844 845## GestureGroupGestureHandlerOptions 846 847Provides the parameters of the gesture group handler. 848 849**Atomic service API**: This API can be used in atomic services since API version 12. 850 851**System capability**: SystemCapability.ArkUI.ArkUI.Full 852 853| Name | Type | Read-Only | Optional| Description | 854| ------------ | ---------------------------------|----- | ---- | -------------------- | 855| mode | [GestureMode](./ts-combined-gestures.md#gesturemode) | No| No | Recognition mode of combined gestures.<br>Default value: **GestureMode.Sequence** | 856| 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.<br>**NOTE**<br>To add both tap and double-tap gestures for a component, add two TapGestures, with the tap gesture added after the double-tap gesture.| 857 858## GesturePriority 859 860**Atomic service API**: This API can be used in atomic services since API version 12. 861 862**System capability**: SystemCapability.ArkUI.ArkUI.Full 863 864| Name| Value| Description| 865| ------| -- | -------- | 866| NORMAL | 0 | Normal priority.| 867| PRIORITY | 1 | High priority.| 868 869## Example 870 871See the example in [Gesture Modifier](ts-universal-attributes-gesture-modifier.md). 872