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 enumerated 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>Default value: **5**<br>**NOTE**<br>If a pan gesture and [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>If the value specified is less than **0**, the default value **5** is used. | 23 24## PanDirection 25 26Enumerates the pan directions. Unlike **SwipeDirection**, **PanDirection** does not have any angle restrictions. 27 28**Atomic service API**: This API can be used in atomic services since API version 11. 29 30| Name | Description | 31| -------- | -------- | 32| All | All directions. | 33| Horizontal | Horizontal panning. | 34| Vertical | Vertical panning. | 35| Left | Panning to the left. | 36| Right | Panning to the right. | 37| Up | Panning up. | 38| Down | Panning down. | 39| None | Panning disabled. | 40 41 42## PanGestureOptions 43 44The 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. 45 46PanGestureOptions(value?: { fingers?: number, direction?: PanDirection, distance?: number }) 47 48**Atomic service API**: This API can be used in atomic services since API version 11. 49 50**Parameters** 51 52| Name | Type | Mandatory | Description | 53| --------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 54| fingers | number | No | Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1** | 55| direction | [PanDirection](#pandirection) | No | Pan direction. The enumerated value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All** | 56| distance | number | No | Minimum pan distance to trigger the gesture, in vp.<br>Default value: **5**<br>**NOTE**<br>If a pan gesture and [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>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.| 57 58**APIs** 59 60| Name | Description | 61| -------- | -------- | 62| setDirection(value: [PanDirection](#pandirection)) | Sets the direction.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 63| setDistance(value: number) | Sets the distance.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 64| setFingers(value: number) | Sets the number of fingers.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 65| getDirection()<sup>12+</sup>: [PanDirection](#pandirection) | Obtains the direction.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 66 67 68## Events 69 70| Name | Description | 71| -------- | -------- | 72| 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.| 73| 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.| 74| 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.| 75| onActionCancel(event: () => void) | Invoked when a tap cancellation event is received after a pan gesture is recognized.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 76 77## Attributes 78 79**Atomic service API**: This API can be used in atomic services since API version 11. 80 81| Name | Type |Description | 82| ---- | ------ | ---------------------------------------- | 83| tag<sup>11+</sup> | string | Tag for the pan gesture. It is used to distinguish the gesture during custom gesture judgment.| 84 85## Example 86 87```ts 88// xxx.ets 89@Entry 90@Component 91struct PanGestureExample { 92 @State offsetX: number = 0 93 @State offsetY: number = 0 94 @State positionX: number = 0 95 @State positionY: number = 0 96 private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left | PanDirection.Right }) 97 98 build() { 99 Column() { 100 Column() { 101 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 102 } 103 .height(200) 104 .width(300) 105 .padding(20) 106 .border({ width: 3 }) 107 .margin(50) 108 .translate({ x: this.offsetX, y: this.offsetY, z: 0}) // Move the component with its upper left corner as the coordinate origin. 109 // Pan left or right to trigger the gesture event. 110 .gesture( 111 PanGesture(this.panOption) 112 .onActionStart((event: GestureEvent) => { 113 console.info('Pan start') 114 }) 115 .onActionUpdate((event: GestureEvent) => { 116 if (event) { 117 this.offsetX = this.positionX + event.offsetX 118 this.offsetY = this.positionY + event.offsetY 119 } 120 }) 121 .onActionEnd((event: GestureEvent) => { 122 this.positionX = this.offsetX 123 this.positionY = this.offsetY 124 console.info('Pan end') 125 }) 126 ) 127 128 Button ('Set PanGesture Trigger Condition') 129 .onClick(() => { 130 // Set the pan gesture to be triggered by two fingers moving in any direction. 131 this.panOption.setDirection(PanDirection.All) 132 this.panOption.setFingers(2) 133 }) 134 } 135 } 136} 137``` 138 139**Diagrams** 140 141Panning to the left: 142 143 144 145Click **Set PanGesture Trigger Condition** to set the pan gesture to be triggered by two fingers moving toward the lower left corner. 146 147  148
