1# 触摸事件 2 3当手指在组件上按下、滑动、抬起时触发。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## onTouch 10 11onTouch(event: (event: TouchEvent) => void): T 12 13手指触摸动作触发该回调。 14 15**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 16 17**系统能力：** SystemCapability.ArkUI.ArkUI.Full 18 19**参数：** 20 21| 参数名 | 类型 | 必填 | 说明 | 22| ------ | --------------------------------- | ---- | -------------------- | 23| event | [TouchEvent](#touchevent对象说明) | 是 | 获得TouchEvent对象。 | 24 25**返回值：** 26 27| 类型 | 说明 | 28| -------- | -------- | 29| T | 返回当前组件。 | 30 31## TouchEvent对象说明 32 33继承于[BaseEvent](ts-gesture-customize-judge.md#baseevent对象说明)。非事件注入场景下，changedTouches是按屏幕显示刷新率重采样的点，touches是按器件刷新率报上来的点，changedTouches的数据可能会和touches里面的不相同。 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37| 名称 | 类型 | 描述 | 38| ------------------- | ---------------------------------------- | ------------ | 39| type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| touches | Array<[TouchObject](#touchobject对象说明)> | 全部手指信息。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41| changedTouches | Array<[TouchObject](#touchobject对象说明)> | 当前发生变化的手指信息。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42| stopPropagation | () => void | 阻塞事件冒泡。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| preventDefault<sup>12+</sup> | () => void | 阻止默认事件。<br/> **说明：** 该接口仅支持部分组件使用，当前支持组件：Hyperlink。暂不支持异步调用和提供Modifier接口。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 44 45### getHistoricalPoints<sup>10+</sup> 46 47getHistoricalPoints(): Array<HistoricalPoint> 48 49获取当前帧所有的历史点。不同设备每帧的触摸事件频率不同，且该接口只能在[TouchEvent](#touchevent对象说明)中调用，可以通过该接口获取触发[onTouch](#ontouch)时当前帧历史点的相关信息。[onTouch](#ontouch)一帧只会调用一次，若当前帧收到的[TouchEvent](#touchevent对象说明)大于1，会将该帧最后一个点通过[onTouch](#ontouch)返还，剩余点作为历史点。 50 51**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55**返回值:** 56 57| 类型 | 描述 | 58| ------ | ----------------------- | 59| Array<[HistoricalPoint](#historicalpoint10对象说明)> | 由历史点组成的数组。 | 60 61 62## TouchObject对象说明 63 64**系统能力：** SystemCapability.ArkUI.ArkUI.Full 65 66| 名称 | 类型 | 描述 | 67| ------- | ------------------------------------------- | ------------------------------------- | 68| type | [TouchType](ts-appendix-enums.md#touchtype) | 触摸事件的类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 69| id | number | 手指唯一标识符。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 70| x | number | 触摸点相对于事件响应组件的左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 71| y | number | 触摸点相对于事件响应组件的左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 72| windowX<sup>10+</sup> | number | 触摸点相对于应用窗口左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 73| windowY<sup>10+</sup> | number | 触摸点相对于应用窗口左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 74| displayX<sup>10+</sup> | number | 触摸点相对于应用屏幕左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 75| displayY<sup>10+</sup> | number | 触摸点相对于应用屏幕左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| screenX<sup>(deprecated)</sup> | number | 触摸点相对于应用窗口左上角的X坐标。<br/>单位：vp <br>从API version 10开始不再维护，建议使用windowX代替。 | 77| screenY<sup>(deprecated)</sup> | number | 触摸点相对于应用窗口左上角的Y坐标。<br/>单位：vp <br>从API version 10开始不再维护，建议使用windowY代替。 | 78 79## HistoricalPoint<sup>10+</sup>对象说明 80 81**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 82 83**系统能力：** SystemCapability.ArkUI.ArkUI.Full 84 85| 名称 | 类型 | 描述 | 86| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | 87| touchObject | [TouchObject](#touchobject对象说明) | 历史点对应触摸事件的基础信息。 | 88| size | number | 历史点对应触摸事件的手指与屏幕的触摸区域大小。<br/>默认值：0 | 89| force | number | 历史点对应触摸事件的压力大小。<br/>默认值：0<br/>取值范围：[0,65535)，压力越大值越大。| 90| timestamp | number | 历史点对应触摸事件的时间戳。触发事件时距离系统启动的时间间隔。<br>单位：ns | 91## 示例 92 93该示例通过按钮设置了触摸事件，手指点击按钮时可获取触摸事件的相关参数。 94 95```ts 96// xxx.ets 97@Entry 98@Component 99struct TouchExample { 100 @State text: string = '' 101 @State eventType: string = '' 102 103 build() { 104 Column() { 105 Button('Touch').height(40).width(100) 106 .onTouch((event?: TouchEvent) => { 107 if(event){ 108 if (event.type === TouchType.Down) { 109 this.eventType = 'Down' 110 } 111 if (event.type === TouchType.Up) { 112 this.eventType = 'Up' 113 } 114 if (event.type === TouchType.Move) { 115 this.eventType = 'Move' 116 } 117 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 118 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 119 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 120 + event.target.area.width + '\nheight:' + event.target.area.height 121 } 122 }) 123 Button('Touch').height(50).width(200).margin(20) 124 .onTouch((event?: TouchEvent) => { 125 if(event){ 126 if (event.type === TouchType.Down) { 127 this.eventType = 'Down' 128 } 129 if (event.type === TouchType.Up) { 130 this.eventType = 'Up' 131 } 132 if (event.type === TouchType.Move) { 133 this.eventType = 'Move' 134 } 135 this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: ' 136 + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:(' 137 + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:' 138 + event.target.area.width + '\nheight:' + event.target.area.height 139 } 140 }) 141 Text(this.text) 142 }.width('100%').padding(30) 143 } 144} 145``` 146 147 148
