点击事件
组件被点击时触发的事件。
说明:
从API version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
点击事件遵循触摸事件分发流程,触摸事件支持屏蔽、透传等自定义行为。
当该点击事件由键盘或者手柄触发时,不会触发onGestureJudgeBegin,onGestureRecognizerJudgeBegin和willClick的回调。
onClick12+
onClick(event: Callback<ClickEvent>, distanceThreshold: number): T
点击动作触发该回调。
当触发点击事件的设备类型为键盘或手柄时,事件的SourceTool值为Unknown,事件的SourceType值为KEY,JOYSTICK。
新增distanceThreshold参数,设置点击手势移动阈值。手指移动超出阈值时,点击手势识别失败。
对于无手指移动距离限制的点击场景,建议使用原有接口。若需限制点击时手指移动范围,建议使用该接口。
卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。
说明:
从API version 12开始,在使用卡片能力时,存在以下限制:
- 如果手指按下的持续时间超过800ms,不能触发点击事件。
- 如果手指按下后移动位移超过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开始,使用卡片能力时存在以下限制:
- 如果手指按下的持续时间超过800ms,不能触发点击事件。
- 如果手指按下后移动位移超过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 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
