Touch Event
A touch event is triggered when a finger is pressed against, swipes on, or is lifted from a component.
NOTE
This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
onTouch
onTouch(event: (event: TouchEvent) => void): T
Invoked when a touch event is triggered.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| event | TouchEvent | Yes | TouchEvent object. |
Return value
| Type | Description |
|---|---|
| T | Current component. |
TouchEvent
Inherits from BaseEvent. 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.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Description |
|---|---|---|
| type | TouchType | Type of the touch event. Atomic service API: This API can be used in atomic services since API version 11. |
| touches | Array<TouchObject> | All finger information. Atomic service API: This API can be used in atomic services since API version 11. |
| changedTouches | Array<TouchObject> | Finger information changed. Atomic service API: This API can be used in atomic services since API version 11. |
| stopPropagation | () => void | Stops the event from bubbling upwards or downwards. Atomic service API: This API can be used in atomic services since API version 11. |
| preventDefault12+ | () => void | Blocks the default event. NOTE This API is only supported by the following components: Hyperlink. Asynchronous calls and the Modifier API are not yet supported. Atomic service API: This API can be used in atomic services since API version 12. |
getHistoricalPoints10+
getHistoricalPoints(): Array<HistoricalPoint>
Obtains 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. You can use this API to obtain the historical points of the current frame when onTouch is invoked. onTouch is invoked only once for a frame. If the value of TouchEvent received by the current frame is greater than 1, the last point of the frame is returned through onTouch. The remaining points are regarded as historical points.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| Array<HistoricalPoint> | Array of historical points. |
TouchObject
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Description |
|---|---|---|
| type | TouchType | Type of the touch event. Atomic service API: This API can be used in atomic services since API version 11. |
| id | number | Unique identifier of a finger. Atomic service API: This API can be used in atomic services since API version 11. |
| x | number | X coordinate of the touch point relative to the upper left corner of the event responding component. Unit: vp Atomic service API: This API can be used in atomic services since API version 11. |
| y | number | Y coordinate of the touch point relative to the upper left corner of the event responding component. Unit: vp Atomic service API: This API can be used in atomic services since API version 11. |
| windowX10+ | number | X coordinate of the touch point relative to the upper left corner of the application window. Unit: vp Atomic service API: This API can be used in atomic services since API version 11. |
| windowY10+ | number | Y coordinate of the touch point relative to the upper left corner of the application window. Unit: vp Atomic service API: This API can be used in atomic services since API version 11. |
| displayX10+ | number | X coordinate of the touch point relative to the upper left corner of the application screen. Unit: vp Atomic service API: This API can be used in atomic services since API version 11. |
| displayY10+ | number | Y coordinate of the touch point relative to the upper left corner of the application screen. Unit: vp Atomic service API: This API can be used in atomic services since API version 11. |
| screenX(deprecated) | number | X coordinate of the touch point relative to the upper left corner of the application window. Unit: vp This API is deprecated since API version 10. You are advised to use windowX instead. |
| screenY(deprecated) | number | Y coordinate of the touch point relative to the upper left corner of the application window. Unit: vp This API is deprecated since API version 10. You are advised to use windowY instead. |
| PressedTime15+ | number | Time when the finger is pressed. Atomic service API: This API can be used in atomic services since API version 15. |
| pressure15+ | number | Pressure value of the finger press. Atomic service API: This API can be used in atomic services since API version 15. |
| width15+ | number | Width of the area pressed by the finger. Atomic service API: This API can be used in atomic services since API version 15. |
| height15+ | number | Height of the area pressed by the finger. Atomic service API: This API can be used in atomic services since API version 15. |
| hand15+ | InteractionHand | Whether the event is triggered by a left-hand or right-hand tap. Atomic service API: This API can be used in atomic services since API version 15. |
HistoricalPoint10+
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Description |
|---|---|---|
| touchObject | TouchObject | Basic information of the historical point. |
| size | number | Size of the contact area between the finger and screen for the historical point. Default value: 0 |
| force | number | Touch force of the historical point. Default value: 0 Value range: [0, 65535). The greater the pressure, the larger the value. |
| 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. Unit: ns |
Example
This example configures a touch event for a button. When the button is touched, it obtains relevant parameters of the touch event.
// xxx.ets
@Entry
@Component
struct TouchExample {
@State text: string = ''
@State eventType: string = ''
build() {
Column() {
Button('Touch').height(40).width(100)
.onTouch((event?: TouchEvent) => {
if(event){
if (event.type === TouchType.Down) {
this.eventType = 'Down'
}
if (event.type === TouchType.Up) {
this.eventType = 'Up'
}
if (event.type === TouchType.Move) {
this.eventType = 'Move'
}
this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
+ event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
+ event.target.area.width + '\nheight:' + event.target.area.height + '\ntargetDisplayId:' +
event.targetDisplayId + '\npressedTime:' + event.touches[0].pressedTime + '\npressure:' +
event.touches[0].pressure +
'\nwidth:' + event.touches[0].width + '\nheight:' + event.touches[0].height
}
})
Button('Touch').height(50).width(200).margin(20)
.onTouch((event?: TouchEvent) => {
if(event){
if (event.type === TouchType.Down) {
this.eventType = 'Down'
}
if (event.type === TouchType.Up) {
this.eventType = 'Up'
}
if (event.type === TouchType.Move) {
this.eventType = 'Move'
}
this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
+ event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
+ event.target.area.width + '\nheight:' + event.target.area.height + '\ntargetDisplayId:' +
event.targetDisplayId + '\npressedTime:' + event.touches[0].pressedTime + '\npressure:' +
event.touches[0].pressure +
'\nwidth:' + event.touches[0].width + '\nheight:' + event.touches[0].height
}
})
Text(this.text)
}.width('100%').padding(30)
}
}
