1# 自定义手势判定 2 3为组件提供自定义手势判定能力。开发者可根据需要，在手势识别期间，决定是否响应手势。 4 5> **说明：** 6> 7> 从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## onGestureJudgeBegin 11onGestureJudgeBegin(callback: (gestureInfo: GestureInfo, event: BaseGestureEvent) => GestureJudgeResult): T 12 13**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 14 15**参数：** 16| 参数名 | 参数类型 | 必填 | 参数描述 | 17| ---------- | -------------------------- | ------- | ----------------------------- | 18| callback | (gestureInfo: [GestureInfo](#gestureinfo对象说明), event: [BaseGestureEvent](#basegestureevent对象说明)) => [GestureJudgeResult](#gesturejudgeresult11) | 是 | 给组件绑定自定义手势判定回调，当绑定到该组件的手势被接受时，会触发用户定义的回调来获取结果。 | 19 20**返回值：** 21 22| 类型 | 说明 | 23| -------- | -------- | 24| T | 返回当前组件。 | 25 26 27## GestureJudgeResult<sup>11+</sup> 28 29**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.ArkUI.ArkUI.Full 32 33| 名称 | 描述 | 34| ----- | -------------------------------------- | 35| CONTINUE | 不影响系统手势判定流程。| 36| REJECT | 对于用户自定义的手势判定结果为失败。| 37 38## GestureInfo对象说明 39 40**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 41 42| 名称 | 类型 | 描述 | 43| --------------- | ------------------------- | -----------| 44| tag | string | 手势标记。<br/>**说明：**<br/>如果未设置事件标识tag属性的情况下，此处tag不返回或者返回undefined。 | 45| type | [GestureControl.GestureType](#gesturetype11) | 手势类型。<br/>**说明：**<br/> 当手势为未暴露类型的系统内置手势事件时，type的值为-1。 | 46| isSystemGesture | boolean | 判断当前手势是否是组件自带的手势。<br/>默认值：false | 47 48## GestureType<sup>11+</sup> 49 50**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 51 52**系统能力：** SystemCapability.ArkUI.ArkUI.Full 53 54| 名称 | 值 | 描述 | 55| ----- | -------- | -------------------------------------- | 56| TAP_GESTURE | 0 | 点击手势| 57| LONG_PRESS_GESTURE | 1 | 长按手势| 58| PAN_GESTURE | 2 | 拖动手势| 59| PINCH_GESTURE | 3 | 捏合手势| 60| SWIPE_GESTURE | 4 | 滑动手势| 61| ROTATION_GESTURE | 5 | 旋转手势| 62| DRAG | 6 | 拖拽| 63| CLICK | 7 | 点击| 64 65## BaseEvent对象说明 66 67 68| 名称 | 类型 | 描述 | 69| ---------| ---------------------------------------- | -----------| 70| target | [EventTarget](ts-universal-events-click.md#eventtarget8对象说明) | 触发手势事件的元素对象显示区域。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 71| timestamp| number | 事件时间戳。<br>单位：ns<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 72| source | [SourceType](ts-gesture-settings.md#sourcetype枚举说明) | 事件输入设备。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 73| pressure | number | 按压的压力大小。<br/>默认值：0<br/>取值范围：[0,65535)，压力越大值越大。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 74| tiltX | number | 手写笔在设备平面上的投影与设备平面X轴的夹角。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 75| tiltY | number | 手写笔在设备平面上的投影与设备平面Y轴的夹角。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| sourceTool | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9) | 事件输入源。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 77| axisHorizontal<sup>12+</sup> | number | 水平轴值。<br/>**说明：**<br/>当前仅在由鼠标滚轮或者触控板双指滑动场景下触发的Pan手势中可以获取。<br/>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 78| axisVertical<sup>12+</sup> | number | 垂直轴值。<br/>**说明：**<br/>当前仅在由鼠标滚轮或者触控板双指滑动场景下触发的Pan手势中可以获取。<br/>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 79| getModifierKeyState<sup>12+</sup> | (Array<string>) => bool | 获取功能键按压状态。报错信息请参考以下错误码。支持功能键 'Ctrl'\|'Alt'\|'Shift'\|'Fn'，设备外接带Fn键的键盘不支持Fn键查询。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 80| deviceId<sup>12+</sup> | number | 触发当前事件的输入设备ID。<br/>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 81 82**错误码**： 83 84以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 85 86| 错误码ID | 错误信息 | 87| ------- | -------- | 88| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 89 90## BaseGestureEvent对象说明 91继承于[BaseEvent](#baseevent对象说明)。 92 93**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 94 95| 名称 | 类型 | 描述 | 96| --------- | ---------------------------------------- | -----------| 97| fingerList | [FingerInfo[]](ts-gesture-settings.md#fingerinfo对象说明8) | 触发事件的所有手指信息。 | 98 99## TapGestureEvent对象说明 100继承于[BaseGestureEvent](#basegestureevent对象说明)。可将该对象作为[onGestureJudgeBegin](#ongesturejudgebegin)的event参数来传递。 101 102**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 103 104## LongPressGestureEvent对象说明 105继承于[BaseGestureEvent](#basegestureevent对象说明)。可将该对象作为[onGestureJudgeBegin](#ongesturejudgebegin)的event参数来传递。 106 107**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 108 109| 名称 | 类型 | 描述 | 110| --------- | ---------------------------------------- | -----------| 111| repeat | boolean | 是否为重复触发事件。 | 112 113## PanGestureEvent对象说明 114继承于[BaseGestureEvent](#basegestureevent对象说明)。可将该对象作为[onGestureJudgeBegin](#ongesturejudgebegin)的event参数来传递。 115 116**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 117 118| 名称 | 类型 | 描述 | 119| --------- | ---------------------------------------- | -----------| 120| offsetX | number | 手势事件x轴相对当前组件元素原始区域的偏移量，单位为vp，从左向右滑动offsetX为正，反之为负。 | 121| offsetY | number | 手势事件y轴相对当前组件元素原始区域的偏移量，单位为vp，从上向下滑动offsetY为正，反之为负。 | 122| velocityX | number | 获取当前手势的x轴方向速度。坐标轴原点为屏幕左上角，分正负方向速度，从左往右为正，反之为负。单位为vp/s。 | 123| velocityY | number | 获取当前手势的y轴方向速度。坐标轴原点为屏幕左上角，分正负方向速度，从上往下为正，反之为负。单位为vp/s。| 124| velocity | number | 获取当前的主方向速度。为xy轴方向速度的平方和的算术平方根。单位为vp/s。 | 125 126## PinchGestureEvent对象说明 127 128**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 129 130继承于[BaseGestureEvent](#basegestureevent对象说明)。可将该对象作为[onGestureJudgeBegin](#ongesturejudgebegin)的event参数来传递。 131| 名称 | 类型 | 描述 | 132| ------------ | ---------------------------------------- | -----------| 133| scale | number | 缩放比例。 | 134| pinchCenterX | number | 捏合手势中心点相对于当前组件元素原始区域左上角x轴坐标，单位为vp。 | 135| pinchCenterY | number | 捏合手势中心点相对于当前组件元素原始区域左上角y轴坐标，单位为vp。 | 136 137## RotationGestureEvent对象说明 138 139**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 140 141继承于[BaseGestureEvent](#basegestureevent对象说明)。可将该对象作为[onGestureJudgeBegin](#ongesturejudgebegin)的event参数来传递。 142| 名称 | 类型 | 描述 | 143| ------------ | ---------------------------------------- | -----------| 144| angle | number | 表示旋转角度，单位为deg。<br/>**说明：**<br/>角度计算方式：滑动手势被识别到后，连接两根手指之间的线被识别为起始线条，随着手指的滑动，手指之间的线条会发生旋转，根据起始线条两端点和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角，最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系，顺时针旋转为0到180度，逆时针旋转为-180到0度。 | 145 146## SwipeGestureEvent对象说明 147继承于[BaseGestureEvent](#basegestureevent对象说明)。可将该对象作为[onGestureJudgeBegin](#ongesturejudgebegin)的event参数来传递。 148 149**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 150 151| 名称 | 类型 | 描述 | 152| ------------ | ---------------------------------------- | -----------| 153| angle | number | 表示滑动手势的角度，即两根手指间的线段与水平方向的夹角变化的度数，单位为deg。<br/>**说明：**<br/>角度计算方式：滑动手势被识别到后，连接两根手指之间的线被识别为起始线条，随着手指的滑动，手指之间的线条会发生旋转，根据起始线条两端点和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角，最后arctan2(cy2-cy1,cx2-cx1)-arctan2(y2-y1,x2-x1)为旋转的角度。以起始线条为坐标系，顺时针旋转为0到180度，逆时针旋转为-180到0度。| 154| speed | number | 滑动手势速度，即所有手指相对当前组件元素原始区域滑动的平均速度，单位为vp/s。 | 155## 示例 156 157### 示例1 158```ts 159// xxx.ets 160@Entry 161@Component 162struct Index { 163 @State message: string = ''; 164 165 build() { 166 Column() { 167 Row({ space: 20 }) { 168 Text(this.message).width(200).height(80).backgroundColor(Color.Pink) 169 .fontSize(25) 170 }.margin(20) 171 } 172 .width('100%') 173 .height(200) 174 .borderWidth(2) 175 .onDragStart(() => { 176 this.message = 'drag' 177 console.log("Drag start.") 178 }) 179 .gesture( 180 TapGesture() 181 .tag("tap1")// 设置点击手势标志 182 .onAction(() => { 183 this.message = 'tap1' 184 }) 185 ) 186 .gesture( 187 LongPressGesture() 188 .tag("longPress1")// 设置长按手势标志 189 .onAction(() => { 190 this.message = 'longPress' 191 }) 192 ) 193 .gesture( 194 SwipeGesture() 195 .tag("swipe1")// 设置滑动手势标志 196 .onAction(() => { 197 this.message = 'swipe1' 198 }) 199 ) 200 .gesture( 201 PanGesture() 202 .tag("pan1")// 设置拖动手势标志 203 .onActionStart(() => { 204 this.message = 'pan1' 205 }) 206 ) 207 .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => { 208 // 若该手势类型为长按手势，转换为长按手势事件 209 if (gestureInfo.type == GestureControl.GestureType.LONG_PRESS_GESTURE) { 210 let longPressEvent = event as LongPressGestureEvent; 211 console.log("repeat " + longPressEvent.repeat) 212 } 213 // 若该手势类型为滑动手势，转换为滑动手势事件 214 if (gestureInfo.type == GestureControl.GestureType.SWIPE_GESTURE) { 215 let swipeEvent = event as SwipeGestureEvent; 216 console.log("angle " + swipeEvent.angle) 217 } 218 // 若该手势类型为拖动手势，转换为拖动手势事件 219 if (gestureInfo.type == GestureControl.GestureType.PAN_GESTURE) { 220 let panEvent = event as PanGestureEvent; 221 console.log("velocity " + panEvent.velocity) 222 } 223 // 自定义判定标准 224 if (gestureInfo.type == GestureControl.GestureType.DRAG) { 225 // 返回 REJECT 会使拖动手势失败 226 return GestureJudgeResult.REJECT; 227 } else if (gestureInfo.tag == 'longPress1' && event.fingerList.length > 0 && event.fingerList[0].localY < 100) { 228 // 返回 CONTINUE 将保持系统判定。 229 return GestureJudgeResult.CONTINUE; 230 } 231 return GestureJudgeResult.CONTINUE; 232 }) 233 } 234} 235``` 236 237### 示例2 238```ts 239// xxx.ets 240import { promptAction } from '@kit.ArkUI'; 241 242@Entry 243@Component 244struct Index { 245 scroller: Scroller = new Scroller() 246 247 build() { 248 Scroll(this.scroller) { 249 Column({ space: 8 }) { 250 Text("Drag 上下两层 上层绑定长按，下层绑定拖拽。先长按后平移上半区红色区域只会响应长按，先长按后平移下半区蓝色区域只会响应拖拽").width('100%').fontSize(20).fontColor('0xffdd00') 251 .backgroundColor(0xeeddaa00) 252 Stack({ alignContent: Alignment.Center }) { 253 Column() { 254 // 模拟上半区和下半区 255 Stack().width('200vp').height('100vp').backgroundColor(Color.Red) 256 Stack().width('200vp').height('100vp').backgroundColor(Color.Blue) 257 }.width('200vp').height('200vp') 258 // Stack的下半区是绑定了拖动手势的图像区域。 259 Image($r('sys.media.ohos_app_icon')) 260 .draggable(true) 261 .onDragStart(()=>{ 262 promptAction.showToast({ message: "Drag 下半区蓝色区域，Image响应" }) 263 }) 264 .width('200vp').height('200vp') 265 // Stack的上半区是绑定了长按手势的浮动区域。 266 Stack() { 267 } 268 .width('200vp') 269 .height('200vp') 270 .hitTestBehavior(HitTestMode.Transparent) 271 .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => { 272 // 确定tag标志是否有值 273 if (gestureInfo.tag) { 274 console.log("gestureInfo tag" + gestureInfo.tag.toString()) 275 } 276 console.log("gestureInfo Type " + gestureInfo.type.toString() + " isSystemGesture " + gestureInfo.isSystemGesture); 277 console.log("pressure " + event.pressure + " fingerList.length " + event.fingerList.length 278 + " timeStamp " + event.timestamp + " sourceType " + event.source.toString() + " titleX " + event.tiltX + " titleY " + event.tiltY + " sourcePool " + event.sourceTool.toString()); 279 // 如果是长按类型手势，判断点击的位置是否在上半区 280 if (gestureInfo.type == GestureControl.GestureType.LONG_PRESS_GESTURE) { 281 if (event.fingerList.length > 0 && event.fingerList[0].localY < 100) { 282 return GestureJudgeResult.CONTINUE 283 } else { 284 return GestureJudgeResult.REJECT 285 } 286 } 287 return GestureJudgeResult.CONTINUE 288 }) 289 .gesture(GestureGroup(GestureMode.Parallel, 290 LongPressGesture() 291 .onAction((event: GestureEvent) => { 292 promptAction.showToast({ message: "LongPressGesture 长按上半区 红色区域，红色区域响应" }) 293 }) 294 .tag("tap111") 295 )) 296 297 }.width('100%') 298 }.width('100%') 299 } 300 } 301} 302``` 303
