1# Touch Event 2 3A touch event is triggered when a finger is pressed against, swipes on, or is lifted from a component. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> For details about event dispatch, see [Event Interaction Pipeline](../../../ui/arkts-interaction-basic-principles.md#event-interaction-pipeline). For details about gesture event handling, see [Multi-level Gesture Events](../../../ui/arkts-gesture-events-multi-level-gesture.md). 10> 11> For details about how to bind gesture events, see [Gesture Binding](./ts-gesture-settings.md). 12 13## onTouch 14 15onTouch(event: (event: TouchEvent) => void): T 16 17Invoked when a touch event is triggered. Touch events bubble by default and can be consumed by multiple components. To prevent event bubbling, use the **stopPropagation** API of [TouchEvent](#touchevent). Mouse left-click events are converted to touch events and will also trigger this callback. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name| Type | Mandatory| Description | 26| ------ | --------------------------------- | ---- | -------------------- | 27| event | [TouchEvent](#touchevent) | Yes | **TouchEvent** object.| 28 29**Return value** 30 31| Type| Description| 32| -------- | -------- | 33| T | Current component.| 34 35## TouchEvent 36 37Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). In non-event injection scenarios, **changedTouches** contains points resampled at the screen refresh rate, while **touches** contains points reported at the device's refresh rate. As such, **changedTouches** data may differ from **touches**. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41| Name | Type | Description | 42| ------------------- | ---------------------------------------- | ------------ | 43| type | [TouchType](ts-appendix-enums.md#touchtype) | Type of the touch event.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 44| touches | Array<[TouchObject](#touchobject)> | Information about all touch points (for multi-touch). Each element represents one touch point. When using this property, you need to check whether it is empty.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 45| changedTouches | Array<[TouchObject](#touchobject)> | Information about touch points that changed and triggered the event. When using this property, you need to check whether it is empty.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| stopPropagation | () => void | Stops the event from bubbling upwards or downwards.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| preventDefault<sup>12+</sup> | () => void | Blocks the default event.<br> **NOTE**<br>This API is only supported by the following components: **Hyperlink**. An exception is thrown when this API is used with unsupported components. Asynchronous calls and the **Modifier** API are not yet supported.<br> **Atomic service API**: This API can be used in atomic services since API version 12.| 48 49**Error codes** 50 51For details about the error codes, see [Interaction Event Error Codes](../errorcode-event.md). 52 53| Error Code | Error Message| 54| --------- | ------- | 55| 100017 | Component does not support prevent function. | 56 57### getHistoricalPoints<sup>10+</sup> 58 59getHistoricalPoints(): Array<HistoricalPoint> 60 61Obtains all historical points of the current frame. The touch event frequency per frame varies by device. This API can be called only in [TouchEvent](#touchevent). You can use this API to obtain the historical points of the current frame when [onTouch](#ontouch) is invoked. Typically, [onTouch](#ontouch) is invoked once per frame. If multiple [TouchEvent](#touchevent) instances are received in a single frame, the last point is returned through **onTouch**, and the remaining points are stored as historical points. For multi-touch events within the same frame, multiple** onTouch** calls may occur. 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**Return value** 68 69| Type | Description | 70| ------ | ----------------------- | 71| Array<[HistoricalPoint](#historicalpoint10)>| Array of historical points.| 72 73 74## TouchObject 75 76**System capability**: SystemCapability.ArkUI.ArkUI.Full 77 78| Name | Type | Description | 79| ------- | ------------------------------------------- | ------------------------------------- | 80| type | [TouchType](ts-appendix-enums.md#touchtype) | Type of the touch event.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 81| id | number | Unique identifier of a finger.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 82| x | number | X coordinate of the touch point relative to the upper left corner of the event responding component.<br>Unit: vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 83| y | number | Y coordinate of the touch point relative to the upper left corner of the event responding component.<br>Unit: vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 84| windowX<sup>10+</sup> | number | X coordinate of the touch point 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. | 85| windowY<sup>10+</sup> | number | Y coordinate of the touch point 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. | 86| displayX<sup>10+</sup> | number | X coordinate of the touch point 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. | 87| displayY<sup>10+</sup> | number | Y coordinate of the touch point 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. | 88| screenX<sup>(deprecated)</sup> | number | X coordinate of the touch point 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. | 89| screenY<sup>(deprecated)</sup> | number | Y coordinate of the touch point 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. | 90| PressedTime<sup>15+</sup> | number | Time when the finger is pressed.<br>Unit: ns<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 91| pressure<sup>15+</sup> | number | Pressure value of the finger press.<br>Value range: [0, 65535). The greater the pressure, the larger the value.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 92| width<sup>15+</sup> | number | Width of the area pressed by the finger.<br>Unit: vp.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 93| height<sup>15+</sup> | number | Height of the area pressed by the finger.<br>Unit: vp.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 94| hand<sup>15+</sup> | [InteractionHand](./ts-gesture-settings.md#interactionhand15) | Whether the event was 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.| 95| globalDisplayX<sup>20+</sup> | number | X coordinate of the touch point relative to the upper left corner of the global display.<br>Unit: vp.<br>Value range: [0, +��).<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 96| globalDisplayY<sup>20+</sup> | number | Y coordinate of the touch point relative to the upper left corner of the global display.<br>Unit: vp.<br>Value range: [0, +��).<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 97 98## HistoricalPoint<sup>10+</sup> 99 100Provides historical touch point information. 101 102**Atomic service API**: This API can be used in atomic services since API version 11. 103 104**System capability**: SystemCapability.ArkUI.ArkUI.Full 105 106| Name | Type | Description | 107| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | 108| touchObject | [TouchObject](#touchobject) | Basic information of the historical point. | 109| size | number | Size of the contact area between the finger and screen for the historical point.<br>Default value: **0** | 110| force | number | Touch force of the historical point.<br>Default value: **0**.<br>Value range: [0, 65535). The greater the pressure, the larger the value.| 111| timestamp | number | Timestamp of the historical point. It is the interval between the time when the event is triggered and the time when the system starts.<br>Unit: ns | 112 113## Example 114 115This example configures a touch event for a button. When the button is touched, it obtains relevant parameters of the touch event. 116 117```ts 118// xxx.ets 119@Entry 120@Component 121struct TouchExample { 122 @State text: string = ''; 123 @State eventType: string = ''; 124 125 build() { 126 Column() { 127 Button('Touch').height(40).width(100) 128 .onTouch((event?: TouchEvent) => { 129 if (event && event.sourceTool === SourceTool.Finger) { 130 if (event.type === TouchType.Down) { 131 this.eventType = 'Down'; 132 } 133 if (event.type === TouchType.Up) { 134 this.eventType = 'Up'; 135 } 136 if (event.type === TouchType.Move) { 137 this.eventType = 'Move'; 138 } 139 // 1. The cancel event is triggered when the user touches the home button to return to the home screen while keeping a finger on the screen. 140 // 2. On a foldable phone, the cancel event is triggered when the user folds the phone to switch to the external screen while keeping a finger on the screen. 141 if (event.type === TouchType.Cancel) { 142 this.eventType = 'Cancel'; 143 } 144 if (event.touches) { 145 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 146 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 147 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 148 + event.target.area.width + '\nheight:' + event.target.area.height + '\ntargetDisplayId:' + 149 event.targetDisplayId + '\npressedTime:' + event.touches[0].pressedTime + '\npressure:' + 150 event.touches[0].pressure + 151 '\nwidth:' + event.touches[0].width + '\nheight:' + event.touches[0].height; 152 } 153 } 154 }) 155 Button('Touch').height(50).width(200).margin(20) 156 .onTouch((event?: TouchEvent) => { 157 if (event) { 158 if (event.type === TouchType.Down) { 159 this.eventType = 'Down'; 160 } 161 if (event.type === TouchType.Up) { 162 this.eventType = 'Up'; 163 } 164 if (event.type === TouchType.Move) { 165 this.eventType = 'Move'; 166 } 167 // 1. The cancel event is triggered when the user touches the home button to return to the home screen while keeping a finger on the screen. 168 // 2. On a foldable phone, the cancel event is triggered when the user folds the phone to switch to the external screen while keeping a finger on the screen. 169 if (event.type === TouchType.Cancel) { 170 this.eventType = 'Cancel'; 171 } 172 if (event.touches) { 173 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 174 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 175 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 176 + event.target.area.width + '\nheight:' + event.target.area.height + '\ntargetDisplayId:' + 177 event.targetDisplayId + '\npressedTime:' + event.touches[0].pressedTime + '\npressure:' + 178 event.touches[0].pressure + 179 '\nwidth:' + event.touches[0].width + '\nheight:' + event.touches[0].height; 180 } 181 } 182 }) 183 Text(this.text) 184 }.width('100%').padding(30) 185 } 186} 187``` 188 189 190
