js-components-common-events.md 14.2 KB
Newer Older
E
ester.zhou 已提交
1
# Universal Events
Z
zengyawen 已提交
2

E
ester.zhou 已提交
3 4
>  **NOTE**
>
5
>  Universal events are supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
E
ester.zhou 已提交
6 7 8 9 10 11

## Event Description

- Events are bound to components. When a component meets the event triggering condition, the corresponding event callback in the JS is executed to implement the interaction between the UI and the JS logic layer of the page.

- The event callback can carry additional information through parameters, such as the dataset on the component and event-specific callback parameters.
Z
zengyawen 已提交
12 13 14 15


Different from private events, universal events can be bound to most components.

E
ester.zhou 已提交
16

E
ester.zhou 已提交
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
| Name                    | Parameter      | Description                                                        | Bubbling Supported                                         | Capturing Supported   |
| ------------------------ | ---------- | ------------------------------------------------------------ | ----------------------------------------------------- | --------------- |
| touchstart               | TouchEvent | Triggered when the tapping starts. For details about **TouchEvent**, see Table 2.      | Yes<sup>5+</sup>                                      | Yes<sup>5+</sup>|
| touchmove                | TouchEvent | Triggered when the tapping moves.                            | Yes<sup>5+</sup>                                      | Yes<sup>5+</sup>|
| touchcancel              | TouchEvent | Triggered when the tapping is interrupted.                      | Yes<sup>5+</sup>                                      | Yes<sup>5+</sup>|
| touchend                 | TouchEvent | Triggered when the tapping ends.                          | Yes<sup>5+</sup>                                      | Yes<sup>5+</sup>|
| click                    | -          | Triggered when a component is clicked.                                        | Yes<sup>6+</sup>                                      | No             |
| doubleclick<sup>7+</sup> | -          | Triggered when a component is double-clicked.                                          | No<br>Bubbling is supported since API version 9. | No             |
| longpress                | -          | Triggered when a component is long pressed.                                        | No<br>Bubbling is supported since API version 9. | No             |
| swipe<sup>5+</sup>       | SwipeEvent | Triggered when a user quickly swipes on a component. For details about **SwipeEvent**, see Table 4.     | No<br>Bubbling is supported since API version 9. | No             |
| attached<sup>6+</sup>    | -          | Triggered after the current component node is mounted to the render tree.                            | No                                                   | No             |
| detached<sup>6+</sup>    | -          | Triggered when the current component node is removed from the render tree.                          | No                                                   | No             |
| pinchstart<sup>7+</sup>  | PinchEvent | Triggered when a pinch operation is started.<br>For details about **PinchEvent**, see Table 5.| No                                                   | No             |
| pinchupdate<sup>7+</sup> | PinchEvent | Triggered when a pinch operation is in progress.                          | No                                                   | No             |
| pinchend<sup>7+</sup>    | PinchEvent | Triggered when a pinch operation is ended.                      | No                                                   | No             |
| pinchcancel<sup>7+</sup> | PinchEvent | Triggered when a pinch operation is interrupted.                            | No                                                   | No             |
| dragstart<sup>7+</sup>   | DragEvent  | Triggered when dragging starts.<br>For details about **DragEvent**, see Table 6.     | No                                                   | No             |
| drag<sup>7+</sup>        | DragEvent  | Triggered when dragging is in progress.                                      | No                                                   | No             |
| dragend<sup>7+</sup>     | DragEvent  | Triggered when dragging is ended.                                        | No                                                   | No             |
| dragenter<sup>7+</sup>   | DragEvent  | Triggered when the dragged component enters a drop target.                                  | No                                                   | No             |
| dragover<sup>7+</sup>    | DragEvent  | Triggered when the dragged component is being dragged over a drop target.                                    | No                                                   | No             |
| dragleave<sup>7+</sup>   | DragEvent  | Triggered when the dragged component leaves a drop target.                                    | No                                                   | No             |
| drop<sup>7+</sup>        | DragEvent  | Triggered when the dragged component is dropped on a drop target.                              | No                                                   | No             |


