1# PanGesture 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9**PanGesture** is used to trigger a pan gesture when the movement distance of a finger on the screen reaches the minimum value. 10 11The table below describes the scenarios that can trigger a pan gesture: 12 13| Trigger Mode | Input Source Type | Input Device Type | Remarks | 14|----------------------|---------------------|------------------------|-----------------------------------| 15| Swiping with a finger press | [SourceTool](ts-gesture-settings.md#sourcetool9).Finger | [SourceType](ts-gesture-settings.md#sourcetype8).TouchScreen | Both **axisVertical** and **axisHorizontal** are 0.| 16| Swiping with a left mouse button press | [SourceTool](ts-gesture-settings.md#sourcetool9).MOUSE | [SourceType](ts-gesture-settings.md#sourcetype8).Mouse | Both **axisVertical** and **axisHorizontal** are 0.| 17| Scrolling with a mouse wheel | [SourceTool](ts-gesture-settings.md#sourcetool9).MOUSE | [SourceType](ts-gesture-settings.md#sourcetype8).Mouse | Either **axisVertical** or **axisHorizontal** is non-zero.| 18| Swiping after pressing the left button on a touchpad | [SourceTool](ts-gesture-settings.md#sourcetool9).MOUSE | [SourceType](ts-gesture-settings.md#sourcetype8).Mouse | Both **axisVertical** and **axisHorizontal** are 0.| 19| Swiping with two fingers on a touchpad | [SourceTool](ts-gesture-settings.md#sourcetool9).TOUCHPAD | [SourceType](ts-gesture-settings.md#sourcetype8).Mouse | Either **axisVertical** or **axisHorizontal** is non-zero.| 20| Swiping with a stylus | [SourceTool](ts-gesture-settings.md#sourcetool9).Pen | [SourceType](ts-gesture-settings.md#sourcetype8).TouchScreen | Both **axisVertical** and **axisHorizontal** are 0.| 21 22> **NOTE** 23> 24> This API is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 25 26 27## APIs 28 29### PanGesture 30 31PanGesture(value?: { fingers?: number; direction?: PanDirection; distance?: number } | PanGestureOptions) 32 33Sets the pan gesture event. 34 35**Atomic service API**: This API can be used in atomic services since API version 11. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39**Parameters** 40 41| Name| Type| Mandatory| Description| 42| -------- | -------- | -------- | -------- | 43| value | { fingers?: number; direction?: PanDirection; distance?: number } \| [PanGestureOptions](#pangestureoptions) | No| Parameters for the pan gesture.<br> - **fingers**: 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.<br> - **direction**: pan direction. The value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**.<br> - **distance**: minimum pan distance to trigger the gesture, in vp.<br>Value range: [0, +∞).<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** to make the gesture more easily recognizable.<br>If the value specified is less than **0**, the default value is used.| 44 45### PanGesture<sup>15+</sup> 46 47PanGesture(options?: PanGestureHandlerOptions) 48 49Sets the pan gesture event. Compared with [PanGesture](#pangesture-1), this API adds the **isFingerCountLimited** and **distanceMap** parameters to **options**, which control whether to enforce the exact number of fingers touching the screen and specify the minimum pan distance required to trigger the gesture for different input sources, respectively. 50 51**Atomic service API**: This API can be used in atomic services since API version 15. 52 53**System capability**: SystemCapability.ArkUI.ArkUI.Full 54 55**Parameters** 56 57| Name| Type| Mandatory| Description| 58| -------- | -------- | -------- | -------- | 59| options | [PanGestureHandlerOptions](./ts-uigestureevent.md#pangesturehandleroptions) | No | Parameters of the pan gesture handler.| 60 61## PanDirection 62 63Enumerates the pan directions. Unlike **SwipeDirection**, **PanDirection** has no angular restrictions. 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69| Name| Value| Description| 70| ---- | -- | ----- | 71| All | - | All directions.| 72| Horizontal | - | Horizontal direction.| 73| Vertical | - | Vertical direction.| 74| Left | - | Leftward.| 75| Right | - | Rightward.| 76| Up | - | Upward.| 77| Down | - | Downward.| 78| None | - | Panning disabled.| 79 80 81## PanGestureOptions 82 83### constructor 84 85PanGestureOptions(value?: { fingers?: number, direction?: PanDirection, distance?: number }) 86 87The attributes of the pan gesture recognizer can be dynamically modified using the **PanGestureOptions** API. This avoids modifying attributes through state variables, which will cause a UI re-render. 88 89**Atomic service API**: This API can be used in atomic services since API version 11. 90 91**System capability**: SystemCapability.ArkUI.ArkUI.Full 92 93**Parameters** 94 95| Name| Type| Mandatory| Description| 96| --------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 97| fingers | number | No | Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**.| 98| direction | [PanDirection](#pandirection) | No | Pan direction. The enumerated value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**.| 99| distance | number | No | 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** to make the gesture more easily recognizable.<br>If the value specified is less than **0**, the default value is used.<br>To avoid slow response and lagging during scrolling, set a reasonable pan distance.| 100 101### constructor<sup>20+</sup> 102 103constructor(value?: PanGestureHandlerOptions) 104 105The attributes of the pan gesture recognizer can be dynamically modified using the **PanGestureOptions** API. This avoids modifying attributes through state variables, which will cause a UI re-render. 106 107**Atomic service API**: This API can be used in atomic services since API version 20. 108 109**System capability**: SystemCapability.ArkUI.ArkUI.Full 110 111**Parameters** 112 113| Name| Type| Mandatory| Description| 114| --------- | ---------------------- | ---- | -------------------------------- | 115| value | [PanGestureHandlerOptions](./ts-uigestureevent.md#pangesturehandleroptions) | No | Parameters of the pan gesture handler.| 116 117### setDirection 118 119setDirection(value: PanDirection) 120 121Sets the pan direction. 122 123**Atomic service API**: This API can be used in atomic services since API version 11. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Parameters** 128 129| Name| Type | Mandatory| Description | 130| ------ | ------------------------------------------ | ---- | ---------------------------- | 131| value | [PanDirection](#pandirection) | Yes | Pan direction. The enumerated value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**.| 132 133### setDirection<sup>20+</sup> 134 135setDirection(value: PanDirection): void 136 137Sets the pan direction. 138 139**Atomic service API**: This API can be used in atomic services since API version 20. 140 141**System capability**: SystemCapability.ArkUI.ArkUI.Full 142 143**Parameters** 144 145| Name| Type | Mandatory| Description | 146| ------ | ------------------------------------------ | ---- | ---------------------------- | 147| value | [PanDirection](#pandirection) | Yes | Pan direction. The enumerated value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**.| 148 149### setDistance 150 151setDistance(value: number) 152 153Sets the minimum pan distance to trigger the gesture, in vp. To avoid performance degradation due to excessive response delays or accidental releases, avoid excessively large values. For best practices, see [Reducing the Pan Distance for Gesture Recognition](https://developer.huawei.com/consumer/en/doc/best-practices-V5/bpta-application-latency-optimization-cases-V5#section1116134115286). 154 155**Atomic service API**: This API can be used in atomic services since API version 11. 156 157**System capability**: SystemCapability.ArkUI.ArkUI.Full 158 159**Parameters** 160 161| Name| Type | Mandatory| Description | 162| ------ | ------------------------------------------ | ---- | ---------------------------- | 163| value | number | 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** to make the gesture more easily recognizable.<br>If the value specified is less than **0**, the default value is used.<br>To avoid slow response and lagging during scrolling, set a reasonable pan distance.| 164 165### setDistance<sup>20+</sup> 166 167setDistance(value: number): void 168 169Sets the minimum pan distance to trigger the gesture, in vp. To avoid performance degradation due to excessive response delays or accidental releases, avoid excessively large values. For best practices, see [Reducing the Pan Distance for Gesture Recognition](https://developer.huawei.com/consumer/en/doc/best-practices-V5/bpta-application-latency-optimization-cases-V5#section1116134115286). 170 171**Atomic service API**: This API can be used in atomic services since API version 20. 172 173**System capability**: SystemCapability.ArkUI.ArkUI.Full 174 175**Parameters** 176 177| Name| Type | Mandatory| Description | 178| ------ | ------------------------------------------ | ---- | ---------------------------- | 179| value | number | 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** to make the gesture more easily recognizable.<br>If the value specified is less than **0**, the default value is used.<br>To avoid slow response and lagging during scrolling, set a reasonable pan distance.| 180 181### setFingers 182 183setFingers(value: number) 184 185Sets the minimum number of fingers to trigger the gesture. 186 187**Atomic service API**: This API can be used in atomic services since API version 11. 188 189**System capability**: SystemCapability.ArkUI.ArkUI.Full 190 191**Parameters** 192 193| Name| Type | Mandatory| Description | 194| ------ | ------------------------------------------ | ---- | ---------------------------- | 195| value | number | Yes | Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**.| 196 197### setFingers<sup>20+</sup> 198 199setFingers(value: number): void 200 201Sets the minimum number of fingers to trigger the gesture. 202 203**Atomic service API**: This API can be used in atomic services since API version 20. 204 205**System capability**: SystemCapability.ArkUI.ArkUI.Full 206 207**Parameters** 208 209| Name| Type | Mandatory| Description | 210| ------ | ------------------------------------------ | ---- | ---------------------------- | 211| value | number | Yes | Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**.| 212 213 214### getDirection<sup>12+</sup> 215 216getDirection(): PanDirection 217 218Obtains the pan direction. 219 220**Atomic service API**: This API can be used in atomic services since API version 12. 221 222**System capability**: SystemCapability.ArkUI.ArkUI.Full 223 224**Return value** 225 226| Type | Description | 227| ------ | --------- | 228| [PanDirection](#pandirection) | Pan direction.| 229 230### getDistance<sup>18+</sup> 231 232getDistance(): number 233 234Obtains the minimum pan distance to trigger the gesture. 235 236**Atomic service API**: This API can be used in atomic services since API version 18. 237 238**System capability**: SystemCapability.ArkUI.ArkUI.Full 239 240**Return value** 241 242| Type | Description | 243| ------ | --------- | 244| number | Minimum pan distance to trigger the gesture.| 245 246 247## Events 248 249**System capability**: SystemCapability.ArkUI.ArkUI.Full 250 251> **NOTE** 252> 253> 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. 254 255### onActionStart 256 257onActionStart(event: (event: GestureEvent) => void) 258 259Invoked when a pan gesture is recognized. 260 261**Atomic service API**: This API can be used in atomic services since API version 11. 262 263**System capability**: SystemCapability.ArkUI.ArkUI.Full 264 265**Parameters** 266 267| Name| Type | Mandatory| Description | 268| ------ | ------------------------------------------ | ---- | ---------------------------- | 269| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the gesture event.| 270 271### onActionUpdate 272 273onActionUpdate(event: (event: GestureEvent) => void) 274 275Invoked when the pan gesture status is updated. If **fingerList** contains multiple fingers, this callback updates the location information of only one finger each time. 276 277**Atomic service API**: This API can be used in atomic services since API version 11. 278 279**System capability**: SystemCapability.ArkUI.ArkUI.Full 280 281**Parameters** 282 283| Name| Type | Mandatory| Description | 284| ------ | ------------------------------------------ | ---- | ---------------------------- | 285| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the gesture event.| 286 287### onActionEnd 288 289onActionEnd(event: (event: GestureEvent) => void) 290 291Invoked when the finger used for a pan gesture is lifted. 292 293**Atomic service API**: This API can be used in atomic services since API version 11. 294 295**System capability**: SystemCapability.ArkUI.ArkUI.Full 296 297**Parameters** 298 299| Name| Type | Mandatory| Description | 300| ------ | ------------------------------------------ | ---- | ---------------------------- | 301| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the gesture event.| 302 303### onActionCancel 304 305onActionCancel(event: () => void) 306 307Invoked when a tap cancellation event is received after a pan gesture is recognized. No gesture event information is returned. 308 309**Atomic service API**: This API can be used in atomic services since API version 11. 310 311**System capability**: SystemCapability.ArkUI.ArkUI.Full 312 313**Parameters** 314 315| Name| Type | Mandatory| Description | 316| ------ | ------------------------------------------ | ---- | ---------------------------- | 317| event | () => void | Yes | Callback for the gesture event.| 318 319### onActionCancel<sup>18+</sup> 320 321onActionCancel(event: Callback\<GestureEvent\>) 322 323Invoked when a tap cancellation event is received after a pan gesture is recognized. Gesture event information is returned. 324 325**Atomic service API**: This API can be used in atomic services since API version 18. 326 327**System capability**: SystemCapability.ArkUI.ArkUI.Full 328 329**Parameters** 330 331| Name| Type | Mandatory| Description | 332| ------ | ------------------------------------------ | ---- | ---------------------------- | 333| event | Callback\<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes | Callback for the gesture event.| 334 335## Attributes 336 337**System capability**: SystemCapability.ArkUI.ArkUI.Full 338 339| Name| Type | Read-Only| Optional| Description | 340| ---- | ------ | ---- | ---- | ----------------------- | 341| tag<sup>11+</sup> | string | No| No| Tag for the pan gesture. It is used to distinguish the gesture during custom gesture judgment.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 342| allowedTypes<sup>14+</sup> | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | No| No| Allowed event input types for the pan gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 343 344## Example 345 346This example demonstrates the recognition of single-finger and double-finger pan gestures using **PanGesture**. 347 348```ts 349// xxx.ets 350@Entry 351@Component 352struct PanGestureExample { 353 @State offsetX: number = 0; 354 @State offsetY: number = 0; 355 @State positionX: number = 0; 356 @State positionY: number = 0; 357 private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left | PanDirection.Right }); 358 359 build() { 360 Column() { 361 Column() { 362 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 363 } 364 .height(200) 365 .width(300) 366 .padding(20) 367 .border({ width: 3 }) 368 .margin(50) 369 .translate({ x: this.offsetX, y: this.offsetY, z: 0}) // Move the component with its upper left corner as the coordinate origin. 370 // Pan left and right to trigger the gesture event 371 .gesture( 372 PanGesture(this.panOption) 373 .onActionStart((event: GestureEvent) => { 374 console.info('Pan start'); 375 console.info('Pan start timeStamp is: ' + event.timestamp); 376 }) 377 .onActionUpdate((event: GestureEvent) => { 378 if (event) { 379 this.offsetX = this.positionX + event.offsetX; 380 this.offsetY = this.positionY + event.offsetY; 381 } 382 }) 383 .onActionEnd((event: GestureEvent) => { 384 this.positionX = this.offsetX; 385 this.positionY = this.offsetY; 386 console.info('Pan end'); 387 console.info('Pan end timeStamp is: ' + event.timestamp); 388 }) 389 ) 390 391 Button('Set PanGesture Trigger Condition') 392 .onClick(() => { 393 // Change the trigger condition to double-finger panning in any direction. 394 this.panOption.setDirection(PanDirection.All); 395 this.panOption.setFingers(2); 396 }) 397 } 398 } 399} 400``` 401 402**Diagrams** 403 404Panning left: 405 406 407 408Click **Set PanGesture Trigger Condition** to set the pan gesture to be triggered by two fingers moving toward the lower left corner. 409 410  411
