1# 点击事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9组件被点击时触发的事件。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 点击事件遵循[触摸事件](../arkui-ts/ts-universal-events-touch.md)分发流程，触摸事件支持屏蔽、透传等自定义行为。 16> 17> 事件分发可参考[事件交互流程](../../../ui/arkts-interaction-basic-principles.md#事件交互流程)，手势事件处理流程可参考[多层级手势事件](../../../ui/arkts-gesture-events-multi-level-gesture.md)。 18> 19> 当该点击事件由键盘或者手柄触发时，不会触发[onGestureJudgeBegin](./ts-gesture-customize-judge.md#ongesturejudgebegin)，[onGestureRecognizerJudgeBegin](./ts-gesture-blocking-enhancement.md#ongesturerecognizerjudgebegin)和[willClick](../arkts-apis-uicontext-uiobserver.md#onwillclick12)的回调。 20 21## onClick<sup>12+</sup> 22 23onClick(event: Callback\<ClickEvent>, distanceThreshold: number): T 24 25点击动作触发该回调。 26 27当触发点击事件的设备类型为键盘或手柄时，事件的[SourceTool](ts-gesture-settings.md#sourcetool枚举说明9)值为Unknown。 28 29新增distanceThreshold参数，设置点击手势移动阈值。手指移动超出阈值时，点击手势识别失败。 30对于无手指移动距离限制的点击场景，建议使用原有接口。若需限制点击时手指移动范围，建议使用该接口。 31 32**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 33 34> **说明：** 35> 36> 从API version 12开始，在使用卡片能力时，存在以下限制： 37> 1. 如果手指按下的持续时间超过800ms，不能触发点击事件。 38> 2. 如果手指按下后移动位移超过20px，不能触发点击事件。 39 40**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| ------ | --------------------------------- | ---- | -------------------- | 48| event | Callback\<[ClickEvent](#clickevent)> | 是 | 点击事件的回调函数。 | 49| distanceThreshold | number | 是 | 点击事件移动阈值。当设置的值小于等于0时，会被转化为默认值。<br/>默认值：2^31-1<br/>单位：vp<br/>**说明：**<br/>当手指的移动距离超出开发者预设的移动阈值时，点击识别失败。如果初始化为默认阈值时，手指移动超过组件热区范围，点击识别失败。 | 50 51> **说明：** 52> 53> 如果执行滑动操作，但滑动距离未超过点击事件移动阈值，并且抬手时手指在组件热区范围内，也会触发点击事件。 54 55**返回值：** 56 57| 类型 | 说明 | 58| -------- | -------- | 59| T | 返回当前组件。 | 60 61## onClick 62 63onClick(event: (event: ClickEvent) => void): T 64 65点击动作触发该回调。 66 67触发点击事件的设备类型为键盘或手柄时，事件的SourceTool值为Unknown。 68 69**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 70 71> **说明：** 72> 73> 从API version 9开始，使用卡片能力时存在以下限制： 74> 1. 如果手指按下的持续时间超过800ms，不能触发点击事件。 75> 2. 如果手指按下后移动位移超过20px，不能触发点击事件。 76 77**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 78 79**系统能力：** SystemCapability.ArkUI.ArkUI.Full 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| ------ | --------------------------------- | ---- | -------------------- | 85| event | (event: [ClickEvent](#clickevent)) => void | 是 | 点击事件的回调函数。 | 86 87**返回值：** 88 89| 类型 | 说明 | 90| -------- | -------- | 91| T | 返回当前组件。 | 92 93## ClickEvent 94 95继承于[BaseEvent](ts-gesture-customize-judge.md#baseevent8)。 96 97**系统能力：** SystemCapability.ArkUI.ArkUI.Full 98 99| 名称 | 类型 | 只读 | 可选 | 说明 | 100| ------------------- | ------------------------- | ------ | -------- | -------------------------------------------------------- | 101| x | number | 否 | 否 | 点击位置相对于被点击元素左边缘的X坐标。<br/>单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 102| y | number | 否 | 否 | 点击位置相对于被点击元素原始区域左上角的Y坐标。<br/>单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 103| windowX<sup>10+</sup> | number | 否 | 否 | 点击位置相对于应用窗口左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 104| windowY<sup>10+</sup> | number | 否 | 否 | 点击位置相对于应用窗口左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 105| displayX<sup>10+</sup> | number | 否 | 否 | 点击位置相对于应用屏幕左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 106| displayY<sup>10+</sup> | number | 否 | 否 | 点击位置相对于应用屏幕左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 107| screenX<sup>(deprecated)</sup> | number | 否 | 否 | 点击位置相对于应用窗口左上角的X坐标。<br>单位：vp<br/>从API version 10开始不再维护，建议使用windowX代替。 | 108| screenY<sup>(deprecated)</sup> | number | 否 | 否 | 点击位置相对于应用窗口左上角的Y坐标。<br>单位：vp<br/>从API version 10开始不再维护，建议使用windowY代替。 | 109| preventDefault<sup>12+</sup> | () => void | 否 | 否 | 阻止默认事件。<br/> **说明：** 该接口仅支持部分组件使用，当前支持组件：RichEditor、Hyperlink，不支持的组件使用时会抛出异常。暂不支持异步调用和提供Modifier接口。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 110| hand<sup>15+</sup> | [InteractionHand](./ts-appendix-enums.md#interactionhand15) | 否 | 是 | 表示事件是由左手点击还是右手点击触发。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 111| globalDisplayX<sup>20+</sup> | number | 否 | 是 | 点击位置相对于全局屏幕的左上角的X坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 112| globalDisplayY<sup>20+</sup> | number | 否 | 是 | 点击位置相对于全局屏幕的左上角的Y坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 113 114**错误码：** 115 116以下错误码的详细介绍请参见[交互事件错误码](../errorcode-event.md)。 117 118| 错误码ID | 错误信息 | 119| --------- | ------- | 120| 100017 | Component does not support prevent function. | 121 122## EventTarget<sup>8+</sup> 123 124[BaseEvent](ts-gesture-customize-judge.md#baseevent8)中参数target的类型。 125 126触发事件的元素对象的显示区域。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130| 名称 | 类型 | 只读 | 可选 | 说明 | 131| ---- | ------------------------- |-----|------| ---------- | 132| area | [Area](ts-types.md#area8) | 否 | 否 | 目标元素的区域信息。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 133| id<sup>15+</sup> | [string](ts-universal-attributes-component-id.md) | 否 | 是 | 开发者设置的节点id。默认值：undefined <br/>**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 134 135## 示例 136 137该示例通过按钮设置点击事件，点击按钮可获取点击事件的相关参数。 138 139```ts 140// xxx.ets 141@Entry 142@Component 143struct ClickExample { 144 @State text: string = ''; 145 146 build() { 147 Column() { 148 Row({ space: 20 }) { 149 Button('Click').width(100).height(40).id('click1') 150 .onClick((event?: ClickEvent) => { 151 if(event){ 152 this.text = 'Click Point:' + '\n windowX:' + event.windowX + '\n windowY:' + event.windowY 153 + '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:(' 154 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:' 155 + event.target.area.width + '\n height:' + event.target.area.height + '\n id:'+ event.target.id 156 + '\ntargetDisplayId:' + event.targetDisplayId + '\ntimestamp' + event.timestamp; 157 } 158 }, 20) 159 Button('Click').width(200).height(50).id('click2') 160 .onClick((event?: ClickEvent) => { 161 if(event){ 162 this.text = 'Click Point:' + '\n windowX:' + event.windowX + '\n windowY:' + event.windowY 163 + '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:(' 164 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:' 165 + event.target.area.width + '\n height:' + event.target.area.height + '\n id:'+ event.target.id 166 + '\ntargetDisplayId:' + event.targetDisplayId + '\ntimestamp' + event.timestamp; 167 } 168 }, 20) 169 }.margin(20) 170 171 Text(this.text).margin(15) 172 }.width('100%') 173 } 174} 175``` 176
