大网数据广告活动
OpenHarmony 设备与应用开发

OpenHarmony 中文参考:TapGesture

· 52CE 我爱测

# TapGesture 支持单击、双击和多次点击事件的识别。 > **说明:** > > 从API version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。 > > 当组件同时绑定双击和单击手势且双击手势先绑定时,单击手势会有300ms的延时。 ## 接口 TapGesture(value?: TapGestureParameters) 创建点击手势对象。继承自GestureInterface\ 。 触

TapGesture

支持单击、双击和多次点击事件的识别。

说明:

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

当组件同时绑定双击和单击手势且双击手势先绑定时,单击手势会有300ms的延时。

接口

TapGesture(value?: TapGestureParameters)

创建点击手势对象。继承自GestureInterface<T>。

触发点击手势事件的设备类型为键盘或手柄时,事件的SourceTool值为Unknown,事件的SourceType值为KEY,JOYSTICK。

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

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

参数:

参数名 类型 必填 说明
value TapGestureParameters 否 点击手势的相关参数。

TapGestureParameters12+对象说明

说明:

为规范匿名对象的定义,API 12版本修改了此处的元素定义。其中,保留了历史匿名对象的起始版本信息,会出现外层元素@since版本号高于内层元素版本号的情况,但这不影响接口的使用。

点击手势参数。继承自BaseHandlerOptions。

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
count11+ number 否 是 识别的连续点击次数。当设置的值小于1或不设置时,会被转化为默认值。
默认值:1
取值范围:[0, +∞)
说明:
1. 当配置多击时,上一次的最后一根手指抬起和下一次的第一根手指按下的超时时间为300毫秒。
2. 当上次点击的位置与当前点击的位置距离超过60vp时,手势识别失败。在多指情况下,点击的位置为所有参与手势响应手指的平均位置。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
fingers11+ number 否 是 触发点击的手指数,最小为1指, 最大为10指。当设置小于1的值或不设置时,会被转化为默认值。
默认值:1
说明:
1. 当配置多指时,第一根手指按下后300毫秒内未有足够的手指数按下,手势识别失败;手指抬起时,抬起后剩余的手指数小于阈值时开始计时,如300ms内未全部抬起则手势识别失败。
2. 实际点击手指数超过配置值,手势识别成功。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
distanceThreshold number 否 是 点击手势移动阈值。当设置的值小于等于0或不设置时,会被转化为默认值。
默认值:2³¹-1
单位:vp
说明:
当手指的移动距离超出开发者预设的移动阈值时,点击识别失败。如果初始化为默认阈值时,手指移动超过组件热区范围,点击识别失败。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

事件

说明:

组件通过手势事件绑定不同GestureType的手势对象,各手势对象在响应手势操作的事件回调中提供手势相关信息。下面通过TapGesture手势对象的onAction事件响应点击事件,获取事件相关信息。其余手势对象的事件定义见各个手势对象章节。 若需绑定多种手势,请使用GestureGroup。

在GestureEvent的fingerList元素中,手指索引编号与位置相对应,即fingerList[index]的id为index。对于先按下但未参与当前手势触发的手指,fingerList中对应的位置为空。建议优先使用fingerInfos。

onAction

onAction(event: (event: GestureEvent) => void)

点击手势识别成功回调。

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

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

参数:

参数名 类型 必填 说明
event (event: GestureEvent) => void 是 手势事件回调函数。

EventLocationInfo20+

用于点击手势获取点击位置坐标。

属性

模型约束: 此接口仅可在Stage模型下使用。

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

名称 类型 只读 可选 说明
x number 否 否 相对于组件左上角的X坐标。
取值范围:[0, +∞)
单位:vp
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
y number 否 否 相对于组件左上角的Y坐标。
取值范围:[0, +∞)
单位:vp
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
windowX number 否 否 相对于窗口的左上角X坐标。
取值范围:[0, +∞)
单位:vp
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
windowY number 否 否 相对于窗口的左上角Y坐标。
取值范围:[0, +∞)
单位:vp
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
displayX number 否 否 相对于屏幕的左上角X坐标。
取值范围:[0, +∞)
单位:vp
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
displayY number 否 否 相对于屏幕的左上角Y坐标。
取值范围:[0, +∞)
单位:vp
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
globalDisplayX23+ number 否 是 相对于主屏幕左上角为原点的坐标系中的X坐标。
单位:vp
取值范围:[0, +∞)
原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。
globalDisplayY23+ number 否 是 相对于主屏幕左上角为原点的坐标系中的Y坐标。
单位:vp
取值范围:[0, +∞)
原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。

