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对象说明8)。非事件注入场景下，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)返还，剩余点作为历史点。若多指在同一帧上报事件，可能存在触发多次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| PressedTime<sup>15+</sup> | number | 当前手指按下的时间。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 79| pressure<sup>15+</sup> | number | 当前手指按着的压力值。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 80| width<sup>15+</sup> | number | 当前手指按压区域的宽。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 81| height<sup>15+</sup> | number | 当前手指按压区域的高。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 82| hand<sup>15+</sup> | [InteractionHand](./ts-gesture-settings.md#interactionhand枚举说明15) | 表示事件是由左手点击还是右手点击触发。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 83 84## HistoricalPoint<sup>10+</sup>对象说明 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90| 名称 | 类型 | 描述 | 91| ----------- | ----------------------------------- | ----------------------------------------------------------------------------- | 92| touchObject | [TouchObject](#touchobject对象说明) | 历史点对应触摸事件的基础信息。 | 93| size | number | 历史点对应触摸事件的手指与屏幕的触摸区域大小。<br/>默认值：0 | 94| force | number | 历史点对应触摸事件的压力大小。<br/>默认值：0<br/>取值范围：[0,65535)，压力越大值越大。| 95| timestamp | number | 历史点对应触摸事件的时间戳。触发事件时距离系统启动的时间间隔。<br>单位：ns | 96 97## 示例 98 99该示例通过按钮设置了触摸事件，手指点击按钮时可获取触摸事件的相关参数。 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
