harmony 鸿蒙自定义手势判定

  • 2025-06-12
  • 浏览 (4)

自定义手势判定

为组件提供自定义手势判定能力。开发者可根据需要，在手势识别期间，决定是否响应手势。

说明：

从API version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

onGestureJudgeBegin

onGestureJudgeBegin(callback: (gestureInfo: GestureInfo, event: BaseGestureEvent) => GestureJudgeResult): T

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数： |参数名 |参数类型 |必填|参数描述 | |———-|————————–|——-|—————————–| |callback |(gestureInfo: GestureInfo, event: BaseGestureEvent) => GestureJudgeResult|是 |给组件绑定自定义手势判定回调。当手势被接受时，触发用户定义的回调获取结果。|

返回值：

类型 说明
T 返回当前组件。

GestureJudgeResult11+

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 描述
CONTINUE 不影响系统手势判定流程。
REJECT 对于用户自定义的手势判定结果为失败。

GestureInfo对象说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 描述
tag string 手势标记。
说明：
未设置事件标识tag属性时，tag不返回或返回undefined。
type GestureControl.GestureType 手势类型。
说明：
当手势为未暴露类型的系统内置手势事件时，type的值为-1。
isSystemGesture boolean 判断当前手势是否为组件自带手势。true表示是，false表示否。
默认值：false

GestureType12+

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 值 描述
TAP_GESTURE 0 点击手势
LONG_PRESS_GESTURE 1 长按手势
PAN_GESTURE 2 拖动手势
PINCH_GESTURE 3 捏合手势
SWIPE_GESTURE 4 滑动手势
ROTATION_GESTURE 5 旋转手势
DRAG 6 拖拽
CLICK 7 点击

BaseEvent对象说明8+

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 描述
target EventTarget 触发手势事件的元素对象。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
timestamp number 事件时间戳，触发事件时距离系统启动的时间间隔。
单位：ns
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
source SourceType 事件输入设备的类型。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
pressure9+ number 按压的压力大小。
默认值：0
取值范围：[0,1]，典型值0.913168，压感大小与数值正相关。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
tiltX9+ number 手写笔在设备平面上的投影与设备平面X轴的夹角。
默认值：0
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
tiltY9+ number 手写笔在设备平面上的投影与设备平面Y轴的夹角。
默认值：0
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
rollAngle17+ number 手写笔与设备平面的夹角。
卡片能力： 从API version 17开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 17开始，该接口支持在原子化服务中使用。
sourceTool9+ SourceTool 事件输入源的类型。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。
axisHorizontal12+ number 水平轴值。
默认值：0
说明：
当前仅在由鼠标滚轮或者触控板双指滑动场景下触发的Pan手势中可以获取。
卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
axisVertical12+ number 垂直轴值。
默认值：0
说明：
当前仅在由鼠标滚轮或者触控板双指滑动场景下触发的Pan手势中可以获取。
卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
getModifierKeyState12+ (Array<string>) => bool 获取功能键按压状态。报错信息请参考以下错误码。支持功能键 ‘Ctrl’|‘Alt’|‘Shift’。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
deviceId12+ number 触发当前事件的输入设备ID。
默认值：0
取值范围：[0, +∞)
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
targetDisplayId15+ number 事件发生的屏幕ID。
默认值：0
取值范围：[0, +∞)
原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed.

BaseGestureEvent对象说明

继承于BaseEvent。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 必填 描述
fingerList11+ FingerInfo[] 是 触发事件的所有手指信息。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
fingerInfos20+ FingerInfo[] 否 参与触发事件的所有有效触点信息。默认值为空数组[]，返回空数组时，表示当前无有效触点信息。
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

TapGestureEvent对象说明

继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 必填 说明
tapLocation20+ EventLocationInfo 否 获取点击手势的坐标信息。
取值范围：[0, +∞)
原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

LongPressGestureEvent对象说明

继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 描述
repeat boolean 是否为重复触发事件。true表示为重复触发事件，false表示非重复触发事件。

PanGestureEvent对象说明

继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 描述
offsetX number 手势事件x轴相对当前组件元素原始区域的偏移量，单位为vp，从左向右滑动offsetX为正，反之为负。
offsetY number 手势事件y轴相对当前组件元素原始区域的偏移量，单位为vp，从上向下滑动offsetY为正，反之为负。
velocityX number 获取当前手势的x轴方向速度。坐标轴原点为屏幕左上角，分正负方向速度，从左往右为正，反之为负。单位为vp/s。
velocityY number 获取当前手势的y轴方向速度。坐标轴原点为屏幕左上角，分正负方向速度，从上往下为正，反之为负。单位为vp/s。
velocity number 获取当前的主方向速度。为xy轴方向速度的平方和的算术平方根。单位为vp/s。

