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>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 24## PanDirection 25 26Enumerates the pan directions. Unlike **SwipeDirection**, **PanDirection** has no angular 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 direction.| 34| Vertical | Vertical direction.| 35| Left | Leftward.| 36| Right | Rightward.| 37| Up | Upward.| 38| Down | Downward.| 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 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.| 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| Name| Type |Description | 80| ---- | ------ | ---------------------------------------- | 81| 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.| 82| 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.| 83 84## Example 85 86This example demonstrates the recognition of single-finger and double-finger pan gestures using **PanGesture**. 87 88```ts 89// xxx.ets 90@Entry 91@Component 92struct PanGestureExample { 93 @State offsetX: number = 0 94 @State offsetY: number = 0 95 @State positionX: number = 0 96 @State positionY: number = 0 97 private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left | PanDirection.Right }) 98 99 build() { 100 Column() { 101 Column() { 102 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 103 } 104 .height(200) 105 .width(300) 106 .padding(20) 107 .border({ width: 3 }) 108 .margin(50) 109 .translate({ x: this.offsetX, y: this.offsetY, z: 0}) // Move the component with its upper left corner as the coordinate origin. 110 // Pan left and right to trigger the gesture event 111 .gesture( 112 PanGesture(this.panOption) 113 .onActionStart((event: GestureEvent) => { 114 console.info('Pan start') 115 }) 116 .onActionUpdate((event: GestureEvent) => { 117 if (event) { 118 this.offsetX = this.positionX + event.offsetX 119 this.offsetY = this.positionY + event.offsetY 120 } 121 }) 122 .onActionEnd((event: GestureEvent) => { 123 this.positionX = this.offsetX 124 this.positionY = this.offsetY 125 console.info('Pan end') 126 }) 127 ) 128 129 Button('Set PanGesture Trigger Condition') 130 .onClick(() => { 131 // Change the trigger condition to double-finger panning in any direction. 132 this.panOption.setDirection(PanDirection.All) 133 this.panOption.setFingers(2) 134 }) 135 } 136 } 137} 138``` 139 140**Diagrams** 141 142Panning left: 143 144 145 146Click **Set PanGesture Trigger Condition** to set the pan gesture to be triggered by two fingers moving toward the lower left corner. 147 148  149