>  **NOTE**
>
44
>  Events not listed in the preceding table do not support bubbling, such as the [change event](../arkui-js/js-components-basic-input.md#events) of the **<input\>** component. For details, see the description of the specific component.
E
ester.zhou 已提交
45 46 47

**Table 1** BaseEvent

48 49 50 51 52 53
| Attribute                   | Type                  | Description                          |
| --------------------- | -------------------- | --------------------------- |
| type                  | string               | Event type, such as **click** and **longpress**.|
| timestamp             | number               | Timestamp when the event is triggered.                |
| deviceId<sup>6+</sup> | number               | ID of the device that triggers the event.              |
| target<sup>6+</sup>   | [Target](#target6)| Target object that triggers the event.                |
E
ester.zhou 已提交
54 55 56 57 58 59

**Table 2** TouchEvent (inherited from BaseEvent)

| Attribute            | Type                    | Description                                       |
| -------------- | ---------------------- | ---------------------------------------- |
| touches        | Array&lt;TouchInfo&gt; | Attribute set of the touch event, including the information array of the touch points on the screen.                |
60
| changedTouches | Array&lt;TouchInfo&gt; | Attribute set when a touch event occurs, including the information array of changed touch points on the screen. **changedTouches** has the same data format as **touches** and indicates touch point changes, including changes in the number and location of touch points. For example, when the user's finger leaves the screen, which means that the number of touch points changes from 1 to 0, **changedTouches** has the relevant data generated, but not **touches**.|
E
ester.zhou 已提交
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76

**Table 3** TouchInfo

| Attribute                | Type    | Description                            |
| ------------------ | ------ | ------------------------------ |
| globalX            | number | Horizontal distance from the upper left corner of the screen (excluding the status bar), which acts as the origin of coordinates.|
| globalY            | number | Vertical distance from the upper left corner of the screen (excluding the status bar), which acts as the origin of coordinates.|
| localX             | number | Horizontal distance from the upper left corner of the touched component, which acts as the origin of coordinates.     |
| localY             | number | Vertical distance from the upper left corner of the touched component, which acts as the origin of coordinates.     |
| size               | number | Touch area.                       |
| force<sup>6+</sup> | number | Touch force.                        |

**Table 4** SwipeEvent (inherited from BaseEvent)

| Attribute                   | Type    | Description                                      |
| --------------------- | ------ | ---------------------------------------- |
77
| direction             | string | Swiping direction. The value can be one of the following:<br>- **left**: Swipe left.<br>- **right**: Swipe right.<br>- **up**: Swipe up.<br>- **down**: Swipe down.|
E
ester.zhou 已提交
78 79 80 81 82 83 84 85 86 87 88 89
| distance<sup>6+</sup> | number | Swiping distance in the swiping direction.                            |

**Table 5** PinchEvent<sup>7+</sup>

| Attribute          | Type    | Description            |
| ------------ | ------ | -------------- |
| scale        | number | Scale factor.          |
| pinchCenterX | number | X-coordinate of the pinch center, in px.|
| pinchCenterY | number | Y-coordinate of the pinch center, in px.|

**Table 6** DragEvent<sup>7+</sup> (inherited from BaseEvent)

90 91 92 93 94 95 96
| Attribute                       | Type                              | Description               |
| ------------------------- | -------------------------------- | ---------------- |
| type                      | string                           | Event name.           |
| globalX                   | number                           | Horizontal distance from the upper left corner of the screen, which acts as the origin of coordinates.|
| globalY                   | number                           | Vertical distance from the upper left corner of the screen, which acts as the origin of coordinates.|
| timestamp                 | number                           | Timestamp.            |
| dataTransfer<sup>9+</sup> | [DataTransfer](#datatransfer9)| Object for data transfer.         |
E
ester.zhou 已提交
97

98
## Target<sup>6+</sup>
Z
zengyawen 已提交
99 100 101

When a component triggers an event, the event callback receives an event object by default. You can obtain the corresponding information through the event object.

E
ester.zhou 已提交
102 103 104 105 106
| Attribute                  | Type    | Description                                      |
| -------------------- | ------ | ---------------------------------------- |
| dataSet<sup>6+</sup> | Object | Custom attribute set defined through [data-*](../arkui-js/js-components-common-attributes.md).|

**Example**
Z
zengyawen 已提交
107

108 109 110
```html
<!-- xxx.hml -->
<div>
Z
zengyawen 已提交
111 112
  <div data-a="dataA" data-b="dataB" 
    style="width: 100%; height: 50%; background-color: saddlebrown;"@touchstart='touchstartfunc'></div>
113
</div>
Z
zengyawen 已提交
114 115
```

116
```js
Z
zengyawen 已提交
117 118 119 120 121 122 123 124
// xxx.js
export default {
  touchstartfunc(msg) {
    console.info(`on touch start, point is: ${msg.touches[0].globalX}`);
    console.info(`on touch start, data is: ${msg.target.dataSet.a}`);
  }
}
```
125 126 127 128 129 130 131 132 133 134 135 136 137

## DataTransfer<sup>9+</sup>

Use **dataTransfer** to transfer data during the drag operation, so you can perform operations on the data when the drag operation is complete.

### setData<sup>9+</sup>

setData(key: string, value: object): boolean

Sets the data associated with the specified key. If there is no data associated with the key, the data will be appended. If there is already data associated with the key, the data will replace the existing data in the same position.

**Parameters**

E
ester.zhou 已提交
138
| Name  | Type  | Mandatory  | Description     |
139 140 141 142 143
| ----- | ------ | ---- | ------- |
| key   | string | Yes   | Data key.  |
| value | object | Yes   | Data to be stored.|

**Return value**
E
ester.zhou 已提交
144

145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
| Type     | Description                       |
| ------- | ------------------------ |
| boolean | Operation result. The value **true** means that the operation is successful, and **false** means otherwise.|

**Example**

```js
// value in setData can be of a primitive type.
dragStart(e) {
	var isSetOk = e.dataTransfer.setData('name', 1);
},
// value in setData can be of the object type.
dragStart(e) {
	var person = new Object();
	person.name = "tom";
	person.age = 21;
	var isSetOk = e.dataTransfer.setData('person', person);
}
```
### getData<sup>9+</sup>

getData(key: string): object

Obtains the data associated with the specified key. If no data is associated with the key, an empty string will be returned.

**Parameters**

E
ester.zhou 已提交
172
| Name | Type  | Mandatory  | Description   |
173 174 175 176
| ---- | ------ | ---- | ----- |
| key  | string | Yes   | Data key.|

**Return value**
E
ester.zhou 已提交
177

178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
| Type    | Description     |
| ------ | ------ |
| object | Obtained data.|

**Example**

```js
dragStart(e) {
	var person = new Object();
	person.name = "tom";
	person.age = 21;
	e.dataTransfer.setData('person', person);
},
dragEnd(e){
	var person = e.dataTransfer.getData('person');
},
```
### clearData<sup>9+</sup>

clearData(key?: string): boolean

Deletes data associated with the specified key. If there is no data associated with the key, this API will not have any effect.
If the key is null, all data will be deleted.

**Parameters**

E
ester.zhou 已提交
204
| Name | Type  | Mandatory  | Description   |
205 206 207 208
| ---- | ------ | ---- | ----- |
| key  | string | No   | Data key.|

**Return value**
E
ester.zhou 已提交
209

210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228
| Type     | Description                       |
| ------- | ------------------------ |
| boolean | Operation result. The value **true** means that the operation is successful, and **false** means otherwise.|

**Example**

```js
dragEnd(e) {
	var isSuccess = e.dataTransfer.clearData('name');
}
```
### setDragImage<sup>9+</sup>

setDragImage(pixelmap: PixelMap, offsetX: number,offsetY: number): boolean

Sets a custom drag image.

**Parameters**

E
ester.zhou 已提交
229
| Name     | Type    | Mandatory  | Description                                      |
230
| -------- | -------- | ---- | ---------------------------------------- |
E
ester.zhou 已提交
231
| pixelmap | [PixelMap](../apis/js-apis-image.md#pixelmap7) | Yes   | Image transferred from the frontend.|
232 233 234 235
| offsetX  | number   | Yes   | Horizontal offset relative to the image.                            |
| offsetY  | number   | Yes   | Vertical offset relative to the image.                           |

**Return value**
E
ester.zhou 已提交
236

237 238
| Type  | Description                       |
| ---- | ------------------------ |
239
| boolean | Operation result. The value **true** means that the operation is successful, and **false** means otherwise.|
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272

**Example**

```js
createPixelMap() {
	let color = new ArrayBuffer(4*96*96);
	var buffer = new Uint8Array(color);
	for (var i = 0; i < buffer.length; i++) {
		buffer[i] = (i + 1) % 255;
	}
	let opts = {
		alphaType:0,
		editable:true,
		pixelFormat:4,
		scaleMode:1,
		size:{height:96,width:96}
	}
	const promise = image.createPixelMap(color,opts);
	promise.then((data)=> {
		console.error('-create pixmap has info message:' + JSON.stringify(data));
		this.pixelMap = data;
		this.pixelMapReader = data;
	})
},

onInit() {
	this.createPixelMap
},

dragStart(e) {
	e.dataTransfer.setDragImage(this.pixelMapReader, 50, 50);
}
```
新手
引导
客服 返回
顶部