PinchGestureEvent对象说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。 |名称 |类型 |描述 | |————|—————————————-|———–| |scale |number|缩放比例。| |pinchCenterX|number|捏合手势中心点相对于当前组件元素原始区域左上角x轴坐标，单位为vp。| |pinchCenterY|number|捏合手势中心点相对于当前组件元素原始区域左上角y轴坐标，单位为vp。|

RotationGestureEvent对象说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。 |名称 |类型 |描述 | |————|—————————————-|———–| |angle |number|表示旋转角度，单位为deg。
说明：
角度计算方式：当滑动手势被识别后，连接两根手指之间的线被识别为起始线条。随着手指的滑动，手指之间的线条会发生旋转。根据起始线条和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角。
最终的旋转角度为：arctan2(cy2-cy1, cx2-cx1) - arctan2(y2-y1, x2-x1)
在起始线条为坐标系的情况下，顺时针旋转为0到180度，逆时针旋转为-180到0度。|

SwipeGestureEvent对象说明

继承于BaseGestureEvent。可将该对象作为onGestureJudgeBegin的event参数来传递。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称 类型 描述
angle number 表示滑动手势的角度，即两根手指间的线段与水平方向的夹角变化的度数，单位为deg。
说明：
角度计算方式：当滑动手势被识别后，连接两根手指之间的线被识别为起始线条。随着手指的滑动，手指之间的线条会发生旋转。根据起始线条和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角。
最终的旋转角度为：arctan2(cy2-cy1, cx2-cx1) - arctan2(y2-y1, x2-x1)
在起始线条为坐标系的情况下，顺时针旋转为0到180度，逆时针旋转为-180到0度。
speed number 滑动手势速度，即所有手指相对当前组件元素原始区域滑动的平均速度，单位为vp/s。

示例

示例1（自定义手势判定）

该示例通过配置onGestureJudgeBegin实现了对长按、滑动和拖动手势的自定义判定。

// xxx.ets
@Entry
@Component
struct Index {
  @State message: string = '';

  build() {
    Column() {
      Row({ space: 20 }) {
        Text(this.message).width(200).height(80).backgroundColor(Color.Pink)
          .fontSize(25)
      }.margin(20)
    }
    .width('100%')
    .height(200)
    .borderWidth(2)
    .onDragStart(() => {
      this.message = 'drag'
      console.log("Drag start.")
    })
    .gesture(
      TapGesture()
        .tag("tap1")// 设置点击手势标志
        .onAction(() => {
          this.message = 'tap1'
        })
    )
    .gesture(
      LongPressGesture()
        .tag("longPress1")// 设置长按手势标志
        .onAction(() => {
          this.message = 'longPress'
        })
    )
    .gesture(
      SwipeGesture()
        .tag("swipe1")// 设置滑动手势标志
        .onAction(() => {
          this.message = 'swipe1'
        })
    )
    .gesture(
      PanGesture()
        .tag("pan1")// 设置拖动手势标志
        .onActionStart(() => {
          this.message = 'pan1'
        })
    )
    .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => {
      // 若该手势类型为长按手势，转换为长按手势事件
      if (gestureInfo.type == GestureControl.GestureType.LONG_PRESS_GESTURE) {
        let longPressEvent = event as LongPressGestureEvent;
        console.log("repeat " + longPressEvent.repeat)
      }
      // 若该手势类型为滑动手势，转换为滑动手势事件
      if (gestureInfo.type == GestureControl.GestureType.SWIPE_GESTURE) {
        let swipeEvent = event as SwipeGestureEvent;
        console.log("angle " + swipeEvent.angle)
      }
      // 若该手势类型为拖动手势，转换为拖动手势事件
      if (gestureInfo.type == GestureControl.GestureType.PAN_GESTURE) {
        let panEvent = event as PanGestureEvent;
        console.log("velocity " + panEvent.velocity)
      }
      // 自定义判定标准
      if (gestureInfo.type == GestureControl.GestureType.DRAG) {
        // 返回 REJECT 会使拖动手势失败
        return GestureJudgeResult.REJECT;
      } else if (gestureInfo.tag == 'longPress1' && event.fingerList.length > 0 && event.fingerList[0].localY < 100) {
        // 返回 CONTINUE 将保持系统判定。
        return GestureJudgeResult.CONTINUE;
      }
      return GestureJudgeResult.CONTINUE;
    })
  }
}

gestures1

示例2（自定义区域手势判定）

该示例通过配置onGestureJudgeBegin判定区域决定长按手势和拖拽是否响应。

