【鸿蒙开发实战篇】HarmonyOS 5.1手势事件详解

小灰尘 發表於 2025-9-11 22:52:00

【鸿蒙开发实战篇】HarmonyOS 5.1手势事件详解

大家好，我是 V 哥。 手势事件由绑定手势方法和绑定的手势组成，绑定的手势可以分为单一手势和组合手势两种类型，根据手势的复杂程度进行区分。本文跟着 V 哥一起来探讨手势事件处理。
想要考取鸿蒙认证的小伙伴，请加入V 哥班级获取辅导：
https://developer.huawei.com/consumer/cn/training/classDetail/042cb1cc4d7d44ecbdbd902fd1275dcc?type=1
V哥写的鸿蒙全系例图书，助你从入门到一名成熟的开发者： ![](https://files.mdnice.com/user/57732/ea8a430a-5ef1-4b41-9946-f90867c21963.png)
 ## 一、绑定手势方法 通过给各个组件绑定不同的手势事件，并设计事件的响应方式，当手势识别成功时，ArkUI框架将通过事件回调通知组件手势识别的结果。
1. gesture（常规手势绑定方法），gesture为通用的一种手势绑定方法，可以将手势绑定到对应的组件上，方法格式如下所示： ``` .gesture(gesture: GestureType, mask?: GestureMask) ``` 2. priorityGesture（带优先级的手势绑定方法），priorityGesture是带优先级的手势绑定方法，可以在组件上绑定优先识别的手势，方法格式如下所示： ``` .priorityGesture(gesture: GestureType, mask?: GestureMask) ``` 在默认情况下，当父组件和子组件使用gesture绑定同类型的手势时，子组件优先识别通过gesture绑定的手势。当父组件使用priorityGesture绑定与子组件同类型的手势时，父组件优先识别通过priorityGesture绑定的手势。长按手势时，设置触发长按的最短时间小的组件会优先响应，会忽略priorityGesture设置。比如当父组件Column和子组件Text同时绑定TapGesture手势时，父组件以带优先级手势priorityGesture的形式进行绑定时，优先响应父组件绑定的TapGesture。示例代码如下所示：
**Demo0701.ets 示例** ```typescript @Entry @Component struct Demo0701 { build() { Column() { Text('绑定手势事件-演示').fontSize(35) // 通过gesture绑定TapGesture手势 .gesture( TapGesture() .onAction(() => { console.info('文本组件的手势-触发中'); })) }.width("100%").margin(10) // 设置为priorityGesture时 // 点击文本区域会忽略Text组件的TapGesture手势事件 // 优先响应父组件Column的TapGesture手势事件 .priorityGesture( TapGesture() .onAction(() => { console.info('容器的手势-触发中'); }), // 忽略内部，仅响应当前组件的手势事件 GestureMask.IgnoreInternal ) } } ``` 效果如下图所示：
![](https://files.mdnice.com/user/57732/81e74433-629e-46ca-bbe4-2ad5533459be.png)
 3. parallelGesture（并行手势绑定方法），是并行的手势绑定方法，可以在父子组件上绑定可以同时响应的相同手势。 ``` .parallelGesture(gesture: GestureType, mask?: GestureMask) ``` 在默认情况下，手势事件为非冒泡事件，当父子组件绑定相同的手势时，父子组件绑定的手势事件会发生竞争，最多只有一个组件的手势事件能够获得响应。而当父组件绑定了并行手势parallelGesture时，父子组件相同的手势事件都可以触发，实现类似冒泡效果。
## 二、单一手势 1. 点击手势（TapGesture），点击手势支持单次点击和多次点击，拥有两个可选参数：count：声明该点击手势识别的连续点击次数。默认值为1，若设置小于1的非法值会被转化为默认值。如果配置多次点击，上一次抬起和下一次按下的超时时间为300毫秒。fingers：用于声明触发点击的手指数量，最小值为1，最大值为10，默认值为1。当配置多指时，若第一根手指按下300毫秒内未有足够的手指数按下则手势识别失败。方法格式如下所示： ``` TapGesture(value?:{count?:number, fingers?:number}) ``` 2. 长按手势（LongPressGesture），长按手势用于触发长按手势事件，拥有三个可选参数：fingers：用于声明触发长按手势所需要的最少手指数量，最小值为1，最大值为10，默认值为1。repeat：用于声明是否连续触发事件回调，默认值为false。duration：用于声明触发长按所需的最短时间，单位为毫秒，默认值为500。方法格式如下所示： ``` LongPressGesture(value?:{fingers?:number, repeat?:boolean, duration?:number}) ``` 以在Text组件上绑定可以重复触发的长按手势为例，演示长按手势，代码如下所示：
**Demo0702.ets 示例** ```typescript @Entry @Component struct Demo0702 { //记录手势的触发次数 @State count: number = 0; build() { Column() { Text('长按手势-触发次数=' + this.count).fontSize(28) .gesture( // 绑定可以重复触发的LongPressGesture LongPressGesture({ repeat: true }) .onAction((event: GestureEvent | undefined) => { if (event) { // 如果是可重复的长按手势，则count值一直递增 if (event.repeat) { this.count++; console.log("长按手势，触发次数=",this.count) } } }) .onActionEnd(() => { // 当长按手势结束的时候将count重置为0 console.log("长按手势，触发结束！") }) ).width("90%") } .padding(10) .border({ width: 3 }) .width("100%") } } ```
3. 拖动手势（PanGesture），拖动手势用于触发拖动手势事件，滑动达到最小滑动距离（默认值为5vp）时拖动手势识别成功，拥有三个可选参数：fingers：用于声明触发拖动手势所需要的最少手指数量，最小值为1，最大值为10，默认值为1。direction：用于声明触发拖动的手势方向，此枚举值支持逻辑与（&）和逻辑或（|）运算。默认值为Pandirection.All。distance：用于声明触发拖动的最小拖动识别距离，单位为vp，默认值为5。方法格式如下所示： ``` PanGesture(value?:{ fingers?:number, direction?:PanDirection, distance?:number}) ``` 以在Text组件上绑定拖动手势为例，可以通过在拖动手势的回调函数中修改组件的布局位置信息来实现组件的拖动，实现代码如下所示：
**Demo0703.ets 示例** ```typescript @Entry @Component struct Demo0703 { // 记录当前x轴偏移量 @State offsetX: number = 0; // 记录当前y轴偏移量 @State offsetY: number = 0; // 记录上一次x轴偏移量 @State positionX: number = 0; // 记录上一次y轴偏移量 @State positionY: number = 0; build() { Column() { Text('拖动手势,坐标:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) .height(100).padding(10) .fontColor(Color.White).backgroundColor(Color.Red) .border({ width: 3 })// 在组件上绑定布局位置信息 .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) .gesture(// 绑定拖动手势 PanGesture() .onActionStart((event: GestureEvent | undefined) => { console.info('开始拖动手势'); })// 当触发拖动手势时，根据回调函数修改组件的布局位置信息 .onActionUpdate((event: GestureEvent | undefined) => { if (event) { // 当前位置累加当前事件记录的偏移量得到横轴总偏移量 this.offsetX = this.positionX + event.offsetX; // 当前位置累加当前事件记录的偏移量得到纵轴总偏移量 this.offsetY = this.positionY + event.offsetY; } }).onActionEnd(() => { // 当手势结束的时候记录当前偏移量 this.positionX = this.offsetX; // 当手势结束的时候记录当前偏移量 this.positionY = this.offsetY; }) ) }.width("100%") } } ``` 效果如下所示：
![](https://files.mdnice.com/user/57732/38420b64-ba58-42d9-9c98-b391b0fa754e.png)
大部分可滑动组件，如List、Grid、Scroll、Tab等组件是通过PanGesture实现滑动，在组件内部的子组件绑定拖动手势（PanGesture）或者滑动手势（SwipeGesture）会导致手势竞争。
当在子组件绑定PanGesture时，在子组件区域进行滑动仅触发子组件的PanGesture。如果需要父组件响应，需要通过修改手势绑定方法或者子组件向父组件传递消息进行实现，或者通过修改父子组件的PanGesture参数distance使得拖动更灵敏。当子组件绑定SwipeGesture时，由于PanGesture和SwipeGesture触发条件不同，需要修改PanGesture和SwipeGesture的参数以达到所需效果。不合理的阈值设置会导致滑动不跟手（响应时延慢）的问题。 4.捏合手势（PinchGesture），捏合手势用于触发捏合手势事件，拥有两个可选参数：fingers：用于声明触发捏合手势所需要的最少手指数量，最小值为2，最大值为5，默认值为2。distance：用于声明触发捏合手势的最小距离，单位为vp，默认值为5，方法格式如下所示： ``` PinchGesture(value?:{fingers?:number, distance?:number}) ``` 我们可以在Column组件上绑定三指捏合手势，可以通过在捏合手势的函数回调中获取缩放比例，实现对组件的缩小或放大，代码如下所示：
**Demo0704.ets 示例** ``` @Entry @Component struct Index {  @State scaleValue: number = 1;  @State pinchValue: number = 1;  @State pinchX: number = 0;  @State pinchY: number = 0;  build() {      Column() {          Column() {          Text('PinchGesture scale:\n' + this.scaleValue)            Text('PinchGesture center:\n(' + this.pinchX + ',' + this.pinchY + ')')      }      .height(200)        .width(300)          .border({ width: 3 })        .margin({ top: 100 })          // 在组件上绑定缩放比例，可以通过修改缩放比例来实现组件的缩小或者放大      .scale({ x: this.scaleValue, y: this.scaleValue, z: 1 })          .gesture(              // 在组件上绑定三指触发的捏合手势            PinchGesture({ fingers: 3 })              .onActionStart((event: GestureEvent|undefined) => {            console.info('Pinch start');            })                // 当捏合手势触发时，可以通过回调函数获取缩放比例，从而修改组件的缩放比例          .onActionUpdate((event: GestureEvent|undefined) => {                if(event){                    this.scaleValue = this.pinchValue * event.scale;              this.pinchX = event.pinchCenterX;                this.pinchY = event.pinchCenterY;          }            })        .onActionEnd(() => {            this.pinchValue = this.scaleValue;                console.info('Pinch end');          })    )  } } } ``` 5. 旋转手势（RotationGesture）,旋转手势用于触发旋转手势事件，拥有两个可选参数：fingers：用于声明触发旋转手势所需要的最少手指数量，最小值为2，最大值为5，默认值为2。angle：用于声明触发旋转手势的最小改变度数，单位为deg，默认值为1。方法格式如下所示： ``` RotationGesture(value?:{fingers?:number, angle?:number}) ``` 我们可以在Text组件上绑定旋转手势实现组件的旋转为例，可以通过在旋转手势的回调函数中获取旋转角度，从而实现组件的旋转，代码示例如下图所示：
**Demo0705.ets 示例** ```typescript @Entry @Component struct Demo0705 { //记录组件需要旋转的角度 @State angle: number = 0; //记录旋转手势的角度值 @State rotateValue: number = 0; build() { Column() { Text('旋转手势演示-旋转角度-' + this.angle). fontSize(20).width("80%").margin(20). borderWidth(1).padding(10) // 在组件上绑定旋转布局，可以通过修改旋转角度来实现组件的旋转 .rotate({ angle: this.angle }) .gesture( RotationGesture() .onActionStart((event: GestureEvent|undefined) => { console.info('开始旋转'); }) // 当旋转手势生效时，通过旋转手势的回调函数获取旋转角度，从而修改组件的旋转角度 .onActionUpdate((event: GestureEvent|undefined) => { if(event){ this.angle = this.rotateValue + event.angle; } console.info('结束旋转'); }) // 当旋转结束抬手时，固定组件在旋转结束时的角度 .onActionEnd(() => { this.rotateValue = this.angle; console.info('获取旋转角度'); }) .onActionCancel(() => { console.info('旋转取消'); }) ) }.width("100%") } } ``` 效果如下图所示：
![](https://files.mdnice.com/user/57732/891d5390-c6a4-4249-81c9-23f874d4e21d.png)
 6. 滑动手势（SwipeGesture），滑动手势用于触发滑动事件，当滑动速度大于100vp/s时可以识别成功，拥有三个可选参数：fingers：用于声明触发滑动手势所需要的最少手指数量，最小值为1，最大值为10，默认值为1。direction：用于声明触发滑动手势的方向，此枚举值支持逻辑与（&）和逻辑或（|）运算。默认值为SwipeDirection.All。speed：用于声明触发滑动的最小滑动识别速度，单位为vp/s，默认值为100。方法格式如下所示：
``` SwipeGesture(value?:{fingers?:number, direction?:SwipeDirection, speed?:number}) ``` 我们可以在Column组件上绑定滑动手势实现组件的旋转为例，代码如下所示：
**Demo0706.ets 示例** ```typescript @Entry @Component struct Demo0706 { //记录旋转角度 @State rotateAngle: number = 0; // 记录滑动速度 @State speed: number = 1; build() { Column() { Column() { Text("滑动手势的速度：" + this.speed) Text("滑动手势的角度：" + this.rotateAngle) } .border({ width: 3 }) .width("70%").padding(10).margin(20) // 在Column组件上绑定旋转，通过滑动手势的滑动速度和角度修改旋转的角度 .rotate({ angle: this.rotateAngle }) .gesture( // 绑定滑动手势且限制仅在竖直方向滑动时触发 SwipeGesture({ direction: SwipeDirection.Vertical }) // 当滑动手势触发时，获取滑动的速度和角度，实现对组件的布局参数的修改 .onAction((event: GestureEvent|undefined) => { if(event){ this.speed = event.speed; this.rotateAngle = event.angle; } }) ) }.width("100%") } } ``` 效果如下所示：
![](https://files.mdnice.com/user/57732/6d001511-3ea0-4bdf-98b7-61032c52b477.png)
当SwipeGesture和PanGesture同时绑定时，若二者是以默认方式或者互斥方式进行绑定时，会发生竞争。SwipeGesture的触发条件为滑动速度达到100vp/s，PanGesture的触发条件为滑动距离达到5vp，先达到触发条件的手势触发。可以通过修改SwipeGesture和PanGesture的参数以达到不同的效果。
## 三、组合手势 组合手势由多种单一手势组合而成，通过在GestureGroup中使用不同的GestureMode来声明该组合手势的类型。方法主要包括2个参数分别为：mode：为GestureMode枚举类。用于声明该组合手势的类型，取值顺序识别、并行识别和互斥识别三种类型。gesture：由多个手势组合而成的数组。用于声明组合成该组合手势的各个手势。方法具体格式如下所示： ``` GestureGroup(mode:GestureMode, gesture:GestureType[]) ``` 1. 顺序识别
顺序识别组合手势对应的GestureMode为Sequence。顺序识别组合手势将按照手势的注册顺序识别手势，直到所有的手势识别成功。当顺序识别组合手势中有一个手势识别失败时，后续手势识别均失败。顺序识别手势组仅有最后一个手势可以响应onActionEnd。 以一个由长按手势和拖动手势组合而成的连续手势为例，在一个Column组件上绑定了translate属性，通过修改该属性可以设置组件的位置移动。然后在该组件上绑定LongPressGesture和PanGesture组合而成的Sequence组合手势。当触发LongPressGesture时，更新显示的数字。当长按后进行拖动时，根据拖动手势的回调函数，实现组件的拖动。实现代码示例如下所示：
**Demo0707.ets 示例** ```typescript @Entry @Component struct Demo0707 { //x坐标偏移量 @State offsetX: number = 0; //y坐标偏移量 @State offsetY: number = 0; //次数 @State count: number = 0; //当前点的x坐标 @State positionX: number = 0; //当前点的y坐标 @State positionY: number = 0; //边框样式 @State borderStyles: BorderStyle = BorderStyle.Dotted
build() { Column() { Text('顺序手势识别\n' + '长按行为:' + this.count + '\n拖拽手势:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY).fontSize(20).width("80%") .margin(10).padding(10).borderWidth(2) } // 绑定translate属性可以实现组件的位置移动 .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) .width("100%") //以下组合手势为顺序识别，当长按手势事件未正常触发时不会触发拖动手势事件 .gesture( // 声明该组合手势的类型为Sequence类型 GestureGroup(GestureMode.Sequence, // 该组合手势第一个触发的手势为长按手势，且长按手势可多次响应   LongPressGesture({ repeat: true }) // 当长按手势识别成功，增加Text组件上显示的count次数   .onAction((event: GestureEvent|undefined) => { if(event){ if (event.repeat) { this.count++; } } console.info('长按手势开始'); }) .onActionEnd(() => { console.info('长按手势结束'); }), // 当长按之后进行拖动，PanGesture手势被触发 PanGesture() .onActionStart(() => { this.borderStyles = BorderStyle.Dashed; console.info('开始拖动'); }) //当该手势被触发时根据回调获得拖动的距离修改该组件的位移距离从而实现组件的移动         .onActionUpdate((event: GestureEvent|undefined) => { if(event){ this.offsetX = (this.positionX + event.offsetX); this.offsetY = this.positionY + event.offsetY; } console.info('拖动已更新'); }) .onActionEnd(() => { this.positionX = this.offsetX; this.positionY = this.offsetY; this.borderStyles = BorderStyle.Solid; }) ).onCancel(() => { console.log("顺序手势取消") }) ) } } ``` 效果如下图所示：
![](https://files.mdnice.com/user/57732/4e3df965-da73-47d4-834d-4c2b4563d64d.png)
 
拖拽事件是一种典型的顺序识别组合手势事件，由长按手势事件和滑动手势事件组合而成。只有先长按达到长按手势事件预设置的时间后进行滑动才会触发拖拽事件。如果长按事件未达到或者长按后未进行滑动，拖拽事件均识别失败。
2. 并行识别 并行识别组合手势对应的GestureMode为Parallel。并行识别组合手势中注册的手势将同时进行识别，直到所有手势识别结束。并行识别手势组合中的手势进行识别时互不影响。 以在一个Column组件上绑定点击手势和双击手势组成的并行识别手势为例，由于单击手势和双击手势是并行识别，因此两个手势可以同时进行识别，二者互不干涉。实现代码如下所示：
**Demo0708.ets 示例** ```typescript @Entry @Component struct Demo0708 { //单击手势次数 @State count1: number = 0; //双击手势次数 @State count2: number = 0; build() { Column() { Text('并行识别手势\n' + '单击手势次数:' + this.count1 + '\n双击手势次数:' + this.count2 ) .fontSize(20).padding(10).width("90%").borderWidth(2) }.width('100%') // 以下组合手势为并行并别，单击手势识别成功后 // 若在规定时间内再次点击，双击手势也会识别成功 .gesture( GestureGroup(GestureMode.Parallel, TapGesture({ count: 1 }).onAction(() => {this.count1++;}), TapGesture({ count: 2 }).onAction(() => {this.count2++;}) ) ) } } ``` 效果如下图所示：
![](https://files.mdnice.com/user/57732/e3f84eae-516a-4965-9185-0513dab323b6.png)
![](https://files.mdnice.com/user/57732/8189ca32-5145-49a0-a1ab-32b658dd51de.png)
 当由单击手势和双击手势组成一个并行识别组合手势后，在区域内进行点击时，单击手势和双击手势将同时进行识别。当只有单次点击时，单击手势识别成功，双击手势识别失败。
当有两次点击时，若两次点击相距时间在规定时间内（默认规定时间为300毫秒），触发两次单击事件和一次双击事件。当有两次点击时，若两次点击相距时间超出规定时间，触发两次单击事件不触发双击事件。
3. 互斥识别
互斥识别组合手势对应的GestureMode为Exclusive。互斥识别组合手势中注册的手势将同时进行识别，若有一个手势识别成功，则结束手势识别，其他所有手势识别失败。
以在一个Column组件上绑定单击手势和双击手势组合而成的互斥识别组合手势为例。若先绑定单击手势后绑定双击手势，由于单击手势只需要一次点击即可触发而双击手势需要两次，每次的点击事件均被单击手势消费而不能积累成双击手势，所以双击手势无法触发。若先绑定双击手势后绑定单击手势，则触发双击手势不触发单击手势。代码实现如下所示：
**Demo0709.ets示例** ```typescript @Entry @Component struct Index { //记录单击手势的次数 @State count1: number = 0; //记录双击手势的次数 @State count2: number = 0; build() { Column() { Text('互斥识别手势\n' + '单击手势识别次数:' + this.count1 + '\n双击手势识别次数:' + this.count2 + '\n') .fontSize(20).borderWidth(2).padding(10).width("90%") } .width('100%') //组合手势为互斥并别，单击手势识别成功后，双击手势会识别失败 .gesture( GestureGroup( GestureMode.Exclusive, TapGesture({ count: 1 }).onAction(() => { this.count1++;}), TapGesture({ count: 2 }).onAction(() => { this.count2++;}) ) ) } } ``` 效果如下图所示：
![](https://files.mdnice.com/user/57732/b4bd5529-a693-48ca-b490-8cbc66d2ce5b.png)
![](https://files.mdnice.com/user/57732/8ccbe7e4-bde3-4e29-a566-6a97fa3e38a9.png)
 当由单击手势和双击手势组成一个互斥识别组合手势后，在区域内进行点击时，单击手势和双击手势将同时进行识别。当只有单次点击时，单击手势识别成功，双击手势识别失败。
当有两次点击时，手势响应取决于绑定手势的顺序。若先绑定单击手势后绑定双击手势，单击手势在第一次点击时即宣告识别成功，此时双击手势已经失败。即使在规定时间内进行了第二次点击，双击手势事件也不会进行响应，此时会触发单击手势事件的第二次识别成功。若先绑定双击手势后绑定单击手势，则会响应双击手势不响应单击手势。
## 四、多层级手势事件 多层级手势事件指父子组件嵌套时，父子组件均绑定了手势或事件。在该场景下，手势或者事件的响应受到多个因素的影响，相互之间发生传递和竞争，容易出现预期外的响应。
1. 触摸事件
触摸事件（onTouch事件）是所有手势组成的基础，有Down，Move，Up，Cancel四种。手势均由触摸事件组成，例如，点击为Down+Up，滑动为Down+一系列Move+Up。触摸事件具有最特殊性： - 监听了onTouch事件的组件。若在手指落下时被触摸则均会收到onTouch事件的回调，被触摸受到触摸热区和触摸控制影响。 - onTouch事件的回调是闭环的。若一个组件收到了手指Id为0的Down事件，后续也会收到手指Id为0的Move事件和Up事件。 - onTouch事件的回调是一致的。若一个组件收到了手指Id为0的Down事件未收到手指Id为1的Down事件，则后续只会收到手指Id为0的touch事件，不会收到手指Id为1的后续touch事件。 对于一般的容器组件（例如：Column），父子组件之间onTouch事件能够同时触发，兄弟组件之间onTouch事件根据布局进行触发。 ``` ComponentA() {    ComponentB().onTouch(() => {})    ComponentC().onTouch(() => {}) }.onTouch(() => {}) ``` 组件B和组件C作为组件A的子组件，当触摸到组件B或者组件C时，组件A也会被触摸到。onTouch事件允许多个组件同时触发。因此，当触摸组件B时，会触发组件A和组件B的onTouch回调，不会触发组件C的onTouch回调。
当触摸组件C时，会触发组件A和组件C的onTouch回调，不触发组件B的回调。特殊的容器组件，如Stack等组件，由于子组件之间存在着堆叠关系，子组件的布局也互相存在遮盖关系。所以，父子组件之间onTouch事件能够同时触发，兄弟组件之间onTouch事件会存在遮盖关系。
2. 手势与事件
除了触摸事件（onTouch事件）外的所有手势与事件，均是通过基础手势或者组合手势实现的。比如拖拽事件是由长按手势和滑动手势组成的一个顺序手势。在未显式声明的情况下，同一时间，一根手指对应的手势组中只会有一个手势获得成功从而触发所设置的回调。因此，除非显式声明允许多个手势同时成功，同一时间只会有一个手势响应。响应优先级遵循以下条件： - 当父子组件均绑定同一类手势时，子组件优先于父组件触发。 - 当一个组件绑定多个手势时，先达到手势触发条件的手势优先触发。 ``` ComponentA() {    ComponentB()  .gesture(TapGesture({count: 1})) }.gesture(TapGesture({count: 1}))     ``` 当父组件和子组件均绑定点击手势时，子组件的优先级高于父组件。因此，当在B组件上进行点击时，组件B所绑定的TapGesture的回调会被触发，而组件A所绑定的TapGesture的回调不会被触发。 ``` ComponentA().gesture(    GestureGroup(      GestureMode.Exclusive,      TapGesture({count: 1}),        PanGesture({distance: 5}) )) ``` 当组件A上绑定了由点击和滑动手势组成的互斥手势组时，先达到手势触发条件的手势触发对应的回调。若使用者做了一次点击操作，则响应点击对应的回调。若使用者进行了一次滑动操作并且滑动距离达到了阈值，则响应滑动对应的回调。
可以通过设置属性，控制默认的多层级手势事件竞争流程，更好的实现手势事件。目前，responseRegion属性和hitTestBehavior属性可以控制Touch事件的分发，从而可以影响到onTouch事件和手势的响应。而绑定手势方法属性可以控制手势的竞争从而影响手势的响应，但不能影响到onTouch事件。
3. responseRegion对手势和事件的控制
responseRegion属性可以实现组件的响应区域范围的变化。响应区域范围可以超出或者小于组件的布局范围。 ``` ComponentA() {    ComponentB()  .onTouch(() => {})  .gesture(TapGesture({count: 1}))    .responseRegion({Rect1, Rect2, Rect3})}.onTouch(() => {})  .gesture(TapGesture({count: 1}))  .responseRegion({Rect4}) ``` 当组件A绑定了.responseRegion({Rect4})的属性后，所有落在Rect4区域范围的触摸事件和手势可被组件A对应的回调响应。
当组件B绑定了.responseRegion({Rect1, Rect2, Rect3})的属性后，所有落在Rect1,Rect2和Rect3区域范围的触摸事件和手势可被组件B对应的回调响应。
当绑定了responseRegion后，手势与事件的响应区域范围将以所绑定的区域范围为准，而不是以布局区域为准，可能出现布局相关区域不响应手势与事件的情况。此外，responseRegion属性支持由多个Rect组成的数组作为入参，以支持更多开发需求。
4. hitTestBehavior对手势和事件的控制
hitTestBehavior属性可以实现在复杂的多层级场景下，一些组件能够响应手势和事件，而一些组件不能响应手势和事件。 ``` ComponentA() {    ComponentB()    .onTouch(() => {})  .gesture(TapGesture({count: 1}))      ComponentC() {          ComponentD()        .onTouch(() => {})        .gesture(TapGesture({count: 1}))    } .onTouch(() => {})    .gesture(TapGesture({count: 1}))    .hitTestBehavior(HitTestMode.Block)} .onTouch(() => {})  .gesture(TapGesture({count: 1})) ``` HitTestMode.Block自身会响应触摸测试，阻塞子节点和兄弟节点的触摸测试，从而导致子节点和兄弟节点的onTouch事件和手势均无法触发。
当组件C未设置hitTestBehavior时，点击组件D区域，组件A、组件C和组件D的onTouch事件会触发，组件D的点击手势会触发。
当组件C设置了hitTestBehavior为HitTestMode.Block时，点击组件D区域，组件A和组件C的onTouch事件会触发，组件D的onTouch事件未触发。同时，由于组件D的点击手势因为被阻塞而无法触发，组件C的点击手势会触发。 ``` Stack A() {    ComponentB()    .onTouch(() => {})  .gesture(TapGesture({count: 1}))      ComponentC()    .onTouch(() => {})    .gesture(TapGesture({count: 1}))      .hitTestBehavior(HitTestMode.Transparent) }.onTouch(() => {}) .gesture(TapGesture({count: 1})) ``` HitTestMode.Transparent自身响应触摸测试，不会阻塞兄弟节点的触摸测试。当组件C未设置hitTestBehavior时，点击组件B和组件C的重叠区域时，Stack A和组件C的onTouch事件会触发，组件C的点击事件会触发，组件B的onTouch事件和点击手势均不触发。
而当组件C设置hitTestBehavior为HitTestMode.Transparent时，点击组件B和组件C的重叠区域，组件A和组件C不受到影响与之前一致，组件A和组件C的onTouch事件会触发，组件C的点击手势会触发。而组件B因为组件C设置了HitTestMode.Transparent，组件B也收到了Touch事件，从而组件B的onTouch事件和点击手势触发。 ``` ComponentA() {    ComponentB()    .onTouch(() => {})    .gesture(TapGesture({count: 1})) }.onTouch(() => {}) .gesture(TapGesture({count: 1})) .hitTestBehavior(HitTestMode.None) ``` HitTestMode.None自身不响应触摸测试，不会阻塞子节点和兄弟节点的触摸控制。 当组件A未设置hitTestBehavior时，点击组件B区域时，组件A和组件B的onTouch事件均会触发，组件B的点击手势会触发。
当组件A设置hitTestBehavior为HitTestMode.None时，点击组件B区域时，组件B的onTouch事件触发，而组件A的onTouch事件无法触发，组件B的点击手势触发。 针对简单的场景，建议在单个组件上绑定hitTestBehavior。 针对复杂场景，建议在多个组件上绑定不同的hitTestBehavior来控制Touch事件的分发。
5. 绑定手势方法对手势的控制
设置绑定手势的方法可以实现在多层级场景下，当父组件与子组件绑定了相同的手势时，设置不同的绑定手势方法有不同的响应优先级。当父组件使用.gesture绑定手势，父子组件所绑定手势类型相同时，子组件优先于父组件响应。 ``` ComponentA() {    ComponentB()    .gesture(TapGesture({count: 1})) }.gesture(TapGesture({count: 1})) ``` 当父子组件均正常绑定点击手势时，子组件优先于父组件响应。此时，单击组件B区域范围，组件B的点击手势会触发，组件A的点击手势不会触发。如果以带优先级的方式绑定手势，则可使得父组件所绑定手势的响应优先级高于子组件。 ``` ComponentA() {  ComponentB()  .gesture(TapGesture({count: 1})) }.priorityGesture(TapGesture({count: 1})) ``` 当父组件以.priorityGesture的形式绑定手势时，父组件所绑定的手势优先级高于子组件。此时，单击组件B区域范围，组件A的点击手势会触发，组件B的点击手势不会触发。如果需要父子组件所绑定的手势不发生冲突，均可响应，则可以使用并行的方式在父组件绑定手势。 ``` ComponentA() {  ComponentB()    .gesture(TapGesture({count: 1})) }.parallelGesture(TapGesture({count: 1})) ``` 当父组件以.parallelGesture的形式绑定手势时，父组件和子组件所绑定的手势均可触发。此时，单击组件B区域范围，组件A和组件B的点击手势均会触发。
## 小结 本文详细介绍了Harmony OS中的交互事件处理机制，涵盖了触屏事件、键鼠事件、焦点事件和拖拽事件等多种类型。首先，对Harmony OS中的事件分类进行了详细阐述，包括触屏事件、键鼠事件、焦点事件和拖拽事件，并解释了事件分发机制和手势事件的构成。接着，深入探讨了事件分发的具体过程，包括触摸测试和事件响应链的收集，以及如何通过触摸测试控制和自定义事件拦截来优化事件处理。
在触屏事件部分，详细讲解了点击事件、触摸事件等的触发条件和回调函数的使用方法，并通过示例代码展示了如何在实际应用中实现这些事件的处理。键鼠事件部分则介绍了鼠标事件和键盘事件的分类及其触发机制，包括鼠标悬浮、点击等事件的处理方法，以及如何通过键盘事件实现快捷键功能。
焦点事件的介绍包括焦点的基本概念、焦点链的形成和走焦规范，以及如何通过监听获焦和失焦事件来实现焦点的动态管理。此外，还介绍了如何设置组件的可获焦属性和焦点样式，以及如何使用FocusController实现主动获焦和失焦。
拖拽事件部分则详细介绍了拖拽操作的基本概念、触发方式和回调事件的使用，包括手势拖拽和鼠标拖拽的不同实现方式，以及如何通过设置拖拽背板图和使用UDMF实现数据的传递。
最后，手势事件的讲解涵盖了单一手势和组合手势的分类及其绑定方法，包括点击手势、长按手势、拖动手势、捏合手势、旋转手势和滑动手势等的使用场景和实现方式，并通过示例代码展示了如何在实际应用中实现复杂的手势交互。
通过本文的学习，读者可以全面掌握Harmony OS中各种交互事件的处理方法，提升应用的交互体验和用户满意度。

</div>
<div id="MySignature" role="contentinfo">
本文来自博客园，作者：威哥爱编程，转载请注明原文链接：https://www.cnblogs.com/finally-vince/p/19086947 
来源：https://www.cnblogs.com/finally-vince/p/19086947

頁: [1]

琼殿技术论坛's Archiver

【鸿蒙开发实战篇】HarmonyOS 5.1手势事件详解