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 10## Events 11 12| Name | Bubbling Supported| Description | 13| ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 14| onTouch(event: (event: TouchEvent) => void) | Yes | Invoked when a touch event is triggered. For details about **event**, see [TouchEvent](#touchevent).| 15 16 17## TouchEvent 18 19| Name | Type | Description | 20| ------------------- | ---------------------------------------- | ------------ | 21| type | [TouchType](ts-appendix-enums.md#touchtype) | Type of the touch event. | 22| touches | Array<[TouchObject](#touchobject)> | All finger information. | 23| changedTouches | Array<[TouchObject](#touchobject)> | Finger information changed.| 24| stopPropagation | () => void | Stops the event from bubbling upwards or downwards.| 25| timestamp<sup>8+</sup> | number | Timestamp of the event. It is the interval between the time when the event is triggered and the time when the system starts.<br>For example, if the system starts at 2023/10/12 11:33 and the touch event is triggered at 2023/10/12 11:34, then the returned timestamp value is 60,000,000,000 ns.<br>Unit: ns| 26| target<sup>8+</sup> | [EventTarget](ts-universal-events-click.md#eventtarget8) | Display area of the element that triggers the gesture event.| 27| source<sup>8+</sup> | [SourceType](ts-gesture-settings.md#sourcetype9)| Event input device.| 28 29 30### getHistoricalPoints<sup>10+</sup> 31 32getHistoricalPoints(): Array<HistoricalPoint> 33 34Obtains 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](#events) is invoked. [onTouch](#events) 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](#events). The remaining points are regarded as historical points. 35 36**Return value** 37 38| Type | Description | 39| ------ | ----------------------- | 40| Array<[HistoricalPoint](#historicalpoint10)>| Array of historical points.| 41 42 43## TouchObject 44 45| Name | Type | Description | 46| ------- | ------------------------------------------- | ------------------------------------- | 47| type | [TouchType](ts-appendix-enums.md#touchtype) | Type of the touch event. | 48| id | number | Unique identifier of a finger. | 49| x | number | X coordinate of the touch point relative to the upper left corner of the component being touched. <br>Unit: vp| 50| y | number | Y coordinate of the touch point relative to the upper left corner of the component being touched. <br>Unit: vp| 51| windowX<sup>10+</sup> | number | X coordinate of the touch point relative to the upper left corner of the application window. <br>Unit: vp | 52| windowY<sup>10+</sup> | number | Y coordinate of the touch point relative to the upper left corner of the application window. <br>Unit: vp | 53| displayX<sup>10+</sup> | number | X coordinate of the touch point relative to the upper left corner of the application screen. <br>Unit: vp | 54| displayY<sup>10+</sup> | number | Y coordinate of the touch point relative to the upper left corner of the application screen. <br>Unit: vp | 55| 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. | 56| 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. | 57 58## HistoricalPoint<sup>10+</sup> 59 60| Name | Type | Description | 61| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | 62| touchObject | [TouchObject](#touchobject) | Basic information of the historical point. | 63| size | number | Size of the contact area between the finger and screen for the historical point.<br>Default value: **0** | 64| force | number | Touch force of the historical point.<br>Default value: **0**<br>Value range: [0,1]. A larger value indicates a greater touch force.<br>The support for this API varies by device. Currently, it is only available on tablets.| 65| 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 | 66## Example 67 68```ts 69// xxx.ets 70@Entry 71@Component 72struct TouchExample { 73 @State text: string = '' 74 @State eventType: string = '' 75 76 build() { 77 Column() { 78 Button('Touch').height(40).width(100) 79 .onTouch((event?: TouchEvent) => { 80 if(event){ 81 if (event.type === TouchType.Down) { 82 this.eventType = 'Down' 83 } 84 if (event.type === TouchType.Up) { 85 this.eventType = 'Up' 86 } 87 if (event.type === TouchType.Move) { 88 this.eventType = 'Move' 89 } 90 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 91 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 92 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 93 + event.target.area.width + '\nheight:' + event.target.area.height 94 } 95 }) 96 Button('Touch').height(50).width(200).margin(20) 97 .onTouch((event?: TouchEvent) => { 98 if(event){ 99 if (event.type === TouchType.Down) { 100 this.eventType = 'Down' 101 } 102 if (event.type === TouchType.Up) { 103 this.eventType = 'Up' 104 } 105 if (event.type === TouchType.Move) { 106 this.eventType = 'Move' 107 } 108 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 109 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 110 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 111 + event.target.area.width + '\nheight:' + event.target.area.height 112 } 113 }) 114 Text(this.text) 115 }.width('100%').padding(30) 116 } 117} 118``` 119 120 121