// xxx.ets
import { PromptAction } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  scroller: Scroller = new Scroller()
  promptAction: PromptAction = this.getUIContext().getPromptAction();

  build() {
    Scroll(this.scroller) {
      Column({ space: 8 }) {
        Text("Drag 上下两层 上层绑定长按，下层绑定拖拽。先长按后平移上半区红色区域只会响应长按，先长按后平移下半区蓝色区域只会响应拖拽").width('100%').fontSize(20).fontColor('0xffdd00')
          .backgroundColor(0xeeddaa00)
        Stack({ alignContent: Alignment.Center }) {
          Column() {
            // 模拟上半区和下半区
            Stack().width('200vp').height('100vp').backgroundColor(Color.Red)
            Stack().width('200vp').height('100vp').backgroundColor(Color.Blue)
          }.width('200vp').height('200vp')
          // Stack的下半区是绑定了拖动手势的图像区域。
          Image($r('sys.media.ohos_app_icon'))
            .draggable(true)
            .onDragStart(()=>{
              this.promptAction.showToast({ message: "Drag 下半区蓝色区域，Image响应" })
            })
            .width('200vp').height('200vp')
          // Stack的上半区是绑定了长按手势的浮动区域。
          Stack() {
          }
          .width('200vp')
          .height('200vp')
          .hitTestBehavior(HitTestMode.Transparent)
          .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => {
            // 确定tag标志是否有值
            if (gestureInfo.tag) {
              console.log("gestureInfo tag" + gestureInfo.tag.toString())
            }
            console.log("gestureInfo Type " + gestureInfo.type.toString() + " isSystemGesture " + gestureInfo.isSystemGesture);
            console.log("pressure " + event.pressure + " fingerList.length " + event.fingerList.length
            + " timeStamp " + event.timestamp + " sourceType " + event.source.toString() + " titleX " + event.tiltX + " titleY " + event.tiltY + " rollAngle " + event.rollAngle + " sourcePool " + event.sourceTool.toString());
            // 如果是长按类型手势，判断点击的位置是否在上半区
            if (gestureInfo.type == GestureControl.GestureType.LONG_PRESS_GESTURE) {
              if (event.fingerList.length > 0 && event.fingerList[0].localY < 100) {
                return GestureJudgeResult.CONTINUE
              } else {
                return GestureJudgeResult.REJECT
              }
            }
            return GestureJudgeResult.CONTINUE
          })
          .gesture(GestureGroup(GestureMode.Parallel,
            LongPressGesture()
              .onAction((event: GestureEvent) => {
                this.promptAction.showToast({ message: "LongPressGesture 长按上半区 红色区域，红色区域响应" })
              })
              .tag("tap111")
          ))

        }.width('100%')
      }.width('100%')
    }
  }
}

gestures2

示例3（实时监测参与手势的有效触点的数量及其简要信息）

该示例通过配置fingerInfos实时检测参与手势的有效触点数量、各个触点ID及其坐标

// xxx.ets
@Entry
@Component
struct GestureDetectorExample {
  @State message: string = '触摸区域'
  @State fingerCount: number = 0
  @State fingerDetails: string = ''

  build() {
    Column() {
      // 显示信息区域
      Column() {
        Text(this.message)
          .fontSize(20)
          .fontWeight(FontWeight.Bold)

        Text(`触点数量: ${this.fingerCount}`)
          .fontSize(16)
          .margin({ top: 8 })


        Text(this.fingerDetails)
          .fontSize(14)
          .margin({ top: 8 })
      }
      .padding(10)
      .border({ width: 1, color: Color.Gray })

      // 手势检测区域
      Column()
        .width('90%')
        .height(200)
        .margin(20)
        .border({ width: 2, color: Color.Black })
        .gesture(
          GestureGroup(GestureMode.Exclusive,
            TapGesture()
              .onAction(() => {
                this.message = '单击事件'
              }),
            LongPressGesture()
              .onAction(() => {
                this.message = '长按事件'
              }),
            PanGesture()
              .onActionStart(() => {
                this.message = '拖动开始'
              })
              .onActionUpdate(() => {
                this.message = '拖动中...'
              })
              .onActionEnd(() => {
                this.message = '拖动结束'
                this.fingerCount = 0
                this.fingerDetails = ''
              })
          )
        )
        .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => {
          // 获取 fingerInfos 信息
          if (event?.fingerInfos) {
            this.fingerCount = event.fingerInfos.length
            this.fingerDetails = event.fingerInfos.map(finger =>
            `ID：${finger.id}: (${finger.localX.toFixed(1)}, ${finger.localY.toFixed(1)})`
            ).join('\n')
            console.log('触点信息:', JSON.stringify(event.fingerInfos))
          }
          if (this.fingerCount > 2) {
            return GestureJudgeResult.REJECT
          }
          return GestureJudgeResult.CONTINUE
        })
    }
    .width('100%')
    .height('100%')
    .padding(10)
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙图像AI分析错误码

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/dzKbRu
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录