1# PanGesture 2 3**PanGesture** is used to trigger a pan gesture when the movement distance of a finger on the screen reaches the minimum value. 4 5> **NOTE** 6> 7> This gesture is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## APIs 11 12PanGesture(value?: { fingers?: number, direction?: PanDirection, distance?: number } | [PanGestureOptions](#pangestureoptions)) 13 14**Atomic service API**: This API can be used in atomic services since API version 11. 15 16**Parameters** 17 18| Name| Type| Mandatory| Description| 19| -------- | -------- | -------- | -------- | 20| fingers | number | No| Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**<br>Value range: 1 to 10<br>**NOTE**<br>If the value is less than 1 or is not set, the default value is used.| 21| direction | [PanDirection](#pandirection) | No| Pan direction. The value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**| 22| distance | number | No| Minimum pan distance to trigger the gesture, in vp.<br>Value range: [0, +∞)<br>Default value: **5**<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 **5** is used.| 23| isFingerCountLimited<sup>15+</sup> | boolean | No| Whether to 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 touching the screen equals the configured minimum number and the swipe distance meets the threshold.<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-pangesture.md#events) event, but the [onActionEnd](ts-basic-gestures-pangesture.md#events) event can still be triggered.<br>Default value: **false**| 24 25## PanDirection 26 27Enumerates the pan directions. Unlike **SwipeDirection**, **PanDirection** has no angular restrictions. 28 29**Atomic service API**: This API can be used in atomic services since API version 11. 30 31| Name| Description| 32| -------- | -------- | 33| All | All directions.| 34| Horizontal | Horizontal direction.| 35| Vertical | Vertical direction.| 36| Left | Leftward.| 37| Right | Rightward.| 38| Up | Upward.| 39| Down | Downward.| 40| None | Panning disabled.| 41 42 43## PanGestureOptions 44 45The 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. 46 47PanGestureOptions(value?: { fingers?: number, direction?: PanDirection, distance?: number }) 48 49**Atomic service API**: This API can be used in atomic services since API version 11. 50 51**Parameters** 52 53| Name | Type | Mandatory| Description | 54| --------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 55| fingers | number | No | Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**| 56| direction | [PanDirection](#pandirection) | No | Pan direction. The enumerated value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**| 57| distance | number | No | Minimum pan distance to trigger the gesture, in vp.<br>Default value: **5**<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 **5** is used.<br>To avoid slow response and lagging during scrolling, set a reasonable pan distance.| 58 59**APIs** 60 61| Name| Description| 62| -------- | -------- | 63| setDirection(value: [PanDirection](#pandirection)) | Sets the pan direction.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 64| setDistance(value: number) | Sets the minimum pan distance to trigger the gesture, in vp.<br>Value range: [0, +∞)<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 65| setFingers(value: number) | Sets the minimum number of fingers to trigger the gesture.<br>Value range: an integer from 1 to 10<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 66| getDirection()<sup>12+</sup>: [PanDirection](#pandirection)| Obtains the pan direction.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 67| getDistance()<sup>18+</sup>: (value: number) | Obtains the minimum pan distance to trigger the gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 68 69 70## Events 71 72| Name| Description| 73| -------- | -------- | 74| onActionStart(event: (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void) | Invoked when a pan gesture is recognized.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 75| onActionUpdate(event: (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void) | Invoked when the pan gesture status is updated.<br>If **fingerList** contains multiple fingers, this callback updates the location information of only one finger each time.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 76| onActionEnd(event: (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void) | Invoked when the finger used for a pan gesture is lifted.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 77| onActionCancel(event: () => void) | Invoked when a tap cancellation event is received after a pan gesture is recognized. No gesture event information is returned.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 78| onActionCancel(event: (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void)<sup>18+</sup> | Invoked when a tap cancellation event is received after a pan gesture is recognized. Gesture event information is returned.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 79 80## Attributes 81 82| Name| Type |Description | 83| ---- | ------ | ---------------------------------------- | 84| tag<sup>11+</sup> | string | 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.| 85| allowedTypes<sup>14+</sup> | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | Allowed event input types for the pan gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 86 87## Example 88 89This example demonstrates the recognition of single-finger and double-finger pan gestures using **PanGesture**. 90 91```ts 92// xxx.ets 93@Entry 94@Component 95struct PanGestureExample { 96 @State offsetX: number = 0 97 @State offsetY: number = 0 98 @State positionX: number = 0 99 @State positionY: number = 0 100 private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left | PanDirection.Right }) 101 102 build() { 103 Column() { 104 Column() { 105 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 106 } 107 .height(200) 108 .width(300) 109 .padding(20) 110 .border({ width: 3 }) 111 .margin(50) 112 .translate({ x: this.offsetX, y: this.offsetY, z: 0}) // Move the component with its upper left corner as the coordinate origin. 113 // Pan left and right to trigger the gesture event 114 .gesture( 115 PanGesture(this.panOption) 116 .onActionStart((event: GestureEvent) => { 117 console.info('Pan start') 118 }) 119 .onActionUpdate((event: GestureEvent) => { 120 if (event) { 121 this.offsetX = this.positionX + event.offsetX 122 this.offsetY = this.positionY + event.offsetY 123 } 124 }) 125 .onActionEnd((event: GestureEvent) => { 126 this.positionX = this.offsetX 127 this.positionY = this.offsetY 128 console.info('Pan end') 129 }) 130 ) 131 132 Button('Set PanGesture Trigger Condition') 133 .onClick(() => { 134 // Change the trigger condition to double-finger panning in any direction. 135 this.panOption.setDirection(PanDirection.All) 136 this.panOption.setFingers(2) 137 }) 138 } 139 } 140} 141``` 142 143**Diagrams** 144 145Panning left: 146 147 148 149Click **Set PanGesture Trigger Condition** to set the pan gesture to be triggered by two fingers moving toward the lower left corner. 150 151  152