getCurrentLocalPosition

getCurrentLocalPosition?(): Coordinate2D

获取点击位置相对于当前组件实时位置的左上角坐标。

起始版本: 26.0.0

模型约束: 此接口仅可在Stage模型下使用。

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

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

返回值:

类型 说明
Coordinate2D 点击位置相对于当前组件实时位置的左上角坐标。

示例

示例1(双击手势识别)

该示例通过TapGesture实现了双击手势的识别。

// xxx.ets
@Entry
@Component
struct TapGestureExample {
  @State value: string = '';

  build() {
    Column() {
      // 单指双击文本触发手势事件
      Text('Click twice').fontSize(28)
        .gesture(
        TapGesture({ count: 2 })
          .onAction((event: GestureEvent) => {
            if (event) {
              this.value = JSON.stringify(event.fingerList[0])
            }
          })
        )
      Text(this.value)
    }
    .height(300)
    .width(300)
    .padding(20)
    .border({ width: 3 })
    .margin(30)
  }
}

[图示请参阅官方原文]

示例2(获取单击手势坐标)

该示例通过TapGesture获取单击手势点击位置的坐标。

// xxx.ets
@Entry
@Component
struct TapGestureExample {

  build() {
    Column() {
      Text('Click Once').fontSize(28)
        .gesture(
          TapGesture({ count: 1, fingers: 1 })
            .onAction((event: GestureEvent | undefined) => {
              if (event) {
                console.info(`x = ${JSON.stringify(event.tapLocation?.x)}`)
                console.info(`y = ${JSON.stringify(event.tapLocation?.y)}`)
                console.info(`windowX = ${JSON.stringify(event.tapLocation?.windowX)}`)
                console.info(`windowY = ${JSON.stringify(event.tapLocation?.windowY)}`)
                console.info(`displayX = ${JSON.stringify(event.tapLocation?.displayX)}`)
                console.info(`displayY = ${JSON.stringify(event.tapLocation?.displayY)}`)
                // 从API version 23开始,新增globalDisplayX和globalDisplayY属性。
                console.info(`globalDisplayX = ${JSON.stringify(event.tapLocation?.globalDisplayX)}`)
                console.info(`globalDisplayY = ${JSON.stringify(event.tapLocation?.globalDisplayY)}`)
              }
            })
        )
    }
    .height(200)
    .width(300)
    .padding(20)
    .border({ width: 3 })
    .margin(30)
  }
}

[图示请参阅官方原文]

示例3(获取组件实时位置)

该示例通过getCurrentLocalPosition方法获取当前组件基于其实时位置的左上角坐标。

从API版本26.0.0开始,新增支持getCurrentLocalPosition接口。

// xxx.ets
@Entry
@Component
struct GetCurrentLocalPositionExample {
  @State positionText: string = '';
  @State textOffsetY: number = 0;

  build() {
    Column() {
      Button('点击获取点击位置相对于当前组件实时位置左上角的坐标').translate({ y: this.textOffsetY })
        .gesture(
          TapGesture({ count: 1 })
            .onAction((event: GestureEvent) => {
              if (event) {
                this.textOffsetY = -200;
                setTimeout(() => {
                  let localPos: Coordinate2D | undefined = event?.tapLocation?.getCurrentLocalPosition?.();
                  this.positionText = `相对于当前组件实时位置左上角的坐标:\n  x: ${localPos?.x ?? 0}\n  y: ${localPos?.y ?? 0}`;
                }, 2000);
              }
            })
        )

      Text(this.positionText)
    }.width('100%')
  }
}

[图示请参阅官方原文]

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。