1# LongPressGesture 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9用于触发长按手势事件，触发长按手势的最少手指数为1，默认最短长按时间为500毫秒。可配置duration参数控制最短长按时长。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 从API version 18开始，部分设备会优先响应系统的双指长按手势，导致应用的双指长按手势不生效。 16 17 18## 接口 19 20### LongPressGesture 21 22LongPressGesture(value?: { fingers?: number; repeat?: boolean; duration?: number }) 23 24创建长按手势对象。继承自[GestureInterface\<T>](ts-gesture-common.md#gestureinterfacet11)。 25 26当组件默认支持可拖拽时，如Text、TextInput、TextArea、HyperLink、Image和RichEditor等组件。长按手势与拖拽会出现冲突，事件优先级如下： 27 28当长按触发时间小于500毫秒时，系统优先响应长按事件而非拖拽事件。 29 30当长按触发时间达到或超过500毫秒时，系统优先响应拖拽事件而非长按事件。 31 32**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 33 34**系统能力：** SystemCapability.ArkUI.ArkUI.Full 35 36**参数：** 37 38| 参数名 | 类型 | 必填 | 说明 | 39| -------- | -------- | -------- | -------- | 40| value | { fingers?: number; repeat?: boolean; duration?: number } | 否 | 设置长按手势参数。<br> - fingers：触发长按的最少手指数，最小值为1， 最大值为10。<br/>默认值：1 <br> - repeat：是否连续触发事件回调。true表示连续触发事件回调，false表示不连续触发事件回调。<br/>默认值：false <br> - duration：触发长按的最短时间，单位为毫秒（ms）。<br/>默认值：500 | 41 42### LongPressGesture<sup>15+</sup> 43 44LongPressGesture(options?: LongPressGestureHandlerOptions) 45 46创建长按手势对象。与[LongPressGesture](#longpressgesture-1)相比，options参数新增了对isFingerCountLimited参数，表示是否检查触摸屏幕的手指数量。 47 48当组件默认支持可拖拽时，如Text、TextInput、TextArea、HyperLink、Image和RichEditor等组件。长按手势与拖拽会出现冲突，事件优先级如下： 49 50当长按触发时间小于500毫秒时，系统优先响应长按事件而非拖拽事件。 51 52当长按触发时间达到或超过500毫秒时，系统优先响应拖拽事件而非长按事件。 53 54**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58**参数：** 59 60| 参数名 | 类型 | 必填 | 说明 | 61| -------- | -------- | -------- | -------- | 62| options | [LongPressGestureHandlerOptions](./ts-gesturehandler.md#longpressgesturehandleroptions) | 否 | 长按手势处理器配置参数。 | 63 64 65## 事件 66 67> **说明：** 68> 69> 在[GestureEvent](ts-gesture-common.md#gestureevent对象说明)的fingerList元素中，手指索引编号与位置相对应，即fingerList[index]的id为index。对于先按下但未参与当前手势触发的手指，fingerList中对应的位置为空。建议优先使用fingerInfos。 70> 71> 长按手势触发后，[GestureEvent](ts-gesture-common.md#gestureevent对象说明)中fingerList和fingerInfo的信息仅在有手指按下时才会更新，手指抬起时不会更新。 72 73### onAction 74 75onAction(event: (event: GestureEvent) => void) 76 77设置长按手势识别成功回调。 78 79**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83**参数：** 84 85| 参数名 | 类型 | 必填 | 说明 | 86| ------ | ------------------------------------------ | ---- | ---------------------------- | 87| event | (event: [GestureEvent](ts-gesture-common.md#gestureevent对象说明)) => void | 是 | 长按手势识别成功回调函数。 | 88 89### onActionEnd 90 91onActionEnd(event: (event: GestureEvent) => void) 92 93设置长按手势结束回调。长按手势识别成功后，最后一根手指抬起时触发回调。 94 95**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 96 97**系统能力：** SystemCapability.ArkUI.ArkUI.Full 98 99**参数：** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| ------ | ------------------------------------------ | ---- | ---------------------------- | 103| event | (event: [GestureEvent](ts-gesture-common.md#gestureevent对象说明)) => void | 是 | 长按手势结束回调函数。 | 104 105### onActionCancel 106 107onActionCancel(event: () => void) 108 109设置长按手势取消回调。长按手势识别成功后，接收到触摸取消事件时触发回调。不返回手势事件信息。 110 111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 114 115**参数：** 116 117| 参数名 | 类型 | 必填 | 说明 | 118| ------ | ------------------------------------------ | ---- | ---------------------------- | 119| event | () => void | 是 | 长按手势取消回调函数。 | 120 121### onActionCancel<sup>18+</sup> 122 123onActionCancel(event: Callback\<GestureEvent\>) 124 125设置长按手势取消回调。长按手势识别成功后，接收到触摸取消事件时触发回调。返回手势事件信息。 126 127**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| ------ | ------------------------------------------ | ---- | ---------------------------- | 135| event | Callback\<[GestureEvent](ts-gesture-common.md#gestureevent对象说明)> | 是 | 长按手势取消回调函数。 | 136 137## 示例 138 139该示例通过LongPressGesture实现了长按手势的识别。 140 141```ts 142// xxx.ets 143@Entry 144@Component 145struct LongPressGestureExample { 146 @State count: number = 0; 147 148 build() { 149 Column() { 150 Text('LongPress onAction:' + this.count).fontSize(28) 151 // 单指长按文本触发该手势事件 152 .gesture( 153 LongPressGesture({ repeat: true }) 154 // 由于repeat设置为true，长按动作存在时会连续触发，触发间隔为duration（默认值500ms） 155 .onAction((event: GestureEvent) => { 156 if (event && event.repeat) { 157 this.count++ 158 } 159 }) 160 // 长按动作一结束触发 161 .onActionEnd((event: GestureEvent) => { 162 this.count = 0 163 }) 164 ) 165 } 166 .height(200) 167 .width(300) 168 .padding(20) 169 .border({ width: 3 }) 170 .margin(30) 171 } 172} 173``` 174 175 176
