1# ArkUI_NativeGestureAPI_1 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9## 概述 10 11手势模块接口集合。 12 13**起始版本：** 12 14 15**相关模块：** [ArkUI_NativeModule](capi-arkui-nativemodule.md) 16 17**所在头文件：** [native_gesture.h](capi-native-gesture-h.md) 18 19## 汇总 20 21### 成员变量 22 23| 名称 | 描述 | 24| -- | -- | 25| int32_t version | 结构版本号 = 1。 | 26 27 28### 成员函数 29 30| 名称 | 描述 | 31| -- | -- | 32| [ArkUI_GestureRecognizer* (\*createTapGesture)(int32_t countNum, int32_t fingersNum)](#createtapgesture) | 创建敲击手势。1. 支持单击、双击和多次点击事件的识别。<br> 2. 当配置多击时，上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。<br> 3. 当上次点击的位置与当前点击的位置距离超过60vp等效像素点时，手势识别失败。<br> 4. 当配置多指时，第一根手指按下后300毫秒内未有足够的手指数按下，手势识别失败，<br> 第一根手指抬起后300毫秒内未有足够的手指抬起，手势识别失败。<br> 5. 实际点击手指数超过配置值，手势识别成功。<br> | 33| [ArkUI_GestureRecognizer* (\*createLongPressGesture)(int32_t fingersNum, bool repeatResult, int32_t durationNum)](#createlongpressgesture) | 创建长按手势。1. 用于触发长按手势事件，触发长按手势的最少手指数为1，最短长按时间为500毫秒。<br> 2. 当组件默认支持可拖拽时，如Text、TextInput、TextArea、HyperLink、Image和RichEditor等组件。<br> 长按手势与拖拽会出现冲突，事件优先级如下：<br> 长按触发时间 < 500ms，长按事件优先拖拽事件响应。<br> 长按触发时间 >= 500ms，拖拽事件优先长按事件响应。<br> 3. 手指按下后若发生超过15px的移动，则判定当前长按手势识别失败。<br> | 34| [ArkUI_GestureRecognizer* (\*createPanGesture)(int32_t fingersNum, ArkUI_GestureDirectionMask directions, double distanceNum)](#createpangesture) | 创建拖动手势。1. 当滑动的最小距离超过设定的最小值时触发拖动手势事件。<br> 2. Tabs组件滑动与该拖动手势事件同时存在时，可将distanceNum值设为1，使拖动更灵敏，避免造成事件错乱。<br> | 35| [ArkUI_GestureRecognizer* (\*createPinchGesture)(int32_t fingersNum, double distanceNum)](#createpinchgesture) | 创建捏合手势。1. 触发捏合手势的最少手指为2指，最大为5指，最小识别距离为distanceNum 像素点。<br> 2. 触发手势手指可以多于fingersNum数目，但只有先落下的与fingersNum相同数目的手指参与手势计算。<br> | 36| [ArkUI_GestureRecognizer* (\*createRotationGesture)(int32_t fingersNum, double angleNum)](#createrotationgesture) | 创建旋转手势。1. 触发旋转手势的最少手指为2指，最大为5指，最小改变度数为1度。<br> 2. 触发手势手指可以多于fingers数目，但只有先落下的两指参与手势计算。<br> | 37| [ArkUI_GestureRecognizer* (\*createSwipeGesture)(int32_t fingersNum, ArkUI_GestureDirectionMask directions, double speedNum)](#createswipegesture) | 创建滑动手势。1. 用于触发滑动事件，滑动速度大于speedNum px/s时可识别成功。<br> | 38| [ArkUI_GestureRecognizer* (\*createGroupGesture)(ArkUI_GroupGestureMode gestureMode)](#creategroupgesture) | 创建手势组。 | 39| [void (\*dispose)(ArkUI_GestureRecognizer* recognizer)](#dispose) | 销毁手势，释放资源。 | 40| [int32_t (\*addChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child)](#addchildgesture) | 手势组增加子手势。 | 41| [int32_t (\*removeChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child)](#removechildgesture) | 删除子手势。 | 42| [int32_t (\*setGestureEventTarget)(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventActionTypeMask actionTypeMask, void* extraParams,void (\*targetReceiver)(ArkUI_GestureEvent* event, void* extraParams))](#setgestureeventtarget) | 创建手势关联回调方法。 | 43| [int32_t (\*addGestureToNode)(ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer, ArkUI_GesturePriority mode, ArkUI_GestureMask mask)](#addgesturetonode) | 将手势添加到UI组件。 | 44| [int32_t (\*removeGestureFromNode)(ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer)](#removegesturefromnode) | 在节点中移除手势。 | 45| [int32_t (\*setGestureInterrupterToNode)(ArkUI_NodeHandle node, ArkUI_GestureInterruptResult (\*interrupter)(ArkUI_GestureInterruptInfo* info))](#setgestureinterruptertonode) | 设置节点手势打断回调。 | 46| [ArkUI_GestureRecognizerType (\*getGestureType)(ArkUI_GestureRecognizer* recognizer)](#getgesturetype) | 获取手势类别。 | 47| [int32_t (\*setInnerGestureParallelTo)(ArkUI_NodeHandle node, void* userData, ArkUI_GestureRecognizer* (\*parallelInnerGesture)(ArkUI_ParallelInnerGestureEvent* event))](#setinnergestureparallelto) | 设置并行内部手势事件回调。 | 48| [ArkUI_GestureRecognizer* (\*createTapGestureWithDistanceThreshold)(int32_t countNum, int32_t fingersNum, double distanceThreshold)](#createtapgesturewithdistancethreshold) | 创建带移动范围限制的敲击手势。1. 支持单击、双击和多次点击事件的识别。<br> 2. 当配置多击时，上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。<br> 3. 当上次点击的位置与当前点击的位置距离超过60vp等效像素点时，手势识别失败。<br> 4. 当配置多指时，第一根手指按下后300毫秒内未有足够的手指数按下，手势识别失败，<br> 第一根手指抬起后300毫秒内未有足够的手指抬起，手势识别失败。<br> 5. 实际点击手指数超过配置值，手势识别成功。<br> 6. 当手指移动距离超出所设置的距离值时，手势识别失败。<br> | 49 50## 成员函数说明 51 52### createTapGesture() 53 54``` 55ArkUI_GestureRecognizer* (*createTapGesture)(int32_t countNum, int32_t fingersNum) 56``` 57 58**描述：** 59 60 61创建敲击手势。1. 支持单击、双击和多次点击事件的识别。<br> 2. 当配置多击时，上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。<br> 3. 当上次点击的位置与当前点击的位置距离超过60vp等效像素点时，手势识别失败。<br> 4. 当配置多指时，第一根手指按下后300毫秒内未有足够的手指数按下，手势识别失败，<br> 第一根手指抬起后300毫秒内未有足够的手指抬起，手势识别失败。<br> 5. 实际点击手指数超过配置值，手势识别成功。<br> 62 63**参数：** 64 65| 参数项 | 描述 | 66| -- | -- | 67| int32_t countNum | 识别的连续点击次数。当设置的值小于1或不设置时，会被转化为默认值 1。 | 68| int32_t fingersNum | 触发点击的手指数，最小为1指， 最大为10指。当设置小于1的值或不设置时，会被转化为默认值 1。 | 69 70**返回：** 71 72| 类型 | 说明 | 73|------------------------------| -- | 74| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的敲击手势指针。 | 75 76### createLongPressGesture() 77 78``` 79ArkUI_GestureRecognizer* (*createLongPressGesture)(int32_t fingersNum, bool repeatResult, int32_t durationNum) 80``` 81 82**描述：** 83 84 85创建长按手势。1. 用于触发长按手势事件，触发长按手势的最少手指数为1，最短长按时间为500毫秒。<br> 2. 当组件默认支持可拖拽时，如Text、TextInput、TextArea、HyperLink、Image和RichEditor等组件。<br> 长按手势与拖拽会出现冲突，事件优先级如下：<br> 长按触发时间 < 500ms，长按事件优先拖拽事件响应。<br> 长按触发时间 >= 500ms，拖拽事件优先长按事件响应。<br> 3. 手指按下后若发生超过15px的移动，则判定当前长按手势识别失败。<br> 86 87**参数：** 88 89| 参数项 | 描述 | 90| -- | -- | 91| int32_t fingersNum | 触发长按的最少手指数，最小为1指， 最大取值为10指。 | 92| bool repeatResult | 是否连续触发事件回调。 | 93| int32_t durationNum | 触发长按的最短时间，单位为毫秒（ms）。设置小于等于0时，按照默认值500处理。 | 94 95**返回：** 96 97| 类型 | 说明 | 98| -- | -- | 99| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的敲击手势指针。 | 100 101### createPanGesture() 102 103``` 104ArkUI_GestureRecognizer* (*createPanGesture)(int32_t fingersNum, ArkUI_GestureDirectionMask directions, double distanceNum) 105``` 106 107**描述：** 108 109 110创建拖动手势。1. 当滑动的最小距离超过设定的最小值时触发拖动手势事件。<br> 2. Tabs组件滑动与该拖动手势事件同时存在时，可将distanceNum值设为1，使拖动更灵敏，避免造成事件错乱。<br> 111 112**参数：** 113 114| 参数项 | 描述 | 115|----------------------------------------------------------------------| -- | 116| int32_t fingersNum | 用于指定触发拖动的最少手指数，最小为1指，最大取值为10指。当设置的值小于1或不设置时，会被转化为默认值 1。 | 117| [ArkUI_GestureDirectionMask](capi-native-gesture-h.md#变量) directions | 用于指定触发拖动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。 | 118| double distanceNum | 用于指定触发拖动手势事件的最小拖动距离，单位为px。当设定的值小于等于0时，按默认值5px处理。 | 119 120**返回：** 121 122| 类型 | 说明 | 123| -- | -- | 124| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的拖动手势指针。 | 125 126### createPinchGesture() 127 128``` 129ArkUI_GestureRecognizer* (*createPinchGesture)(int32_t fingersNum, double distanceNum) 130``` 131 132**描述：** 133 134 135创建捏合手势。1. 触发捏合手势的最少手指为2指，最大为5指，最小识别距离为distanceNum 像素点。<br> 2. 触发手势手指可以多于fingersNum数目，但只有先落下的与fingersNum相同数目的手指参与手势计算。<br> 136 137**参数：** 138 139| 参数项 | 描述 | 140| -- | -- | 141| int32_t fingersNum | 触发捏合的最少手指数, 最小为2指，最大为5指。默认值：2。 | 142| double distanceNum | 最小识别距离，单位为px。当设置识别距离的值小于等于0时，会被转化为默认值5px处理。 | 143 144**返回：** 145 146| 类型 | 说明 | 147| -- | -- | 148| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的手势指针。 | 149 150### createRotationGesture() 151 152``` 153ArkUI_GestureRecognizer* (*createRotationGesture)(int32_t fingersNum, double angleNum) 154``` 155 156**描述：** 157 158 159创建旋转手势。1. 触发旋转手势的最少手指为2指，最大为5指，最小改变度数为1度。<br> 2. 触发手势手指可以多于fingers数目，但只有先落下的两指参与手势计算。<br> 160 161**参数：** 162 163| 参数项 | 描述 | 164| -- | -- | 165| int32_t fingersNum | 触发旋转的最少手指数, 最小为2指，最大为5指。默认值：2。 | 166| double angleNum | 触发旋转手势的最小改变度数，单位为deg。默认值：1。当改变度数的值小于等于0或大于360时，会被转化为默认值 1。 | 167 168**返回：** 169 170| 类型 | 说明 | 171| -- | -- | 172| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的手势指针。 | 173 174### createSwipeGesture() 175 176``` 177ArkUI_GestureRecognizer* (*createSwipeGesture)(int32_t fingersNum, ArkUI_GestureDirectionMask directions, double speedNum) 178``` 179 180**描述：** 181 182 183创建滑动手势。1. 用于触发滑动事件，滑动速度大于speedNum px/s时可识别成功。<br> 184 185**参数：** 186 187| 参数项 | 描述 | 188| -- | -- | 189| int32_t fingersNum | 触发滑动的最少手指数，默认为1，最小为1指，最大为10指。 | 190| [ArkUI_GestureDirectionMask](capi-native-gesture-h.md#变量) directions | 触发滑动手势的滑动方向。 | 191| double speedNum | 识别滑动的最小速度，单位 px/s。当设置滑动速度的值小于等于0时，会被转化为默认值100px/s。 | 192 193**返回：** 194 195| 类型 | 说明 | 196| -- | -- | 197| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的手势指针。 | 198 199### createGroupGesture() 200 201``` 202ArkUI_GestureRecognizer* (*createGroupGesture)(ArkUI_GroupGestureMode gestureMode) 203``` 204 205**描述：** 206 207 208创建手势组。 209 210**参数：** 211 212| 参数项 | 描述 | 213|---------------------------------------------------------------------------------------| -- | 214| [ArkUI_GroupGestureMode](capi-native-gesture-h.md#arkui_groupgesturemode) gestureMode | 手势组模式。 | 215 216**返回：** 217 218| 类型 | 说明 | 219| -- | -- | 220| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的手势组指针。 | 221 222### dispose() 223 224``` 225void (*dispose)(ArkUI_GestureRecognizer* recognizer) 226``` 227 228**描述：** 229 230 231销毁手势，释放资源。 232 233**参数：** 234 235| 参数项 | 描述 | 236|---------------------------------------------------------------------------------------| -- | 237| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* recognizer| 指向自定义弹窗控制器的指针。 | 238 239### addChildGesture() 240 241``` 242int32_t (*addChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child) 243``` 244 245**描述：** 246 247 248手势组增加子手势。 249 250**参数：** 251 252| 参数项 | 描述 | 253| -- | -- | 254| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* group | 需要被关联子手势的手势组。 | 255| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* child | 子手势。 | 256 257**返回：** 258 259| 类型 | 说明 | 260| -- | -- | 261| int32_t | 0 - 成功。<br> 401 - 参数错误。比如添加手势到非手势组对象内。 | 262 263### removeChildGesture() 264 265``` 266int32_t (*removeChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child) 267``` 268 269**描述：** 270 271 272删除子手势。 273 274**参数：** 275 276| 参数项 | 描述 | 277| -- | -- | 278| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* group | 需要被删除子手势的手势组。 | 279| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* child | 子手势。 | 280 281**返回：** 282 283| 类型 | 说明 | 284| -- | -- | 285| int32_t | 0 - 成功。<br> 401 - 参数错误。 | 286 287### setGestureEventTarget() 288 289``` 290int32_t (*setGestureEventTarget)(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventActionTypeMask actionTypeMask, void* extraParams,void (*targetReceiver)(ArkUI_GestureEvent* event, void* extraParams)) 291``` 292 293**描述：** 294 295 296创建手势关联回调方法。 297 298**参数：** 299 300| 参数项 | 描述 | 301|-------------------------------------------------------------------------------------------| -- | 302| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* recognizer | 需要被绑定回调事件的各类手势指针。 | 303| [ArkUI_GestureEventActionTypeMask](capi-native-gesture-h.md#变量) actionTypeMask | 需要相应的手势事件类型集合，一次性可以注册多个回调，在回调中区分回调事件类型。例：actionTypeMask = GESTURE_EVENT_ACTION_ACCEPT | GESTURE_EVENT_ACTION_UPDATE; | 304| void* extraParams | targetReceiver 回调时传入的上下文数据。 | 305| targetReceiver | 对应注册手势类型的事件回调处理， event 返回手势回调数据。 | 306 307**返回：** 308 309| 类型 | 说明 | 310| -- | -- | 311| int32_t | 0 - 成功。<br> 401 - 参数错误。 | 312 313### addGestureToNode() 314 315``` 316int32_t (*addGestureToNode)(ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer, ArkUI_GesturePriority mode, ArkUI_GestureMask mask) 317``` 318 319**描述：** 320 321 322将手势添加到UI组件。 323 324**参数：** 325 326| 参数项 | 描述 | 327|-------------------------------------------------------------------------------------------| -- | 328| [ArkUI_NodeHandle](capi-arkui-nativemodule-arkui-node8h.md) node | 需要被绑定手势的ArkUI组件。 | 329| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* recognizer | 绑定此节点的手势。 | 330| [ArkUI_GesturePriority](capi-native-gesture-h.md#arkui_gesturepriority) mode | 标识此手势的模式（NORMAL_GESTURE， PARALLEL_GESTURE， PRIORITY_GESTURE）。 | 331| [ArkUI_GestureMask](capi-native-gesture-h.md#arkui_gesturemask) mask | 手势屏蔽模式。 | 332 333**返回：** 334 335| 类型 | 说明 | 336| -- | -- | 337| int32_t | 0 - 成功。<br> 401 - 参数错误。 | 338 339### removeGestureFromNode() 340 341``` 342int32_t (*removeGestureFromNode)(ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer) 343``` 344 345**描述：** 346 347 348在节点中移除手势。 349 350**参数：** 351 352| 参数项 | 描述 | 353| -- | -- | 354| [ArkUI_NodeHandle](capi-arkui-nativemodule-arkui-node8h.md) node | 需要被移除手势的节点。 | 355| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* recognizer | 需要被移除的手势。 | 356 357**返回：** 358 359| 类型 | 说明 | 360| -- | -- | 361| int32_t | 0 - 成功。<br> 401 - 参数错误。 | 362 363### setGestureInterrupterToNode() 364 365``` 366int32_t (*setGestureInterrupterToNode)(ArkUI_NodeHandle node, ArkUI_GestureInterruptResult (*interrupter)(ArkUI_GestureInterruptInfo* info)) 367``` 368 369**描述：** 370 371 372设置节点手势打断回调。 373 374**参数：** 375 376| 参数项 | 描述 | 377|------------------------------------------------------------------| -- | 378| [ArkUI_NodeHandle](capi-arkui-nativemodule-arkui-node8h.md) node | 需要被设置手势打断回调的ArkUI节点。 | 379| interrupter | 打断回调, info 返回手势打断数据。interrupter 返回 GESTURE_INTERRUPT_RESULT_CONTINUE, 手势正常进行； 返回 GESTURE_INTERRUPT_RESULT_REJECT 手势打断。 | 380 381**返回：** 382 383| 类型 | 说明 | 384| -- | -- | 385| int32_t | 0 - 成功。<br> 401 - 参数错误。 | 386 387### getGestureType() 388 389``` 390ArkUI_GestureRecognizerType (*getGestureType)(ArkUI_GestureRecognizer* recognizer) 391``` 392 393**描述：** 394 395 396获取手势类别。 397 398**参数：** 399 400| 参数项 | 描述 | 401| -- | -- | 402| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* recognizer | 手势指针。 | 403 404**返回：** 405 406| 类型 | 说明 | 407|-------------------------------------------------------------------------------------| -- | 408| [ArkUI_GestureRecognizerType](capi-native-gesture-h.md#arkui_gesturerecognizertype) | 手势类型。 | 409 410### setInnerGestureParallelTo() 411 412``` 413int32_t (*setInnerGestureParallelTo)(ArkUI_NodeHandle node, void* userData, ArkUI_GestureRecognizer* (*parallelInnerGesture)(ArkUI_ParallelInnerGestureEvent* event)) 414``` 415 416**描述：** 417 418 419设置并行内部手势事件回调。 420 421**参数：** 422 423| 参数项 | 描述 | 424|------------------------------------------------------------------| -- | 425| [ArkUI_NodeHandle](capi-arkui-nativemodule-arkui-node8h.md) node | 需要被设置并行内部手势事件回调的ArkUI节点。 | 426| void* userData | 用户自定义数据。 | 427| parallelInnerGesture | 并行内部手势事件，event 返回并行内部手势事件数据。parallelInnerGesture 返回 需要并行的手势识别器指针。 | 428 429**返回：** 430 431| 类型 | 说明 | 432| -- | -- | 433| int32_t | [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) - 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) - 参数错误。 | 434 435### createTapGestureWithDistanceThreshold() 436 437``` 438ArkUI_GestureRecognizer* (*createTapGestureWithDistanceThreshold)(int32_t countNum, int32_t fingersNum, double distanceThreshold) 439``` 440 441**描述：** 442 443 444创建带移动范围限制的敲击手势。1. 支持单击、双击和多次点击事件的识别。<br> 2. 当配置多击时，上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。<br> 3. 当上次点击的位置与当前点击的位置距离超过60vp等效像素点时，手势识别失败。<br> 4. 当配置多指时，第一根手指按下后300毫秒内未有足够的手指数按下，手势识别失败，<br> 第一根手指抬起后300毫秒内未有足够的手指抬起，手势识别失败。<br> 5. 实际点击手指数超过配置值，手势识别成功。<br> 6. 当手指移动距离超出所设置的距离值时，手势识别失败。<br> 445 446**参数：** 447 448| 参数项 | 描述 | 449| -- | -- | 450| int32_t countNum | 识别的连续点击次数。当设置的值小于1或不设置时，会被转化为默认值 1。 | 451| int32_t fingersNum | 触发点击的手指数，最小为1指， 最大为10指。当设置小于1的值或不设置时，会被转化为默认值 1。 | 452| double distanceThreshold | 手指允许的移动距离范围。当设置的值小于0或者不设置时，会被转化为默认值无穷大。 | 453 454**返回：** 455 456| 类型 | 说明 | 457| -- | -- | 458| [ArkUI_GestureRecognizer](capi-arkui-nativemodule-arkui-gesturerecognizer.md)* | 返回创建的敲击手势指针。 | 459 460 461