1# LongPressGesture 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9**LongPressGesture** is used to trigger a long press gesture. This gesture requires one or more fingers to be held down for a specified duration, which is 500 ms by default and can be adjusted using the **duration** parameter. 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> On some devices, the system's two-finger long press gesture may take precedence, causing the application's two-finger long press gesture to be ineffective. 16 17 18## APIs 19 20### LongPressGesture 21 22LongPressGesture(value?: { fingers?: number, repeat?: boolean, duration?: number }) 23 24Sets the parameters for the long press gesture. 25 26In components that support drag actions by default, such as **Text**, **TextInput**, **TextArea**, **HyperLink**, **Image**, and **RichEditor**, the long press gesture may conflict with the drag action. If this occurs, the event priority is determined as follows: 27 28If the long press duration is less than 500 milliseconds, the system prioritizes the long press event over the drag event. 29 30If the long press duration reaches or exceeds 500 milliseconds, the system prioritizes the drag event over the long press event. 31 32**Atomic service API**: This API can be used in atomic services since API version 11. 33 34**System capability**: SystemCapability.ArkUI.ArkUI.Full 35 36**Parameters** 37 38| Name| Type| Mandatory| Description| 39| -------- | -------- | -------- | -------- | 40| value | { fingers?: number, repeat?: boolean, duration?: number } | No| Parameters for the long press gesture.<br> - **fingers**: minimum number of fingers to trigger a long press gesture. The value ranges from 1 to 10.<br>Default value: **1**.<br> - **repeat**: whether to continuously trigger the event callback. The value **true** means to continuously trigger the event callback, and **false** means the opposite.<br>Default value: **false**.<br> - **duration**: minimum hold-down time, in ms.<br>Default value: **500**.| 41 42### LongPressGesture<sup>15+</sup> 43 44LongPressGesture(options?: LongPressGestureHandlerOptions) 45 46Sets the parameters for the long press gesture. Compared with [LongPressGesture](#longpressgesture-1), this API adds the **isFingerCountLimited** parameter to **options**, which determines whether to enforce the exact number of fingers touching the screen. 47 48In components that support drag actions by default, such as **Text**, **TextInput**, **TextArea**, **HyperLink**, **Image**, and **RichEditor**, the long press gesture may conflict with the drag action. If this occurs, the event priority is determined as follows: 49 50If the long press duration is less than 500 milliseconds, the system prioritizes the long press event over the drag event. 51 52If the long press duration reaches or exceeds 500 milliseconds, the system prioritizes the drag event over the long press event. 53 54**Atomic service API**: This API can be used in atomic services since API version 15. 55 56**System capability**: SystemCapability.ArkUI.ArkUI.Full 57 58**Parameters** 59 60| Name| Type| Mandatory| Description| 61| -------- | -------- | -------- | -------- | 62| options | [LongPressGestureHandlerOptions](./ts-uigestureevent.md#longpressgesturehandleroptions) | No| Parameters of the long press gesture handler.| 63 64 65## Events 66 67> **NOTE** 68> 69> 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. 70> 71> Once a long press gesture is triggered, the information in **fingerList** and **fingerInfo** within the [GestureEvent](ts-gesture-settings.md#gestureevent) object is only updated when fingers are pressed down and not updated when fingers are lifted. 72 73### onAction 74 75onAction(event: (event: GestureEvent) => void) 76 77Invoked when a long press gesture is recognized. 78 79**Atomic service API**: This API can be used in atomic services since API version 11. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83**Parameters** 84 85| Name| Type | Mandatory| Description | 86| ------ | ------------------------------------------ | ---- | ---------------------------- | 87| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the long press event.| 88 89### onActionEnd 90 91onActionEnd(event: (event: GestureEvent) => void) 92 93Invoked when the last finger is lifted after the long press gesture is recognized. 94 95**Atomic service API**: This API can be used in atomic services since API version 11. 96 97**System capability**: SystemCapability.ArkUI.ArkUI.Full 98 99**Parameters** 100 101| Name| Type | Mandatory| Description | 102| ------ | ------------------------------------------ | ---- | ---------------------------- | 103| event | (event: [GestureEvent](ts-gesture-settings.md#gestureevent)) => void | Yes | Callback for the long press event.| 104 105### onActionCancel 106 107onActionCancel(event: () => void) 108 109Invoked when a tap cancellation event is received after the long press gesture is recognized. No gesture event information is returned. 110 111**Atomic service API**: This API can be used in atomic services since API version 11. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Full 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ------------------------------------------ | ---- | ---------------------------- | 119| event | () => void | Yes | Callback for the long press event.| 120 121### onActionCancel<sup>18+</sup> 122 123onActionCancel(event: Callback\<GestureEvent\>) 124 125Invoked when a tap cancellation event is received after the long press gesture is recognized. Gesture event information is returned. 126 127**Atomic service API**: This API can be used in atomic services since API version 18. 128 129**System capability**: SystemCapability.ArkUI.ArkUI.Full 130 131**Parameters** 132 133| Name| Type | Mandatory| Description | 134| ------ | ------------------------------------------ | ---- | ---------------------------- | 135| event | Callback\<[GestureEvent](ts-gesture-settings.md#gestureevent)> | Yes | Callback for the long press event.| 136 137## Attributes 138 139**System capability**: SystemCapability.ArkUI.ArkUI.Full 140 141| Name| Type | Read-Only| Optional| Description | 142| ---- | ------ | ----------- | ------------ | ----------------- | 143| tag<sup>11+</sup> | string | No| No| Tag for the long press 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.| 144| allowedTypes<sup>14+</sup> | Array\<[SourceTool](ts-gesture-settings.md#sourcetool9)> | No| No| Allowed event input types for the long press gesture.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 145 146 147## Example 148 149This example demonstrates the recognition of a long press gesture using **LongPressGesture**. 150 151```ts 152// xxx.ets 153@Entry 154@Component 155struct LongPressGestureExample { 156 @State count: number = 0; 157 158 build() { 159 Column() { 160 Text('LongPress onAction:' + this.count).fontSize(28) 161 // This gesture event is triggered when the text is long-pressed with a single finger. 162 .gesture( 163 LongPressGesture({ repeat: true }) 164 // Since repeat is set to true, the event callback is continuously triggered during the long press, with the triggering interval specified by duration (500 ms by default). 165 .onAction((event: GestureEvent) => { 166 if (event && event.repeat) { 167 this.count++ 168 } 169 }) 170 // Triggered when the long press gesture ends. 171 .onActionEnd((event: GestureEvent) => { 172 this.count = 0 173 }) 174 ) 175 } 176 .height(200) 177 .width(300) 178 .padding(20) 179 .border({ width: 3 }) 180 .margin(30) 181 } 182} 183``` 184 185 186
