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> This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9## onTouch 10 11onTouch(event: (event: TouchEvent) => void): T 12 13Invoked when a touch event is triggered. 14 15**Atomic service API**: This API can be used in atomic services since API version 11. 16 17**System capability**: SystemCapability.ArkUI.ArkUI.Full 18 19**Parameters** 20 21| Name| Type | Mandatory| Description | 22| ------ | --------------------------------- | ---- | -------------------- | 23| event | [TouchEvent](#touchevent) | Yes | **TouchEvent** object.| 24 25**Return value** 26 27| Type| Description| 28| -------- | -------- | 29| T | Current component.| 30 31## TouchEvent 32 33Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). In non-injected event scenarios, **changedTouches** indicates points resampled according to the screen's refresh rate, while **touches** indicates points based on the device's refresh rate. As such, the data in **changedTouches** may differ from that in **touches**. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name | Type | Description | 38| ------------------- | ---------------------------------------- | ------------ | 39| 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. | 40| touches | Array<[TouchObject](#touchobject)> | All finger information.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 41| changedTouches | Array<[TouchObject](#touchobject)> | Finger information changed.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42| 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.| 43| preventDefault<sup>12+</sup> | () => void | Blocks the default event.<br> **NOTE**<br>This API is only supported by the following components: **Hyperlink**. 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.| 44 45### getHistoricalPoints<sup>10+</sup> 46 47getHistoricalPoints(): Array<HistoricalPoint> 48 49Obtains all historical points of the current frame. The touch event frequency of a frame varies by device, and all touch events of the current frame are referred to as its historical points. 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. [onTouch](#ontouch) is invoked only once for a frame. If the value of [TouchEvent](#touchevent) received by the current frame is greater than 1, the last point of the frame is returned through [onTouch](#ontouch). The remaining points are regarded as historical points. 50 51**Atomic service API**: This API can be used in atomic services since API version 11. 52 53**System capability**: SystemCapability.ArkUI.ArkUI.Full 54 55**Return value** 56 57| Type | Description | 58| ------ | ----------------------- | 59| Array<[HistoricalPoint](#historicalpoint10)>| Array of historical points.| 60 61 62## TouchObject 63 64**System capability**: SystemCapability.ArkUI.ArkUI.Full 65 66| Name | Type | Description | 67| ------- | ------------------------------------------- | ------------------------------------- | 68| 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. | 69| id | number | Unique identifier of a finger.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 70| 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.| 71| 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.| 72| 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. | 73| 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. | 74| 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. | 75| 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. | 76| 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. | 77| 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. | 78| PressedTime<sup>15+</sup> | number | Time when the finger is pressed.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 79| pressure<sup>15+</sup> | number | Pressure value of the finger press.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 80| width<sup>15+</sup> | number | Width of the area pressed by the finger.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 81| height<sup>15+</sup> | number | Height of the area pressed by the finger.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 82| 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.| 83 84## HistoricalPoint<sup>10+</sup> 85 86**Atomic service API**: This API can be used in atomic services since API version 11. 87 88**System capability**: SystemCapability.ArkUI.ArkUI.Full 89 90| Name | Type | Description | 91| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | 92| touchObject | [TouchObject](#touchobject) | Basic information of the historical point. | 93| size | number | Size of the contact area between the finger and screen for the historical point.<br>Default value: **0** | 94| 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.| 95| 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 | 96 97## Example 98 99This example configures a touch event for a button. When the button is touched, it obtains relevant parameters of the touch event. 100 101```ts 102// xxx.ets 103@Entry 104@Component 105struct TouchExample { 106 @State text: string = '' 107 @State eventType: string = '' 108 109 build() { 110 Column() { 111 Button('Touch').height(40).width(100) 112 .onTouch((event?: TouchEvent) => { 113 if(event){ 114 if (event.type === TouchType.Down) { 115 this.eventType = 'Down' 116 } 117 if (event.type === TouchType.Up) { 118 this.eventType = 'Up' 119 } 120 if (event.type === TouchType.Move) { 121 this.eventType = 'Move' 122 } 123 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 124 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 125 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 126 + event.target.area.width + '\nheight:' + event.target.area.height + '\ntargetDisplayId:' + 127 event.targetDisplayId + '\npressedTime:' + event.touches[0].pressedTime + '\npressure:' + 128 event.touches[0].pressure + 129 '\nwidth:' + event.touches[0].width + '\nheight:' + event.touches[0].height 130 } 131 }) 132 Button('Touch').height(50).width(200).margin(20) 133 .onTouch((event?: TouchEvent) => { 134 if(event){ 135 if (event.type === TouchType.Down) { 136 this.eventType = 'Down' 137 } 138 if (event.type === TouchType.Up) { 139 this.eventType = 'Up' 140 } 141 if (event.type === TouchType.Move) { 142 this.eventType = 'Move' 143 } 144 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 145 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 146 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 147 + event.target.area.width + '\nheight:' + event.target.area.height + '\ntargetDisplayId:' + 148 event.targetDisplayId + '\npressedTime:' + event.touches[0].pressedTime + '\npressure:' + 149 event.touches[0].pressure + 150 '\nwidth:' + event.touches[0].width + '\nheight:' + event.touches[0].height 151 } 152 }) 153 Text(this.text) 154 }.width('100%').padding(30) 155 } 156} 157``` 158 159 160
