1# 触摸事件 2 3当手指在组件上按下、滑动、抬起时触发。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 事件 10 11| 名称 | 是否冒泡 | 功能描述 | 12| ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 13| onTouch(event: (event: TouchEvent) => void) | 是 | 手指触摸动作触发该回调，event返回值见[TouchEvent](#touchevent对象说明)介绍。 | 14 15 16## TouchEvent对象说明 17 18| 名称 | 类型 | 描述 | 19| ------------------- | ---------------------------------------- | ------------ | 20| type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。 | 21| touches | Array<[TouchObject](#touchobject对象说明)> | 全部手指信息。 | 22| changedTouches | Array<[TouchObject](#touchobject对象说明)> | 当前发生变化的手指信息。 | 23| stopPropagation | () => void | 阻塞事件冒泡。 | 24| timestamp<sup>8+</sup> | number | 事件时间戳，触发事件时距离系统启动的时间间隔。<br/>例如，当系统启动时间为2023/10/12 11:33, 在2023/10/12 11:34时触发触摸事件，时间戳返回的值为60,000,000,000ns。<br>单位：纳秒 | 25| target<sup>8+</sup> | [EventTarget](ts-universal-events-click.md#eventtarget8对象说明) | 触发事件的元素对象显示区域。 | 26| source<sup>8+</sup> | [SourceType](ts-gesture-settings.md#sourcetype枚举说明) | 事件输入设备。 | 27 28 29### getHistoricalPoints<sup>10+</sup> 30 31getHistoricalPoints(): Array<HistoricalPoint> 32 33获取当前帧所有的历史点。不同设备每帧的触摸事件频率不同，且该接口只能在[TouchEvent](#touchevent对象说明)中调用，可以通过该接口获取触发[onTouch](#事件)时当前帧历史点的相关信息。[onTouch](#事件)一帧只会调用一次，若当前帧收到的[TouchEvent](#touchevent对象说明)大于1，会将该帧最后一个点通过[onTouch](#事件)返还，剩余点作为历史点。 34 35**返回值:** 36 37| 类型 | 描述 | 38| ------ | ----------------------- | 39| Array<[HistoricalPoint](#historicalpoint10对象说明)> | 由历史点组成的数组。 | 40 41 42## TouchObject对象说明 43 44| 名称 | 类型 | 描述 | 45| ------- | ------------------------------------------- | ------------------------------------- | 46| type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。 | 47| id | number | 手指唯一标识符。 | 48| x | number | 触摸点相对于被触摸元素左上角的X坐标。<br/>单位：vp | 49| y | number | 触摸点相对于被触摸元素左上角的Y坐标。<br/>单位：vp | 50| windowX<sup>10+</sup> | number | 触摸点相对于应用窗口左上角的X坐标。<br/>单位：vp | 51| windowY<sup>10+</sup> | number | 触摸点相对于应用窗口左上角的Y坐标。<br/>单位：vp | 52| displayX<sup>10+</sup> | number | 触摸点相对于应用屏幕左上角的X坐标。<br/>单位：vp | 53| displayY<sup>10+</sup> | number | 触摸点相对于应用屏幕左上角的Y坐标。<br/>单位：vp | 54| screenX<sup>(deprecated)</sup> | number | 触摸点相对于应用窗口左上角的X坐标。<br/>单位：vp<br>从API version 10开始不再维护，建议使用windowX代替。 | 55| screenY<sup>(deprecated)</sup> | number | 触摸点相对于应用窗口左上角的Y坐标。<br/>单位：vp<br>从API version 10开始不再维护，建议使用windowX代替。 | 56 57## HistoricalPoint<sup>10+</sup>对象说明 58 59| 名称 | 类型 | 描述 | 60| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | 61| touchObject | [TouchObject](#touchobject对象说明) | 历史点对应触摸事件的基础信息。 | 62| size | number | 历史点对应触摸事件的手指与屏幕的触摸区域大小。<br/>默认值：0 | 63| force | number | 历史点对应触摸事件的压力大小。<br/>默认值：0<br/>取值范围：[0,1]，压力越大值越大。<br/>此接口根据硬件设备不同，支持情况不同。当前只支持Tablet。| 64| timestamp | number | 历史点对应触摸事件的时间戳。触发事件时距离系统启动的时间间隔。<br>单位：纳秒 | 65## 示例 66 67```ts 68// xxx.ets 69@Entry 70@Component 71struct TouchExample { 72 @State text: string = '' 73 @State eventType: string = '' 74 75 build() { 76 Column() { 77 Button('Touch').height(40).width(100) 78 .onTouch((event?: TouchEvent) => { 79 if(event){ 80 if (event.type === TouchType.Down) { 81 this.eventType = 'Down' 82 } 83 if (event.type === TouchType.Up) { 84 this.eventType = 'Up' 85 } 86 if (event.type === TouchType.Move) { 87 this.eventType = 'Move' 88 } 89 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 90 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 91 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 92 + event.target.area.width + '\nheight:' + event.target.area.height 93 } 94 }) 95 Button('Touch').height(50).width(200).margin(20) 96 .onTouch((event?: TouchEvent) => { 97 if(event){ 98 if (event.type === TouchType.Down) { 99 this.eventType = 'Down' 100 } 101 if (event.type === TouchType.Up) { 102 this.eventType = 'Up' 103 } 104 if (event.type === TouchType.Move) { 105 this.eventType = 'Move' 106 } 107 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 108 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 109 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 110 + event.target.area.width + '\nheight:' + event.target.area.height 111 } 112 }) 113 Text(this.text) 114 }.width('100%').padding(30) 115 } 116} 117``` 118 119 120
