1# 手势拦截 2 3手势拦截主要用于确保手势按需执行，有效解决手势冲突问题。典型应用场景包括：嵌套滚动、通过过滤组件响应手势的范围来优化交互体验。手势拦截主要采用[手势触发控制](#手势触发控制)和[手势响应控制](#手势响应控制)两种方式实现。 4 5## 手势触发控制 6 7手势触发控制是指，在系统判定阈值已满足的条件下，应用可自行判断是否应拦截手势，使手势操作失败。 8 9**图1** 手势触发控制流程图 10 11 12 13手势触发控制涉及以下接口。 14 15| **接口** | **说明** | 16| ------- | -------------- | 17|[onGestureJudgeBegin](../reference/apis-arkui/arkui-ts/ts-gesture-customize-judge.md#ongesturejudgebegin)|用于手势拦截，是通用事件。在手势满足系统触发阈值场景下，回调给应用判断是否拦截手势。| 18|[onGestureRecognizerJudgeBegin](../reference/apis-arkui/arkui-ts/ts-gesture-blocking-enhancement.md#ongesturerecognizerjudgebegin)|用于手势拦截、获取手势识别器和初始化手势识别器开闭状态。是onGestureJudgeBegin接口的能力扩展，可以代替onGestureJudgeBegin接口。<br>获取手势识别器时，会获取一次交互中手势响应链上的所有手势识别器，以及当前即将触发的手势识别器，初始化手势的激活状态。| 19 20以下示例中，Image和Stack两个组件位于同一区域。长按Stack组件的上半部分可触发挂载在Stack组件上的长按手势，长按Stack组件的下半部分则会响应Image组件的拖拽操作。 21 22**图2** 示例图 23 24 25 261. Image组件设置拖拽。 27 28 ```ts 29 Image($r('sys.media.ohos_app_icon')) 30 .draggable(true) 31 .onDragStart(()=>{ 32 promptAction.showToast({ message: "Drag 下半区蓝色区域，Image响应" }); 33 }) 34 .width('200vp').height('200vp') 35 ``` 36 372. Stack组件设置手势。 38 39 ```ts 40 Stack() {} 41 .width('200vp') 42 .height('200vp') 43 .hitTestBehavior(HitTestMode.Transparent) 44 .gesture(GestureGroup(GestureMode.Parallel, 45 LongPressGesture() 46 .onAction((event: GestureEvent) => { 47 promptAction.showToast({ message: "LongPressGesture 长按上半区 红色区域，红色区域响应" }); 48 }) 49 .tag("longpress") 50 )) 51 ``` 52 533. Stack组件设置拦截。 54 55 ```ts 56 .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => { 57 // 如果是长按类型手势，判断点击的位置是否在上半区 58 if (gestureInfo.type == GestureControl.GestureType.LONG_PRESS_GESTURE) { 59 if (event.fingerList.length > 0 && event.fingerList[0].localY < 100) { 60 return GestureJudgeResult.CONTINUE; 61 } else { 62 return GestureJudgeResult.REJECT; 63 } 64 } 65 return GestureJudgeResult.CONTINUE; 66 }) 67 ``` 68 694. 代码完整示例。 70 71 ```ts 72 import { promptAction } from '@kit.ArkUI'; 73 74 @Entry 75 @Component 76 struct Index { 77 scroller: Scroller = new Scroller(); 78 79 build() { 80 Scroll(this.scroller) { 81 Column({ space: 8 }) { 82 Text("包括上下两层组件，上层组件绑定长按手势，下层组件绑定拖拽。其中上层组件下半区域绑定手势拦截，使该区域响应下层拖拽手势。").width('100%').fontSize(20).fontColor('0xffdd00') 83 Stack({ alignContent: Alignment.Center }) { 84 Column() { 85 // 模拟上半区和下半区 86 Stack().width('200vp').height('100vp').backgroundColor(Color.Red) 87 Stack().width('200vp').height('100vp').backgroundColor(Color.Blue) 88 }.width('200vp').height('200vp') 89 // Stack的下半区是绑定了拖动手势的图像区域。 90 Image($r('sys.media.ohos_app_icon')) 91 .draggable(true) 92 .onDragStart(()=>{ 93 promptAction.showToast({ message: "Drag 下半区蓝色区域，Image响应" }); 94 }) 95 .width('200vp').height('200vp') 96 // Stack的上半区是绑定了长按手势的浮动区域。 97 Stack() { 98 } 99 .width('200vp') 100 .height('200vp') 101 .hitTestBehavior(HitTestMode.Transparent) 102 .gesture(GestureGroup(GestureMode.Parallel, 103 LongPressGesture() 104 .onAction((event: GestureEvent) => { 105 promptAction.showToast({ message: "LongPressGesture 长按上半区 红色区域，红色区域响应" }); 106 }) 107 .tag("longpress") 108 )) 109 .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => { 110 // 如果是长按类型手势，判断点击的位置是否在上半区 111 if (gestureInfo.type == GestureControl.GestureType.LONG_PRESS_GESTURE) { 112 if (event.fingerList.length > 0 && event.fingerList[0].localY < 100) { 113 return GestureJudgeResult.CONTINUE; 114 } else { 115 return GestureJudgeResult.REJECT; 116 } 117 } 118 return GestureJudgeResult.CONTINUE; 119 }) 120 }.width('100%') 121 }.width('100%') 122 } 123 } 124 } 125 ``` 126 127## 手势响应控制 128 129手势响应控制，指的是手势已经成功识别，但是开发者仍然可以通过调用API接口控制手势回调是否能够响应。 130 131**图3** 手势响应控制流程图 132 133 134手势响应控制的前提是手势识别成功，如果手势不成功也不会产生手势回调响应。 135 1361. 业务手势作业流：指真正触发UI变化的业务手势，比如使页面滚动的PanGesture，触发点击的TapGesture等。 137 1382. 监听手势作业流：指在监听手势运行的过程中，应根据上下文的业务状态变化动态控制手势识别器的启停，例如在组件于嵌套滚动过程中是否已滑至边缘。这一监听事件可借助一个使用[并行手势绑定方式](arkts-gesture-events-binding.md#parallelgesture并行手势绑定方法)的PanGesture实现，或者采用Touch事件来完成。 139 1403. 设置手势并行：此步骤并非必需，典型场景是在嵌套滚动中，设置外部组件的滚动手势与内部的滚动手势并行。 141 1424. 动态开闭手势：指通过手势识别器的setEnable方法，控制手势是否响应用户回调。 143 144手势响应控制涉及以下接口。 145 146| **接口** | **说明** | 147| ------- | -------------- | 148|[shouldBuiltInRecognizerParallelWith](../reference/apis-arkui/arkui-ts/ts-gesture-blocking-enhancement.md#shouldbuiltinrecognizerparallelwith)|用于设置系统原生组件内置手势与其他手势并行。| 149|[onGestureRecognizerJudgeBegin](../reference/apis-arkui/arkui-ts/ts-gesture-blocking-enhancement.md#ongesturerecognizerjudgebegin)|用于手势拦截，获取手势识别器，初始化手势识别器开闭状态。| 150|[parallelGesture](arkts-gesture-events-binding.md#parallelgesture并行手势绑定方法)|可使开发者定义的手势，与比他优先级高的手势并行。| 151 152以下示例是两个Scroll组件的嵌套滚动场景，使用手势控制的api去控制外部组件和内部组件的嵌套滚动联动。 153 1541. 使用shouldBuiltInRecognizerParallelWith接口设置外部Scroll组件的PanGesture手势，与内部Scroll组件的PanGesture手势并行。 155 156 ```ts 157 .shouldBuiltInRecognizerParallelWith((current: GestureRecognizer, others: Array<GestureRecognizer>) => { 158 for (let i = 0; i < others.length; i++) { 159 let target = others[i].getEventTargetInfo(); 160 if (target.getId() == "inner" && others[i].isBuiltIn() && others[i].getType() == GestureControl.GestureType.PAN_GESTURE) { // 找到将要组成并行手势的识别器 161 this.currentRecognizer = current; // 保存当前组件的识别器 162 this.childRecognizer = others[i]; // 保存将要组成并行手势的识别器 163 return others[i]; // 返回和当前手势将要组成并行手势的识别器 164 } 165 } 166 return undefined; 167 }) 168 ``` 169 1702. 使用onGestureRecognizerJudgeBegin接口获取到Scroll组件的PanGesture手势识别器，同时根据内外Scroll组件的边界条件，初始化内外手势的开闭状态。 171 172 ```ts 173 .onGestureRecognizerJudgeBegin((event: BaseGestureEvent, current: GestureRecognizer, others: Array<GestureRecognizer>) => { // 在识别器即将要成功时，根据当前组件状态，设置识别器使能状态 174 let target = current.getEventTargetInfo(); 175 if (target.getId() == "outer" && current.isBuiltIn() && current.getType() == GestureControl.GestureType.PAN_GESTURE) { 176 for (let i = 0; i < others.length; i++) { 177 let target = others[i].getEventTargetInfo() as ScrollableTargetInfo; 178 if (target instanceof ScrollableTargetInfo && target.getId() == "inner") { // 找到响应链上对应并行的识别器 179 let panEvent = event as PanGestureEvent; 180 this.childRecognizer.setEnabled(true); 181 this.currentRecognizer.setEnabled(false); 182 if (target.isEnd()) { // 根据当前组件状态以及移动方向动态控制识别器使能状态 183 if (panEvent && panEvent.offsetY < 0) { 184 this.childRecognizer.setEnabled(false); 185 this.currentRecognizer.setEnabled(true); 186 } 187 } else if (target.isBegin()) { 188 if (panEvent.offsetY > 0) { 189 this.childRecognizer.setEnabled(false); 190 this.currentRecognizer.setEnabled(true); 191 } 192 } 193 } 194 } 195 } 196 return GestureJudgeResult.CONTINUE; 197 }) 198 ``` 199 2003. 设置监听手势，监听Scroll组件状态，动态调整手势开闭状态，以使手势响应。 201 202 ```ts 203 .parallelGesture( // 绑定一个Pan手势作为动态控制器 204 PanGesture() 205 .onActionUpdate((event: GestureEvent)=>{ 206 if (this.childRecognizer.getState() != GestureRecognizerState.SUCCESSFUL || this.currentRecognizer.getState() != GestureRecognizerState.SUCCESSFUL) { // 如果识别器状态不是SUCCESSFUL，则不做控制 207 return; 208 } 209 let target = this.childRecognizer.getEventTargetInfo() as ScrollableTargetInfo; 210 let currentTarget = this.currentRecognizer.getEventTargetInfo() as ScrollableTargetInfo; 211 if (target instanceof ScrollableTargetInfo && currentTarget instanceof ScrollableTargetInfo) { 212 this.childRecognizer.setEnabled(true); 213 this.currentRecognizer.setEnabled(false); 214 if (target.isEnd()) { // 在移动过程中实时根据当前组件状态，控制识别器的开闭状态 215 if ((event.offsetY - this.lastOffset) < 0) { 216 this.childRecognizer.setEnabled(false); 217 if (currentTarget.isEnd()) { 218 this.currentRecognizer.setEnabled(false); 219 } else { 220 this.currentRecognizer.setEnabled(true); 221 } 222 } 223 } else if (target.isBegin()) { 224 if ((event.offsetY - this.lastOffset) > 0) { 225 this.childRecognizer.setEnabled(false); 226 if (currentTarget.isBegin()) { 227 this.currentRecognizer.setEnabled(false); 228 } else { 229 this.currentRecognizer.setEnabled(true); 230 } 231 } 232 } 233 } 234 this.lastOffset = event.offsetY 235 }) 236 ) 237 ``` 238 2394. 代码完整示例。 240 241 ```ts 242 // xxx.ets 243 @Entry 244 @Component 245 struct FatherControlChild { 246 scroller: Scroller = new Scroller(); 247 scroller2: Scroller = new Scroller(); 248 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; 249 private childRecognizer: GestureRecognizer = new GestureRecognizer(); 250 private currentRecognizer: GestureRecognizer = new GestureRecognizer(); 251 private lastOffset: number = 0; 252 253 build() { 254 Stack({ alignContent: Alignment.TopStart }) { 255 Scroll(this.scroller) { // 外部滚动容器 256 Column() { 257 Text("Scroll Area") 258 .width('90%') 259 .height(150) 260 .backgroundColor(0xFFFFFF) 261 .borderRadius(15) 262 .fontSize(16) 263 .textAlign(TextAlign.Center) 264 .margin({ top: 10 }) 265 Scroll(this.scroller2) { // 内部滚动容器 266 Column() { 267 Text("Scroll Area2") 268 .width('90%') 269 .height(150) 270 .backgroundColor(0xFFFFFF) 271 .borderRadius(15) 272 .fontSize(16) 273 .textAlign(TextAlign.Center) 274 .margin({ top: 10 }) 275 Column() { 276 ForEach(this.arr, (item: number) => { 277 Text(item.toString()) 278 .width('90%') 279 .height(150) 280 .backgroundColor(0xFFFFFF) 281 .borderRadius(15) 282 .fontSize(16) 283 .textAlign(TextAlign.Center) 284 .margin({ top: 10 }) 285 }, (item: string) => item) 286 }.width('100%') 287 } 288 } 289 .id("inner") 290 .width('100%') 291 .height(800) 292 }.width('100%') 293 } 294 .id("outer") 295 .height(600) 296 .scrollable(ScrollDirection.Vertical) // 滚动方向纵向 297 .scrollBar(BarState.On) // 滚动条常驻显示 298 .scrollBarColor(Color.Gray) // 滚动条颜色 299 .scrollBarWidth(10) // 滚动条宽度 300 .edgeEffect(EdgeEffect.None) 301 .shouldBuiltInRecognizerParallelWith((current: GestureRecognizer, others: Array<GestureRecognizer>) => { 302 for (let i = 0; i < others.length; i++) { 303 let target = others[i].getEventTargetInfo(); 304 if (target.getId() == "inner" && others[i].isBuiltIn() && others[i].getType() == GestureControl.GestureType.PAN_GESTURE) { // 找到将要组成并行手势的识别器 305 this.currentRecognizer = current; // 保存当前组件的识别器 306 this.childRecognizer = others[i]; // 保存将要组成并行手势的识别器 307 return others[i]; // 返回和当前手势将要组成并行手势的识别器 308 } 309 } 310 return undefined; 311 }) 312 .onGestureRecognizerJudgeBegin((event: BaseGestureEvent, current: GestureRecognizer, others: Array<GestureRecognizer>) => { // 在识别器即将要成功时，根据当前组件状态，设置识别器使能状态 313 let target = current.getEventTargetInfo(); 314 if (target.getId() == "outer" && current.isBuiltIn() && current.getType() == GestureControl.GestureType.PAN_GESTURE) { 315 for (let i = 0; i < others.length; i++) { 316 let target = others[i].getEventTargetInfo() as ScrollableTargetInfo; 317 if (target instanceof ScrollableTargetInfo && target.getId() == "inner") { // 找到响应链上对应并行的识别器 318 let panEvent = event as PanGestureEvent; 319 this.childRecognizer.setEnabled(true); 320 this.currentRecognizer.setEnabled(false); 321 if (target.isEnd()) { // 根据当前组件状态以及移动方向动态控制识别器使能状态 322 if (panEvent && panEvent.offsetY < 0) { 323 this.childRecognizer.setEnabled(false); 324 this.currentRecognizer.setEnabled(true); 325 } 326 } else if (target.isBegin()) { 327 if (panEvent.offsetY > 0) { 328 this.childRecognizer.setEnabled(false); 329 this.currentRecognizer.setEnabled(true); 330 } 331 } 332 } 333 } 334 } 335 return GestureJudgeResult.CONTINUE; 336 }) 337 .parallelGesture( // 绑定一个Pan手势作为动态控制器 338 PanGesture() 339 .onActionUpdate((event: GestureEvent)=>{ 340 if (this.childRecognizer.getState() != GestureRecognizerState.SUCCESSFUL || this.currentRecognizer.getState() != GestureRecognizerState.SUCCESSFUL) { // 如果识别器状态不是SUCCESSFUL，则不做控制 341 return; 342 } 343 let target = this.childRecognizer.getEventTargetInfo() as ScrollableTargetInfo; 344 let currentTarget = this.currentRecognizer.getEventTargetInfo() as ScrollableTargetInfo; 345 if (target instanceof ScrollableTargetInfo && currentTarget instanceof ScrollableTargetInfo) { 346 this.childRecognizer.setEnabled(true); 347 this.currentRecognizer.setEnabled(false); 348 if (target.isEnd()) { // 在移动过程中实时根据当前组件状态，控制识别器的开闭状态 349 if ((event.offsetY - this.lastOffset) < 0) { 350 this.childRecognizer.setEnabled(false); 351 if (currentTarget.isEnd()) { 352 this.currentRecognizer.setEnabled(false); 353 } else { 354 this.currentRecognizer.setEnabled(true); 355 } 356 } 357 } else if (target.isBegin()) { 358 if ((event.offsetY - this.lastOffset) > 0) { 359 this.childRecognizer.setEnabled(false) 360 if (currentTarget.isBegin()) { 361 this.currentRecognizer.setEnabled(false); 362 } else { 363 this.currentRecognizer.setEnabled(true); 364 } 365 } 366 } 367 } 368 this.lastOffset = event.offsetY; 369 }) 370 ) 371 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 372 } 373 } 374 ```
