1# TapGesture 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9**TapGesture** is used to trigger a tap gesture with one, two, or more taps. 10 11> **NOTE** 12> 13> This gesture is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 14> 15> When both double-tap and single-tap gestures are bound to a component with the double-tap gesture bound first, the single-tap gesture will have a 300 ms delay. 16 17 18## APIs 19 20TapGesture(value?: TapGestureParameters) 21 22Sets the parameters for the tap gesture. 23 24When the tap gesture event is triggered by a keyboard or gamepad device, the [SourceTool](ts-gesture-settings.md#sourcetool9) value of the event is **Unknown**. 25 26**Atomic service API**: This API can be used in atomic services since API version 11. 27 28**System capability**: SystemCapability.ArkUI.ArkUI.Full 29 30**Parameters** 31 32| Name| Type| Mandatory| Description| 33| -------- | -------- | -------- | -------- | 34| value | [TapGestureParameters](#tapgestureparameters12) | No| Parameters for the tap gesture.| 35 36## TapGestureParameters<sup>12+</sup> 37 38> **NOTE** 39> 40> To standardize anonymous object definitions, the element definitions here have been revised in API version 12. While historical version information is preserved for anonymous objects, there may be cases where the outer element's @since version number is higher than inner elements'. This does not affect interface usability. 41 42Defines tap gesture parameters. Inherits from [BaseHandlerOptions](./ts-uigestureevent.md#basehandleroptions15). 43 44**System capability**: SystemCapability.ArkUI.ArkUI.Full 45 46| Name| Type| Read-Only| Optional| Description| 47| -------- | -------- | -------- | -------- | -------- | 48| count<sup>11+</sup> | number | No| Yes| Number of consecutive taps. If the value is less than 1 or is not set, the default value is used.<br>Default value: **1**<br>**NOTE**<br>1. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms.<br>2. If the distance between the last tapped position and the current tapped position exceeds 60 vp, gesture recognition fails. In multi-finger scenarios, the tapped position is the average position of all fingers involved in the gesture response.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 49| fingers<sup>11+</sup> | number | No| Yes| Number of fingers required to trigger a tap. The value ranges from 1 to 10. If the value is less than 1 or is not set, the default value is used.<br>Default value: **1**<br>**NOTE**<br>1. For a multi-finger gesture, recognition fails if the required number of fingers is not pressed within 300 ms after the first finger; when fingers are lifted, if the remaining number of fingers is below the threshold after lifting, all fingers must be lifted within 300 ms for the gesture to be successfully recognized.<br>2. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 50| distanceThreshold | number | No| Yes| Movement threshold for the tap gesture. If the value is less than or equal to 0 or is not set, the default value is used.<br>Default value: 2^31-1<br>**NOTE**<br>If the finger movement exceeds the preset movement threshold, the tap gesture recognition fails. If the default threshold is used during initialization and the finger moves beyond the component's touch target, the tap gesture recognition fails.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 51 52## Events 53 54> **NOTE** 55> 56> 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. 57 58**Atomic service API**: This API can be used in atomic services since API version 11. 59 60**System capability**: SystemCapability.ArkUI.ArkUI.Full 61 62### onAction 63 64onAction(event: (event: GestureEvent) => void) 65 66Callback invoked when a tap gesture is recognized. 67 68**Atomic service API**: This API can be used in atomic services since API version 11. 69 70**System capability**: SystemCapability.ArkUI.ArkUI.Full 71 72**Parameters** 73 74| Name| Type | Mandatory| Description | 75| ------ | ------------------------------------------ | ---- | ---------------------------- | 76| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the tap event.| 77 78## Attributes 79 80**System capability**: SystemCapability.ArkUI.ArkUI.Full 81 82| Name| Type | Read-Only| Optional| Description | 83| ---- | ------ | ---- | ---- | ----------------- | 84| tag<sup>11+</sup> | string | No| No| Tag for the tap 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)> | No| No| Allowed event input types for the tap gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 86 87## EventLocationInfo<sup>20+</sup> 88 89Provides coordinate information for tap gestures. 90 91**Atomic service API**: This API can be used in atomic services since API version 20. 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95| Name| Type| Mandatory| Description| 96| -------- | -------- | -------- | -------- | 97| x | number | Yes| X-coordinate relative to the upper left corner of the component.<br>Value range: [0, +∞).<br>Unit: vp.| 98| y | number | Yes| Y-coordinate relative to the upper left corner of the component.<br>Value range: [0, +∞).<br>Unit: vp.| 99| windowX | number | Yes| X-coordinate relative to the upper left corner of the window.<br>Value range: [0, +∞).<br>Unit: vp.| 100| windowY | number | Yes| Y-coordinate relative to the upper left corner of the window.<br>Value range: [0, +∞).<br>Unit: vp.| 101| displayX | number | Yes| X-coordinate relative to the upper left corner of the screen.<br>Value range: [0, +∞).<br>Unit: vp.| 102| displayY | number | Yes| Y-coordinate relative to the upper left corner of the screen.<br>Value range: [0, +∞).<br>Unit: vp.| 103 104## Example 105 106### Example 1: Implementing Double-Tap Gesture Recognition 107 108This example demonstrates the recognition of a double-tap gesture using **TapGesture**. 109 110```ts 111// xxx.ets 112@Entry 113@Component 114struct TapGestureExample { 115 @State value: string = ''; 116 117 build() { 118 Column() { 119 // The gesture event is triggered by double-tapping. 120 Text('Click twice').fontSize(28) 121 .gesture( 122 TapGesture({ count: 2 }) 123 .onAction((event: GestureEvent) => { 124 if (event) { 125 this.value = JSON.stringify(event.fingerList[0]) 126 } 127 }) 128 ) 129 Text(this.value) 130 } 131 .height(300) 132 .width(300) 133 .padding(20) 134 .border({ width: 3 }) 135 .margin(30) 136 } 137} 138``` 139 140 141 142### Example 2: Obtaining Coordinates of a Single-Tap Gesture 143 144This example demonstrates how to obtain the coordinates of a single-tap gesture using **TapGesture**. 145 146```ts 147// xxx.ets 148@Entry 149@Component 150struct TapGestureExample { 151 @State value: string = '' 152 153 build() { 154 Column() { 155 Text('Click Once').fontSize(28) 156 .gesture( 157 TapGesture({ count: 1, fingers: 1 }) 158 .onAction((event: GestureEvent | undefined) => { 159 if (event) { 160 console.info("x = ", JSON.stringify(event.tapLocation?.x)) 161 console.info("y = ", event.tapLocation?.y) 162 console.info("windowX = ", event.tapLocation?.windowX) 163 console.info("windowY = ", event.tapLocation?.windowY) 164 console.info("displayX = ", event.tapLocation?.displayX) 165 console.info("displayY = ", event.tapLocation?.displayY) 166 } 167 }) 168 ) 169 Text(this.value) 170 } 171 .height(200) 172 .width(300) 173 .padding(20) 174 .border({ width: 3 }) 175 .margin(30) 176 } 177} 178``` 179
