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> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 可以通过gesture、priorityGesture和parallelGesture给组件绑定手势识别，手势识别成功后可以通过事件回调通知组件。可以通过[触摸热区](ts-universal-attributes-touch-target.md)指定可识别手势的区域。gesture、priorityGesture和parallelGesture当前不支持使用三目运算符（条件? 表达式1 : 表达式2）切换手势绑定。 16 17## gesture 18 19gesture(gesture: GestureType, mask?: GestureMask): T 20 21绑定手势。 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------ | ------------------------------------------ | ---- | ---------------------------- | 31| gesture | [GestureType](./ts-gesture-common.md#gesturetype11-1) | 是 | 绑定的手势类型。 | 32| mask | [GestureMask](./ts-gesture-common.md#gesturemask11枚举说明) | 否 | 事件响应设置。<br/>默认值：GestureMask.Normal | 33 34**返回值：** 35 36| 类型 | 说明 | 37| ------ | --------- | 38| T | 返回当前组件。 | 39 40## priorityGesture 41 42priorityGesture(gesture: GestureType, mask?: GestureMask): T 43 44绑定优先识别手势。 45 461. 默认情况下，子组件优先识别通过gesture绑定的手势，当父组件配置priorityGesture时，父组件优先识别priorityGesture绑定的手势。 47 482. 绑定长按手势时，设置触发长按的最短时间小的组件会优先响应，会忽略priorityGesture设置。 49 50**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 51 52**系统能力：** SystemCapability.ArkUI.ArkUI.Full 53 54**参数：** 55 56| 参数名 | 类型 | 必填 | 说明 | 57| ------ | ------------------------------------------ | ---- | ---------------------------- | 58| gesture | [GestureType](./ts-gesture-common.md#gesturetype11-1) | 是 | 绑定的手势对象。 | 59| mask | [GestureMask](./ts-gesture-common.md#gesturemask11枚举说明) | 否 | 事件响应设置。<br/>默认值：GestureMask.Normal | 60 61**返回值：** 62 63| 类型 | 说明 | 64| ------ | --------- | 65| T | 返回当前组件。 | 66 67## parallelGesture 68 69parallelGesture(gesture: GestureType, mask?: GestureMask): T 70 71绑定可与子组件手势同时触发的手势。手势事件为非冒泡事件。父组件设置parallelGesture时，父子组件相同的手势事件都可以触发，实现类似冒泡效果。 72 73**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 74 75**系统能力：** SystemCapability.ArkUI.ArkUI.Full 76 77**参数：** 78 79| 参数名 | 类型 | 必填 | 说明 | 80| ------ | ------------------------------------------ | ---- | ---------------------------- | 81| gesture | [GestureType](./ts-gesture-common.md#gesturetype11-1) | 是 | 绑定的手势对象。 | 82| mask | [GestureMask](./ts-gesture-common.md#gesturemask11枚举说明) | 否 | 事件响应设置。<br/>默认值：GestureMask.Normal | 83 84**返回值：** 85 86| 类型 | 说明 | 87| ------ | --------- | 88| T | 返回当前组件。 | 89 90## SourceType枚举说明<sup>8+</sup> 91 92**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96| 名称 | 值 | 说明 | 97| ---- | --- | -------- | 98| Unknown | - | 未知设备。 | 99| Mouse | - | 鼠标。 | 100| TouchScreen | - | 触摸屏。 | 101 102## SourceTool枚举说明<sup>9+</sup> 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106| 名称 | 值 | 说明 | 107| -------- | - | --------- | 108| Unknown | - | 未知输入源。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 109| Finger | - | 手指输入。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 110| Pen | - | 手写笔输入。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 111| MOUSE<sup>12+</sup> | - | 鼠标输入。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 112| TOUCHPAD<sup>12+</sup> | - | 触控板输入。触控板单指输入被视为鼠标输入操作。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 113| JOYSTICK<sup>12+</sup> | - | 手柄输入。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 114 115## 示例 116 117### 示例1(父组件优先识别手势和父子组件同时触发手势) 118 119该示例通过配置priorityGesture和parallelGesture分别实现了父组件优先识别手势和父子组件同时触发手势。 120 121```ts 122// xxx.ets 123@Entry 124@Component 125struct GestureSettingsExample { 126 @State priorityTestValue: string = '' 127 @State parallelTestValue: string = '' 128 129 build() { 130 Column() { 131 Column() { 132 Text('TapGesture:' + this.priorityTestValue).fontSize(28) 133 .gesture( 134 TapGesture() 135 .onAction((event: GestureEvent) => { 136 this.priorityTestValue += '\nText' 137 })) 138 } 139 .height(200) 140 .width(250) 141 .padding(20) 142 .margin(20) 143 .border({ width: 3 }) 144 // 设置为priorityGesture时，点击文本会忽略Text组件的TapGesture手势事件，优先识别父组件Column的TapGesture手势事件 145 .priorityGesture( 146 TapGesture() 147 .onAction((event: GestureEvent) => { 148 this.priorityTestValue += '\nColumn' 149 }), GestureMask.IgnoreInternal) 150 151 Column() { 152 Text('TapGesture:' + this.parallelTestValue).fontSize(28) 153 .gesture( 154 TapGesture() 155 .onAction((event: GestureEvent) => { 156 this.parallelTestValue += '\nText' 157 })) 158 } 159 .height(200) 160 .width(250) 161 .padding(20) 162 .margin(20) 163 .border({ width: 3 }) 164 // 设置为parallelGesture时，点击文本会同时触发子组件Text与父组件Column的TapGesture手势事件 165 .parallelGesture( 166 TapGesture() 167 .onAction((event: GestureEvent) => { 168 this.parallelTestValue += '\nColumn' 169 }), GestureMask.Normal) 170 } 171 } 172} 173``` 174 175 176 177### 示例2（实时监测参与滑动手势的有效触点数量） 178 179该示例通过配置fingerInfos实时监测参与滑动手势的有效触点数量 180 181```ts 182// xxx.ets 183@Entry 184@Component 185 186struct PanGestureWithFingerCount { 187 @State offsetX: number = 0 188 @State offsetY: number = 0 189 @State positionX: number = 0 190 @State positionY: number = 0 191 @State fingerCount: number = 0 //用于记录参与手势的触点数量 192 193 private panOption: PanGestureOptions = new PanGestureOptions({ 194 direction: PanDirection.All, 195 fingers: 1 196 }) 197 198 build() { 199 Column() { 200 // 显示当前有效触点数量 201 Text(`触点数量: ${this.fingerCount}`) 202 .fontSize(20) 203 .margin(10) 204 205 Column() { 206 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 207 } 208 .height(200) 209 .width(300) 210 .padding(20) 211 .border({ width: 3 }) 212 .margin(50) 213 .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) 214 .gesture( 215 PanGesture(this.panOption) 216 .onActionStart((event: GestureEvent) => { 217 console.info('Pan start') 218 this.fingerCount = event.fingerInfos?.length || 0 // 记录触点数量 219 }) 220 .onActionUpdate((event: GestureEvent) => { 221 if (event) { 222 console.info('fingerInfos',JSON.stringify(event.fingerInfos)) 223 this.offsetX = this.positionX + event.offsetX 224 this.offsetY = this.positionY + event.offsetY 225 this.fingerCount = event.fingerInfos?.length || 0 // 更新触点数量,记录下参与当前手势的有效触点的数量 226 } 227 }) 228 .onActionEnd((event: GestureEvent) => { 229 this.positionX = this.offsetX 230 this.positionY = this.offsetY 231 this.fingerCount = 0 // 触点离开触摸区域后归零 232 console.info('Pan end') 233 }) 234 .onActionCancel(() => { 235 this.fingerCount = 0 // 手势取消后归零 236 }) 237 ) 238 239 Button('切换为双指滑动') 240 .onClick(() => { 241 this.panOption.setFingers(2) 242 }) 243 } 244 } 245} 246```
