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

点击事件

· 52CE 我爱测

对于无手指移动距离限制的点击场景,建议使用原有接口。若需限制点击时手指移动范围,建议使用该接口。

点击事件

组件被点击时触发的事件。

说明:

onClick12+

onClick(event: Callback<ClickEvent>, distanceThreshold: number): T

点击动作触发该回调。

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

新增distanceThreshold参数,设置点击手势移动阈值。手指移动超出阈值时,点击手势识别失败。

对于无手指移动距离限制的点击场景,建议使用原有接口。若需限制点击时手指移动范围,建议使用该接口。

卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。

说明:

  • 从API version 12开始,在使用卡片能力时,存在以下限制:

    1. 如果手指按下的持续时间超过800ms,不能触发点击事件。
    2. 如果手指按下后移动位移超过20px,不能触发点击事件。
  • 该接口不支持在attributeModifier中调用。

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

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

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

参数:

参数名 类型 必填 说明
event Callback<ClickEvent> 是 点击事件的回调函数。
distanceThreshold number 是 点击事件移动阈值。当设置的值小于等于0时,会被转化为默认值。
默认值:2^31-1
单位:vp
说明:
当手指的移动距离超出开发者预设的移动阈值时,点击识别失败。如果初始化为默认阈值时,手指移动超过组件热区范围,点击识别失败。

说明:

如果执行滑动操作,但滑动距离未超过点击事件移动阈值,并且抬手时手指在组件热区范围内,也会触发点击事件。

返回值:

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

onClick

onClick(event: (event: ClickEvent) => void): T

点击动作触发该回调。

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

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。

说明:

从API version 9开始,使用卡片能力时存在以下限制:

  1. 如果手指按下的持续时间超过800ms,不能触发点击事件。
  2. 如果手指按下后移动位移超过20px,不能触发点击事件。

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

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

参数:

参数名 类型 必填 说明
event (event: ClickEvent) => void 是 点击事件的回调函数。

返回值:

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

ClickEvent

继承于BaseEvent。

属性

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

名称 类型 只读 可选 说明
x number 否 否 点击位置在被点击元素为基准的组件坐标系中的X坐标。onClick的distanceThreshold设置后,点击位置为抬手点。触发事件的是键盘或手柄时,点击位置为被点击元素的中心点。
单位:vp
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
y number 否 否 点击位置在被点击元素为基准的组件坐标系中的Y坐标。onClick的distanceThreshold设置后,点击位置为抬手点。触发事件的是键盘或手柄时,点击位置为被点击元素的中心点。
单位:vp
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
windowX10+ number 否 否 点击位置在当前应用窗口坐标系中的X坐标。onClick的distanceThreshold设置后,点击位置为抬手点。
单位:vp
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
windowY10+ number 否 否 点击位置在当前应用窗口坐标系中的Y坐标。onClick的distanceThreshold设置后,点击位置为抬手点。
单位:vp
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
displayX10+ number 否 否 点击位置在当前应用屏幕坐标系中的X坐标。
单位:vp
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
displayY10+ number 否 否 点击位置在当前应用屏幕坐标系中的Y坐标。
单位:vp
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
screenX(deprecated) number 否 否 点击位置在当前应用窗口坐标系中的X坐标。
单位:vp
说明: 从API version 7开始支持,从API version 10开始废弃,建议使用windowX替代。
screenY(deprecated) number 否 否 点击位置在当前应用窗口坐标系中的Y坐标。
单位:vp
说明: 从API version 7开始支持,从API version 10开始废弃,建议使用windowY替代。
preventDefault12+ () => void 否 否 阻止默认事件。
说明: 该接口仅支持部分组件使用,当前支持组件:RichEditor、Hyperlink,不支持的组件使用时会抛出异常。暂不支持异步调用和提供Modifier接口。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
hand15+ InteractionHand 否 是 表示事件是由左手点击还是右手点击触发。
原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
globalDisplayX20+ number 否 是 点击位置在全局坐标系中的X坐标。
单位:vp
取值范围:[0, +∞)
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
globalDisplayY20+ number 否 是 点击位置在全局坐标系中的Y坐标。
单位:vp
取值范围:[0, +∞)
原子化服务API: 从API version 20开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。

错误码:

以下错误码的详细介绍请参见交互事件错误码。

错误码ID 错误信息
100017 Component does not support prevent function.

getCurrentLocalPosition

getCurrentLocalPosition?(): Coordinate2D

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

起始版本: 26.0.0

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

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

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

返回值:

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

EventTarget8+

BaseEvent中参数target的类型。

触发事件的元素对象的显示区域。

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

名称 类型 只读 可选 说明
area Area 否 否 目标元素的区域信息。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
id15+ string 否 是 开发者设置的节点id。默认值:undefined
卡片能力: 从API version 15开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。

示例

示例1(获取点击事件相关参数)

该示例通过按钮设置点击事件ClickEvent,点击按钮可获取点击事件的相关参数。

// xxx.ets
@Entry
@Component
struct ClickExample {
  @State text: string = '';

  build() {
    Column() {
      Row({ space: 20 }) {
        Button('Click1').width(100).height(40).id('click1')
          .onClick((event?: ClickEvent) => {
            if (event) {
              this.text =
                `Click Point:\n  windowX:${event.windowX}\n  windowY:${event.windowY}\n  x:${event.x}\n  y:${event.y}\n target:\n  component globalPos:(${event.target.area.globalPosition.x},${event.target.area.globalPosition.y})\n  width:${event.target.area.width}\n  height:${event.target.area.height}\n  id:${event.target.id}\ntargetDisplayId:${event.targetDisplayId}\ntimestamp${event.timestamp}`
            }
          }, 20)
        Button('Click2').width(200).height(50).id('click2')
          .onClick((event?: ClickEvent) => {
            if (event) {
              this.text =
                `Click Point:\n  windowX:${event.windowX}\n  windowY:${event.windowY}\n  x:${event.x}\n  y:${event.y}\n target:\n  component globalPos:(${event.target.area.globalPosition.x},${event.target.area.globalPosition.y})\n  width:${event.target.area.width}\n  height:${event.target.area.height}\n  id:${event.target.id}\ntargetDisplayId:${event.targetDisplayId}\ntimestamp${event.timestamp}`
            }
          }, 20)
      }.margin(20)

      Text(this.text).margin(15)
    }.width('100%')
  }
}

[图示请参阅官方原文]

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

该示例通过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 })
        .onClick((event?: ClickEvent) => {
          if (event) {
            this.textOffsetY = -200;
            setTimeout(() => {
              let localPos: Coordinate2D | undefined = event?.getCurrentLocalPosition?.();
              this.positionText = `相对于当前组件实时位置左上角的坐标:\n  x: ${localPos?.x}\n  y: ${localPos?.y}`;
            }, 2000);
          }
        })

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

[图示请参阅官方原文]

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

资料来源与适用范围

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

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

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