1# PinchGesture 2 3**PinchGesture** is used to trigger a pinch gesture, which requires two to five fingers with a minimum 5 vp distance between the fingers. 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 12PinchGesture(value?: { fingers?: number, distance?: number }) 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 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.| 21| distance | number | No| Minimum recognition distance, in vp.<br>Default value: **5**<br>**NOTE**<br>Value range: [0, +∞). If the value is less than or equal to 0, the default value is used.| 22| 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 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**| 23 24 25## Events 26 27| Name| Description| 28| -------- | -------- | 29| onActionStart(event:(event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void) | Triggered when a pinch gesture is recognized.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 30| onActionUpdate(event:(event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void) | Triggered when the user moves the finger in the pinch gesture on the screen.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 31| onActionEnd(event:(event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void) | Triggered when the fingers used for the pinch gesture are lifted.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 32| onActionCancel(event: () => void) | Triggered when a tap cancellation event is received after the pinch 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.| 33| onActionCancel(event:(event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void)<sup>18+</sup> | Triggered when a tap cancellation event is received after the pinch gesture is recognized. Gesture event information is returned.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 34 35## Attributes 36 37| Name| Type |Description | 38| ---- | ------ | ---------------------------------------- | 39| tag<sup>11+</sup> | string | Tag for the pinch gesture. It is used to distinguish the gesture during custom gesture recognition.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| allowedTypes<sup>14+</sup> | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | Allowed event input types for the pinch gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 41 42## Example 43 44This example demonstrates the recognition of a three-finger pinch gesture using **PinchGesture**. 45 46```ts 47// xxx.ets 48@Entry 49@Component 50struct PinchGestureExample { 51 @State scaleValue: number = 1 52 @State pinchValue: number = 1 53 @State pinchX: number = 0 54 @State pinchY: number = 0 55 56 build() { 57 Column() { 58 Column() { 59 Text('PinchGesture scale:\n' + this.scaleValue) 60 Text('PinchGesture center:\n(' + this.pinchX + ',' + this.pinchY + ')') 61 } 62 .height(200) 63 .width(300) 64 .padding(20) 65 .border({ width: 3 }) 66 .margin({ top: 100 }) 67 .scale({ x: this.scaleValue, y: this.scaleValue, z: 1 }) 68 // The gesture event is triggered by pinching three fingers together. 69 .gesture( 70 PinchGesture({ fingers: 3 }) 71 .onActionStart((event: GestureEvent) => { 72 console.info('Pinch start') 73 }) 74 .onActionUpdate((event: GestureEvent) => { 75 if (event) { 76 this.scaleValue = this.pinchValue * event.scale 77 this.pinchX = event.pinchCenterX 78 this.pinchY = event.pinchCenterY 79 } 80 }) 81 .onActionEnd((event: GestureEvent) => { 82 this.pinchValue = this.scaleValue 83 console.info('Pinch end') 84 }) 85 ) 86 }.width('100%') 87 } 88} 89``` 90 91  92
