1# Click Event 2 3A click event is triggered when a component is clicked. 4 5> **NOTE** 6> 7> The event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> For details about the event distribution process, see [Multi-level Gesture Events](../../../ui/arkts-gesture-events-multi-level-gesture.md). 10 11## onClick<sup>12+</sup> 12 13onClick(event: Callback\<ClickEvent>, distanceThreshold: number): T 14 15Called when a click event occurs. 16 17When the click event is triggered by a keyboard or game controller, the value of **SourceTool** is **Unknown**. 18 19Compared with the original **onClick** API, this API has the **distanceThreshold** parameter that specifies the finger movement threshold for click events. If the finger's movement exceeds the set threshold, the gesture recognition will fail. 20For scenarios where there is no restriction on the finger movement distance during a click, the original API is recommended. If there is a requirement for the finger to stay within a certain area during the click, this API is recommended. 21 22**Widget capability**: This API can be used in ArkTS widgets since API version 12. 23 24> **NOTE** 25> 26> Since API version 12, the following constraints apply when this API is used in service widgets: 27> 1. Click events will not be triggered if the finger is pressed for more than 800 ms. 28> 2. Click events will not be triggered if the finger moves more than 20 px after pressing down. 29 30**Atomic service API**: This API can be used in atomic services since API version 12. 31 32**System capability**: SystemCapability.ArkUI.ArkUI.Full 33 34**Parameters** 35 36| Name| Type | Mandatory| Description | 37| ------ | --------------------------------- | ---- | -------------------- | 38| event | [ClickEvent](#clickevent) | Yes | [ClickEvent](#clickevent) object.| 39| distanceThreshold | number | Yes | Finger movement threshold for click events. If the value specified is less than or equal to 0, it will be converted to the default value.<br>Default value: 2^31-1<br>Unit: vp<br>**NOTE**<br>If the finger movement exceeds the preset movement threshold, the gesture recognition fails. If the default threshold is used during initialization and the finger moves beyond the component's touch target, the gesture recognition fails.| 40 41**Return value** 42 43| Type| Description| 44| -------- | -------- | 45| T | Current component.| 46 47## onClick 48 49onClick(event: (event: ClickEvent) => void): T 50 51Called when a click event occurs. 52 53When the click event is triggered by a keyboard or gamepad, the value of **SourceTool** is **Unknown**. 54 55**Widget capability**: This API can be used in ArkTS widgets since API version 9. 56 57> **NOTE** 58> 59> Since API version 9, the following constraints apply when this API is used in service widgets: 60> 1. Click events will not be triggered if the finger is pressed for more than 800 ms. 61> 2. Click events will not be triggered if the finger moves more than 20 px after pressing down. 62 63**Atomic service API**: This API can be used in atomic services since API version 11. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67**Parameters** 68 69| Name| Type | Mandatory| Description | 70| ------ | --------------------------------- | ---- | -------------------- | 71| event | [ClickEvent](#clickevent) | Yes | [ClickEvent](#clickevent) object.| 72 73**Return value** 74 75| Type| Description| 76| -------- | -------- | 77| T | Current component.| 78 79## ClickEvent 80 81Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). 82 83**System capability**: SystemCapability.ArkUI.ArkUI.Full 84 85| Name | Type | Description | 86| ------------------- | ------------------------------------ | -------------------------------------------------------- | 87| x | number | X coordinate of the click relative to the left edge of the clicked component.<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 88| y | number | Y coordinate of the click relative to the upper left corner of the clicked component's original area.<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 89| target<sup>8+</sup> | [EventTarget](#eventtarget8) | Display area of the object that triggers the event.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 90| windowX<sup>10+</sup> | number | X coordinate of the click relative to the upper left corner of the application window.<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 91| windowY<sup>10+</sup> | number | Y coordinate of the click relative to the upper left corner of the application window.<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 92| displayX<sup>10+</sup> | number | X coordinate of the click relative to the upper left corner of the application screen.<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 93| displayY<sup>10+</sup> | number | Y coordinate of the click relative to the upper left corner of the application screen.<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 94| screenX<sup>(deprecated)</sup> | number | X coordinate of the click relative to the upper left corner of the application window.<br>Unit: vp<br>This API is deprecated since API version 10. You are advised to use **windowX** instead.| 95| screenY<sup>(deprecated)</sup> | number | Y coordinate of the click relative to the upper left corner of the application window.<br>Unit: vp<br>This API is deprecated since API version 10. You are advised to use **windowY** instead.| 96| preventDefault<sup>12+</sup> | () => void | Blocks the default event.<br> **NOTE**<br>This API is only supported by the following components: **RichEditor** and **Hyperlink**. An exception is thrown when this API is used with unsupported components. Currently, asynchronous calls and Modifier APIs are not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 97| targetDisplayId<sup>15+</sup> | number | ID of the screen where the event occurs.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 98| hand<sup>15+</sup> | [InteractionHand](./ts-gesture-settings.md#interactionhand15) | Whether the event is triggered by a left-hand or right-hand tap.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 99 100**Error codes** 101 102For details about the error codes, see [Interaction Event Error Codes](../errorcode-event.md). 103 104| ID | Error Message| 105| --------- | ------- | 106| 100017 | Component does not support prevent function. | 107 108## EventTarget<sup>8+</sup> 109 110Describes the display area of the object that triggers the event. 111 112**Widget capability**: This API can be used in ArkTS widgets since API version 9. 113 114**Atomic service API**: This API can be used in atomic services since API version 11. 115 116**System capability**: SystemCapability.ArkUI.ArkUI.Full 117 118| Name | Type | Description | 119| ---- | ------------------------- | ---------- | 120| area | [Area](ts-types.md#area8) | Area information of the target element.| 121| id<sup>15+</sup> | [string](ts-universal-attributes-component-id.md) | Custom node ID. Default value: **undefined**.| 122 123## Example 124 125This example shows how to configure a click event for a button. By doing so, you can obtain relevant parameters of the click event when the button is pressed. 126 127```ts 128// xxx.ets 129@Entry 130@Component 131struct ClickExample { 132 @State text: string = '' 133 134 build() { 135 Column() { 136 Row({ space: 20 }) { 137 Button('Click').width(100).height(40).id('click') 138 .onClick((event?: ClickEvent) => { 139 if(event){ 140 this.text = 'Click Point:' + '\n windowX:' + event.windowX + '\n windowY:' + event.windowY 141 + '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:(' 142 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:' 143 + event.target.area.width + '\n height:' + event.target.area.height + '\ntimestamp' + event.timestamp 144 + '\n id:'+ event.target.id + '\ntargetDisplayId:' + event.targetDisplayId; 145 } 146 }, 20) 147 Button('Click').width(200).height(50).id('click') 148 .onClick((event?: ClickEvent) => { 149 if(event){ 150 this.text = 'Click Point:' + '\n windowX:' + event.windowX + '\n windowY:' + event.windowY 151 + '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:(' 152 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:' 153 + event.target.area.width + '\n height:' + event.target.area.height + '\ntimestamp' + event.timestamp 154 + '\n id:'+ event.target.id + '\ntargetDisplayId:' + event.targetDisplayId; 155 } 156 }, 20) 157 }.margin(20) 158 159 Text(this.text).margin(15) 160 }.width('100%') 161 } 162} 163``` 164 165
