1# 触摸事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9由手指在组件上按下、滑动或抬起时触发。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 事件分发可参考[事件交互流程](../../../ui/arkts-interaction-basic-principles.md#事件交互流程)，手势事件处理流程可参考[多层级手势事件](../../../ui/arkts-gesture-events-multi-level-gesture.md)。 16> 17> 如需绑定手势事件可参考[绑定手势方法](./ts-gesture-settings.md)。 18 19## onTouch 20 21onTouch(event: (event: TouchEvent) => void): T 22 23手指触摸动作触发该回调。触摸事件默认[冒泡](../../../ui/arkts-interaction-basic-principles.md#事件冒泡)，会被多个组件消费，如果需阻止冒泡，可参考[TouchEvent](#touchevent对象说明)的stopPropagation方法。鼠标左键按下时，对应的事件也会转换成触摸事件并触发该回调。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------ | --------------------------------- | ---- | -------------------- | 33| event | [TouchEvent](#touchevent对象说明) | 是 | 获得TouchEvent对象。 | 34 35**返回值：** 36 37| 类型 | 说明 | 38| -------- | -------- | 39| T | 返回当前组件。 | 40 41## TouchEvent对象说明 42 43继承于[BaseEvent](ts-gesture-customize-judge.md#baseevent8)。在非事件注入场景下，changedTouches是按屏幕刷新率重采样的点，而touches是按器件刷新率上报的点，因此changedTouches与touches的数据可能不同。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ------------------- | -----------|------|-------- | -------------------------- | 49| type | [TouchType](ts-appendix-enums.md#touchtype) | 否 | 否 | 触摸事件的类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| touches | <[TouchObject](#touchobject)>[] | 否 | 否 | 全部屏幕触点（多指）的信息，每个元素代表一个触点。在使用该属性时，需要校验是否为空。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| changedTouches | <[TouchObject](#touchobject)>[] | 否 | 否 | 发生变化而产生事件的手指信息。在使用该属性时，需要校验是否为空。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 52| stopPropagation | () => void | 否 | 否 | 阻塞[事件冒泡](../../../ui/arkts-interaction-basic-principles.md#事件冒泡)。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53| preventDefault<sup>12+</sup> | () => void | 否 | 否 | 阻止默认事件。<br/> **说明：** 该接口仅支持部分组件使用，当前支持组件：Hyperlink，不支持的组件在使用时会抛出异常。暂不支持异步调用和提供Modifier接口。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 54 55**错误码：** 56 57以下错误码的详细介绍请参见[交互事件错误码](../errorcode-event.md)。 58 59| 错误码ID | 错误信息 | 60| --------- | ------- | 61| 100017 | Component does not support prevent function. | 62 63### getHistoricalPoints<sup>10+</sup> 64 65getHistoricalPoints(): Array<HistoricalPoint> 66 67获取当前帧的所有历史点。不同设备每帧的触摸事件频率不同，且该接口仅能在[TouchEvent](#touchevent对象说明)中调用，用于获取触发[onTouch](#ontouch)时当前帧历史点的相关信息。[onTouch](#ontouch)一帧通常只会调用一次，如果当前帧收到的[TouchEvent](#touchevent对象说明)数目大于1，会将该帧最后一个点通过[onTouch](#ontouch)返还，其余点作为历史点。如果多指在同一帧上报事件，可能触发多次onTouch。 68 69**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 70 71**系统能力：** SystemCapability.ArkUI.ArkUI.Full 72 73**返回值：** 74 75| 类型 | 说明 | 76| ------ | ----------------------- | 77| Array<[HistoricalPoint](#historicalpoint10对象说明)> | 由历史点组成的数组。 | 78 79 80## TouchObject 81 82**系统能力：** SystemCapability.ArkUI.ArkUI.Full 83 84| 名称 | 类型 | 只读 | 可选 | 说明 | 85| ------- | ----------------------------------|-----| -------------- | ------------------------------------- | 86| type | [TouchType](ts-appendix-enums.md#touchtype) | 否 | 否 | 触摸事件的类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 87| id | number | 否 | 否 | 手指唯一标识符。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 88| x | number | 否 | 否 | 触摸点相对于事件响应组件左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 89| y | number | 否 | 否 | 触摸点相对于事件响应组件左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 90| windowX<sup>10+</sup> | number | 否 | 否 | 触摸点相对于应用窗口左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 91| windowY<sup>10+</sup> | number | 否 | 否 | 触摸点相对于应用窗口左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 92| displayX<sup>10+</sup> | number | 否 | 否 | 触摸点相对于应用屏幕左上角的X坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 93| displayY<sup>10+</sup> | number | 否 | 否 | 触摸点相对于应用屏幕左上角的Y坐标。<br/>单位：vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 94| screenX<sup>(deprecated)</sup> | number | 否 | 否 | 触摸点相对于应用窗口左上角的X坐标。<br/>单位：vp <br>从API version 10开始不再维护，建议使用windowX代替。 | 95| screenY<sup>(deprecated)</sup> | number | 否 | 否 | 触摸点相对于应用窗口左上角的Y坐标。<br/>单位：vp <br>从API version 10开始不再维护，建议使用windowY代替。 | 96| pressedTime<sup>15+</sup> | number | 否 | 是 | 当前手指按下的时间。<br>单位：ns<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 97| pressure<sup>15+</sup> | number | 否 | 是 | 当前手指按压的压力值。<br/>取值范围：[0,65535)，压力越大，值越大。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 98| width<sup>15+</sup> | number | 否 | 是 | 当前手指按压区域的宽度。<br />单位：vp<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 99| height<sup>15+</sup> | number | 否 | 是 | 当前手指按压区域的高度。<br />单位：vp<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 100| hand<sup>15+</sup> | [InteractionHand](./ts-appendix-enums.md#interactionhand15) | 否 | 是 | 表示事件是由左手点击还是右手点击触发。<br />**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 101| globalDisplayX<sup>20+</sup> | number | 否 | 是 | 触摸点位置相对于全局屏幕左上角的X坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 102| globalDisplayY<sup>20+</sup> | number | 否 | 是 | 触摸点位置相对于全局屏幕左上角的Y坐标。<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 103 104## HistoricalPoint<sup>10+</sup>对象说明 105 106历史点信息。 107 108**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112| 名称 | 类型 | 只读 | 可选 | 说明 | 113| ----------- | -----------------------------|------ | ----------|------------------------------------------------------------------- | 114| touchObject | [TouchObject](#touchobject) | 否 | 否 | 历史点对应触摸事件的基础信息。 | 115| size | number | 否 | 否 | 历史点对应触摸事件中手指与屏幕的触摸区域大小。<br/>默认值：0 | 116| force | number | 否 | 否 | 历史点对应触摸事件的压力大小。<br/>默认值：0<br/>取值范围：[0,65535)，压力越大，值越大。| 117| timestamp | number | 否 | 否 | 历史点对应触摸事件的时间戳，表示触发事件时距离系统启动的时间间隔。<br>单位：ns | 118 119## 示例 120 121该示例中，按钮设置触摸事件，在点击按钮时可获取事件的相关参数。 122 123```ts 124// xxx.ets 125@Entry 126@Component 127struct TouchExample { 128 @State text: string = ''; 129 @State eventType: string = ''; 130 131 build() { 132 Column() { 133 Button('Touch').height(40).width(100) 134 .onTouch((event?: TouchEvent) => { 135 if (event && event.sourceTool === SourceTool.Finger) { 136 if (event.type === TouchType.Down) { 137 this.eventType = 'Down'; 138 } 139 if (event.type === TouchType.Up) { 140 this.eventType = 'Up'; 141 } 142 if (event.type === TouchType.Move) { 143 this.eventType = 'Move'; 144 } 145 // 1.手指按住屏幕同时点击Home键返回桌面，此时会触发Cancel 146 // 2.折叠屏手机，应用在按住屏幕的情况下折叠手机切换到外屏，此时会触发Cancel 147 if (event.type === TouchType.Cancel) { 148 this.eventType = 'Cancel'; 149 } 150 if (event.touches) { 151 this.text = 'TouchType:' + this.eventType 152 + '\nDistance between touch point and touch element:' 153 + '\n x: ' + event.touches[0].x + '\n y: ' + event.touches[0].y 154 + '\n width: ' + event.touches[0].width + '\n height: ' + event.touches[0].height 155 + '\n pressedTime: ' + event.touches[0].pressedTime 156 + '\n pressure: ' + event.touches[0].pressure 157 + '\nComponent globalPos:' 158 + '\n x: ' + event.target.area.globalPosition.x + '\n y: ' + event.target.area.globalPosition.y 159 + '\n width: ' + event.target.area.width + '\n height: ' + event.target.area.height 160 + '\ntargetDisplayId: ' + event.targetDisplayId; 161 } 162 } 163 }) 164 Button('Touch').height(50).width(200).margin(20) 165 .onTouch((event?: TouchEvent) => { 166 if (event) { 167 if (event.type === TouchType.Down) { 168 this.eventType = 'Down'; 169 } 170 if (event.type === TouchType.Up) { 171 this.eventType = 'Up'; 172 } 173 if (event.type === TouchType.Move) { 174 this.eventType = 'Move'; 175 } 176 // 1.手指按住屏幕同时点击Home键返回桌面，此时会触发Cancel 177 // 2.折叠屏手机，应用在按住屏幕的情况下折叠手机切换到外屏，此时会触发Cancel 178 if (event.type === TouchType.Cancel) { 179 this.eventType = 'Cancel'; 180 } 181 if (event.touches) { 182 this.text = 'TouchType:' + this.eventType 183 + '\nDistance between touch point and touch element:' 184 + '\n x: ' + event.touches[0].x + '\n y: ' + event.touches[0].y 185 + '\n width: ' + event.touches[0].width + '\n height: ' + event.touches[0].height 186 + '\n pressedTime: ' + event.touches[0].pressedTime 187 + '\n pressure: ' + event.touches[0].pressure 188 + '\nComponent globalPos:' 189 + '\n x: ' + event.target.area.globalPosition.x + '\n y: ' + event.target.area.globalPosition.y 190 + '\n width: ' + event.target.area.width + '\n height: ' + event.target.area.height 191 + '\ntargetDisplayId: ' + event.targetDisplayId; 192 } 193 } 194 }) 195 Text(this.text) 196 }.width('100%').padding(30) 197 } 198} 199``` 200 201
