1# 通用事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9> **说明：** 10> 从API version 4开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 11 12## 事件说明 13 14- 事件绑定在组件上，当组件达到事件触发条件时，会执行JS中对应的事件回调函数，实现页面UI视图和页面JS逻辑层的交互。 15 16- 事件回调函数中通过参数可以携带额外的信息，如组件上的数据对象dataset，事件特有的回调参数。 17 18 19相对于私有事件，大部分组件都可以绑定如下事件。 20 21 22| 名称 | 参数 | 描述 | 是否支持冒泡 | 是否支持捕获 | 23| ------------------------ | ---------- | ------------------------------------------------------------ | ----------------------------------------------------- | --------------- | 24| touchstart | TouchEvent | 手指刚触摸屏幕时触发该事件。TouchEvent具体可参考表2。 | 是<sup>5+</sup> | 是<sup>5+</sup> | 25| touchmove | TouchEvent | 手指触摸屏幕后移动时触发该事件。 | 是<sup>5+</sup> | 是<sup>5+</sup> | 26| touchcancel | TouchEvent | 手指触摸屏幕中动作被打断时触发该事件。 | 是<sup>5+</sup> | 是<sup>5+</sup> | 27| touchend | TouchEvent | 手指触摸结束离开屏幕时触发该事件。 | 是<sup>5+</sup> | 是<sup>5+</sup> | 28| click | BaseEvent | 点击动作触发该事件。 | 是<sup>6+</sup> | 否 | 29| doubleclick<sup>7+</sup> | BaseEvent | 双击动作触发该事件 | 否<br/> 从API Version 9 开始支持冒泡。 | 否 | 30| longpress | BaseEvent | 长按动作触发该事件。 | 否<br/>从API Version 9 开始支持冒泡。 | 否 | 31| swipe<sup>5+</sup> | SwipeEvent | 组件上快速滑动后触发该事件。 SwipeEvent具体可参考表4 。 | 否<br/>从API Version 9 开始支持冒泡。 | 否 | 32| attached<sup>6+</sup> | - | 当前组件节点挂载在渲染树后触发。 | 否 | 否 | 33| detached<sup>6+</sup> | - | 当前组件节点从渲染树中移除后触发。 | 否 | 否 | 34| pinchstart<sup>7+</sup> | PinchEvent | 手指开始执行捏合操作时触发该事件。<br/>PinchEvent具体可参考表5。 | 否 | 否 | 35| pinchupdate<sup>7+</sup> | PinchEvent | 手指执行捏合操作过程中触发该事件。 | 否 | 否 | 36| pinchend<sup>7+</sup> | PinchEvent | 手指捏合操作结束离开屏幕时触发该事件。 | 否 | 否 | 37| pinchcancel<sup>7+</sup> | PinchEvent | 手指捏合操作被打断时触发该事件。 | 否 | 否 | 38| dragstart<sup>7+</sup> | DragEvent | 用户开始拖拽时触发该事件。<br/>DragEvent具体可参考表6。 | 否 | 否 | 39| drag<sup>7+</sup> | DragEvent | 拖拽过程中触发该事件。 | 否 | 否 | 40| dragend<sup>7+</sup> | DragEvent | 用户拖拽完成后触发。 | 否 | 否 | 41| dragenter<sup>7+</sup> | DragEvent | 进入释放目标时触发该事件。 | 否 | 否 | 42| dragover<sup>7+</sup> | DragEvent | 在释放目标内拖动时触发。 | 否 | 否 | 43| dragleave<sup>7+</sup> | DragEvent | 离开释放目标区域时触发。 | 否 | 否 | 44| drop<sup>7+</sup> | DragEvent | 在可释放目标区域内释放时触发。 | 否 | 否 | 45 46 47> **说明：** 48> 除上述事件外，其他事件均为非冒泡事件，如[input的change事件](js-components-basic-input.md#事件)，详见各个组件。 49 50**表1** BaseEvent对象属性列表 51 52| 属性 | 类型 | 说明 | 53| --------------------- | ---------------------- | ---------------------------------------- | 54| type | string | 当前事件的类型，比如click、longpress等。 | 55| timestamp | number | 该事件触发时的时间戳。 | 56| deviceId<sup>8+</sup> | number | 触发该事件的设备ID信息。 | 57| target<sup>12+</sup> | [Target](#target对象6) | 触发该事件的目标对象。 | 58 59**表2** TouchEvent对象属性列表(继承BaseEvent) 60 61| 属性 | 类型 | 说明 | 62| -------------- | ---------------------- | ---------------------------------------- | 63| touches | Array<TouchInfo> | 触摸事件时的属性集合，包含屏幕触摸点的信息数组。 | 64| changedTouches | Array<TouchInfo> | 触摸事件时的属性集合，包括产生变化的屏幕触摸点的信息数组。数据格式和touches一样。该属性表示有变化的触摸点，如从无变有，位置变化，从有变无。例如用户手指刚接触屏幕时，touches数组中有数据，但changedTouches无数据。 | 65 66**表3** TouchInfo 67 68| 属性 | 类型 | 说明 | 69| ------------------ | ------ | ------------------------------ | 70| globalX | number | 距离屏幕左上角（不包括状态栏）横向距离。屏幕的左上角为原点。 | 71| globalY | number | 距离屏幕左上角（不包括状态栏）纵向距离。屏幕的左上角为原点。 | 72| localX | number | 距离被触摸组件左上角横向距离。组件的左上角为原点。 | 73| localY | number | 距离被触摸组件左上角纵向距离。组件的左上角为原点。 | 74| size | number | 触摸接触面积。 | 75| force<sup>6+</sup> | number | 接触力信息。 | 76 77**表4** SwipeEvent 基础事件对象属性列表（继承BaseEvent） 78 79| 属性 | 类型 | 说明 | 80| --------------------- | ------ | ---------------------------------------- | 81| direction | string | 滑动方向，可能值有：<br/>- left：向左滑动；<br/>- right：向右滑动；<br/>- up：向上滑动；<br/>- down：向下滑动。 | 82| distance<sup>6+</sup> | number | 在滑动方向上的滑动距离。 | 83 84**表5** PinchEvent 对象属性列表<sup>7+</sup> 85 86| 属性 | 类型 | 说明 | 87| ------------ | ------ | -------------- | 88| scale | number | 缩放比例。 | 89| pinchCenterX | number | 捏合中心点X轴坐标，单位px。 | 90| pinchCenterY | number | 捏合中心点Y轴坐标，单位px。 | 91 92**表6** DragEvent对象属性列表(继承BaseEvent)<sup>7+</sup> 93 94| 属性 | 类型 | 说明 | 95| ------------------------- | -------------------------------- | ---------------- | 96| type | string | 事件名称。 | 97| globalX | number | 距离屏幕左上角坐标原点横向距离。 | 98| globalY | number | 距离屏幕左上角坐标原点纵向距离。 | 99| timestamp | number | 时间戳。 | 100| dataTransfer<sup>9+</sup> | [DataTransfer](#datatransfer对象9) | 用于传输数据。 | 101 102## Target对象<sup>6+</sup> 103 104当组件触发事件后，事件回调函数默认会收到一个事件对象，通过该事件对象可以获取相应的信息。 105 106 107 108| 属性 | 类型 | 说明 | 109| -------------------- | ------ | ---------------------------------------- | 110| dataSet<sup>6+</sup> | Object | 组件上通过通用属性设置的[data-*](js-components-common-attributes.md)的自定义属性组成的集合。 | 111 112**示例：** 113 114```html 115<!-- xxx.hml --> 116<div> 117 <div data-a="dataA" data-b="dataB" 118 style="width: 100%; height: 50%; background-color: saddlebrown;"@touchstart='touchstartfunc'></div> 119</div> 120``` 121 122```js 123// xxx.js 124export default { 125 touchstartfunc(msg) { 126 console.info(`on touch start, point is: ${msg.touches[0].globalX}`); 127 console.info(`on touch start, data is: ${msg.target.dataSet.a}`); 128 } 129} 130``` 131 132## DataTransfer对象<sup>9+</sup> 133 134在拖拽操作的过程中，可以通过dataTransfer对象来传输数据，以便在拖拽操作结束的时候对数据进行其他操作。 135 136### setData<sup>9+</sup> 137 138setData(key: string, value: object): boolean 139 140设置给定key关联的数据。如果没有与该key关联的数据，则将其添加到末尾。如果该key关联的数据已经存在，则在相同位置替换现有数据。 141 142**参数：** 143 144| 参数名 | 参数类型 | 必填 | 描述 | 145| ----- | ------ | ---- | ------- | 146| key | string | 是 | 数据键值。 | 147| value | object | 是 | 要存储的数据。 | 148 149**返回值：** 150 151| 类型 | 说明 | 152| ------- | ------------------------ | 153| boolean | 执行结果，true表示成功，false表示失败。 | 154 155**示例：** 156 157```js 158// setData的value参数，可以是基本数据类型。 159dragStart(e) { 160 var isSetOK = e.dataTransfer.setData('name', 1); 161}, 162// setData的value参数，也可以是对象类型。 163dragStart(e) { 164 var person = new Object(); 165 person.name = "tom"; 166 person.age = 21; 167 var isSetOK = e.dataTransfer.setData('person', person); 168} 169``` 170### getData<sup>9+</sup> 171 172getData(key: string): object 173 174获取给定key关联的数据，如果没有与该key关联的数据，则返回空字符串。 175 176**参数：** 177 178| 参数名 | 参数类型 | 必填 | 描述 | 179| ---- | ------ | ---- | ----- | 180| key | string | 是 | 数据键值。 | 181 182**返回值：** 183 184| 类型 | 说明 | 185| ------ | ------ | 186| object | 获取的数据。 | 187 188**示例：** 189 190```js 191dragStart(e) { 192 var person = new Object(); 193 person.name = "tom"; 194 person.age = 21; 195 e.dataTransfer.setData('person', person); 196}, 197dragEnd(e){ 198 var person = e.dataTransfer.getData('person'); 199}, 200``` 201### clearData<sup>9+</sup> 202 203clearData(key?: string): boolean 204 205删除给定key关联的数据。如果没有与该key关联的数据，则该方法不会产生任何效果。 206如果key为空，则删除所有数据。 207 208**参数：** 209 210| 参数名 | 参数类型 | 必填 | 描述 | 211| ---- | ------ | ---- | ----- | 212| key | string | 否 | 数据键值。 | 213 214**返回值：** 215 216| 类型 | 说明 | 217| ------- | ------------------------ | 218| boolean | 执行结果，true表示成功，false表示失败。 | 219 220**示例：** 221 222```js 223dragEnd(e) { 224 var isSuccess = e.dataTransfer.clearData('name'); 225} 226``` 227### setDragImage<sup>9+</sup> 228 229setDragImage(pixelMap: PixelMap, offsetX: number,offsetY: number): boolean 230 231用于设置自定义的拖动图像。 232 233**参数：** 234 235| 参数名 | 参数类型 | 必填 | 描述 | 236| -------- | -------- | ---- | ---------------------------------------- | 237| pixelMap | [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 前端传入的图片资源。 | 238| offsetX | number | 是 | 相对于图片的横向偏移量。 | 239| offsetY | number | 是 | 相对于图片的纵向偏移量。 | 240 241**返回值：** 242 243| 类型 | 说明 | 244| ---- | ------------------------ | 245| boolean | 执行结果，true表示成功，false表示失败。 | 246 247**示例：** 248 249```js 250import image from '@ohos.multimedia.image'; 251 252export default { 253 createPixelMap() { 254 let color = new ArrayBuffer(4 * 96 * 96); 255 var buffer = new Uint8Array(color); 256 for (var i = 0; i < buffer.length; i++) { 257 buffer[i] = (i + 1) % 255; 258 } 259 let opts = { 260 alphaType: 0, 261 editable: true, 262 pixelFormat: 4, 263 scaleMode: 1, 264 size: { 265 height: 96, width: 96 266 } 267 } 268 const promise = image.createPixelMap(color, opts); 269 promise.then((data) => { 270 console.error('-create pixelMap has info message:' + JSON.stringify(data)); 271 this.pixelMap = data; 272 this.pixelMapReader = data; 273 }) 274 }, 275 276 onInit() { 277 this.createPixelMap() 278 }, 279 280 dragStart(e) { 281 e.dataTransfer.setDragImage(this.pixelMapReader, 50, 50); 282 } 283} 284```