js-apis-emitter.md 5.6 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.events.emitter (Emitter)
Z
zengsiyu 已提交
2

L
Leon 已提交
3
本模块提供了在同一进程不同线程间,或同一进程同一线程内,发送和处理事件的能力,包括持续订阅事件、单次订阅事件、取消订阅事件,以及发送事件到事件队列的能力。
4 5 6

> **说明:**
>
L
Leon 已提交
7 8 9
> 本模块首批接口从API version 7开始支持。后续版本新增接口,采用上角标单独标记接口的起始版本。
>
> 本模块接口在FA模型及Stage模型下均可使用。
Z
zengsiyu 已提交
10 11 12 13 14 15 16 17 18

## 导入模块

```javascript
import emitter from '@ohos.events.emitter'
```

## 权限列表

L
Leon 已提交
19
无权限要求。
Z
zengsiyu 已提交
20 21 22

## emitter.on

23
on(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
Z
zengsiyu 已提交
24

L
Leon 已提交
25
持续订阅指定的事件,并在接收到该事件时,执行对应的回调处理函数。
Z
zengsiyu 已提交
26

L
Leon 已提交
27
**系统能力**: `SystemCapability.Notification.Emitter`
X
xuzhihao 已提交
28

Z
zengsiyu 已提交
29 30
**参数:**

L
Leon 已提交
31 32 33 34
| 参数名   | 类型                                | 必填 | 说明                                                     |
| -------- | ----------------------------------- | ---- | ------------------------------------------------------ |
| event    | [InnerEvent](#innerevent)           | 是   | 持续订阅的事件,其中[EventPriority](#eventpriority),在订阅事件时无需指定,也不生效 |
| callback | Callback\<[EventData](#eventdata)\> | 是   | 接收到该事件时需要执行的回调处理函数                       |
Z
zengsiyu 已提交
35 36 37 38

**示例:**

```javascript
F
fangJinliang1 已提交
39
let innerEvent = {
40
    eventId: 1
Z
zengsiyu 已提交
41
};
L
Leon 已提交
42 43 44

// 收到eventId为1的事件后执行该回调函数
function emitterCallback() {
Z
zengsiyu 已提交
45
    console.info('callback');
F
fangJinliang1 已提交
46
}
L
Leon 已提交
47
emitter.on(innerEvent, emitterCallback);
Z
zengsiyu 已提交
48 49 50 51
```

## emitter.once

52
once(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
Z
zengsiyu 已提交
53

L
Leon 已提交
54
单次订阅指定的事件,并在接收到该事件并执行完相应的回调函数后,自动取消订阅。
Z
zengsiyu 已提交
55

L
Leon 已提交
56
**系统能力**: `SystemCapability.Notification.Emitter`
X
xuzhihao 已提交
57

Z
zengsiyu 已提交
58 59
**参数:**

L
Leon 已提交
60 61 62
| 参数名   | 类型                                | 必填 | 说明                                                                            |
| -------- | ----------------------------------- | ---- | ------------------------------------------------------------------------------ |
| event    | [InnerEvent](#innerevent)           | 是   | 单次订阅的事件,其中[EventPriority](#eventpriority),在订阅事件时无需指定,也不生效 |
L
Leon 已提交
63
| callback | Callback\<[EventData](#eventdata)\> | 是   | 接收到该事件时需要执行的回调处理函数                                             |
Z
zengsiyu 已提交
64 65 66 67

**示例:**

```javascript
F
fangJinliang1 已提交
68
let innerEvent = {
69
    eventId: 1
Z
zengsiyu 已提交
70
};
L
Leon 已提交
71 72 73

// 收到eventId为1的事件后执行该回调函数
function emitterCallback() {
Z
zengsiyu 已提交
74 75
    console.info('once callback');
};
L
Leon 已提交
76
emitter.once(innerEvent, emitterCallback);
Z
zengsiyu 已提交
77 78 79 80 81 82
```

## emitter.off

off(eventId: number): void

L
Leon 已提交
83
取消所有针对该事件ID的订阅。
Z
zengsiyu 已提交
84

L
Leon 已提交
85
**系统能力**: `SystemCapability.Notification.Emitter`
X
xuzhihao 已提交
86

Z
zengsiyu 已提交
87 88
**参数:**

89 90 91
| 参数名  | 类型   | 必填 | 说明   |
| ------- | ------ | ---- | ------ |
| eventId | number | 是   | 事件ID |
Z
zengsiyu 已提交
92 93 94 95 96 97 98 99 100

**示例:**

```javascript
emitter.off(1);
```

## emitter.emit

L
Leon 已提交
101
emit(event: [InnerEvent](#innerevent), data?: [EventData](#eventdata)): void
Z
zengsiyu 已提交
102

L
Leon 已提交
103
发送指定的事件。
Z
zengsiyu 已提交
104

L
Leon 已提交
105
**系统能力**: `SystemCapability.Notification.Emitter`
X
xuzhihao 已提交
106

Z
zengsiyu 已提交
107 108 109
**参数:**

| 参数名 | 类型                      | 必填 | 说明           |
L
Leon 已提交
110 111
| ------ | ------------------------- | ---- | ------------- |
| event  | [InnerEvent](#innerevent) | 是   | 发送的事件,其中[EventPriority](#eventpriority)用于指定事件被发送的优先级 |
112
| data   | [EventData](#eventdata)   | 否   | 事件携带的数据 |
Z
zengsiyu 已提交
113 114 115 116

**示例:**

```javascript
F
fangJinliang1 已提交
117
let eventData = {
Z
zengsiyu 已提交
118
    data: {
119 120
        "content": "c",
        "id": 1,
L
Leon 已提交
121 122 123
    }
};

F
fangJinliang1 已提交
124
let innerEvent = {
125
    eventId: 1,
Z
zengsiyu 已提交
126 127
    priority: emitter.EventPriority.HIGH
};
L
Leon 已提交
128

Z
zengsiyu 已提交
129 130 131
emitter.emit(innerEvent, eventData);
```

F
fangJinliang1 已提交
132 133
## EventPriority

L
Leon 已提交
134
用于表示事件被发送的优先级。
F
fangJinliang1 已提交
135

L
Leon 已提交
136
**系统能力**:  `SystemCapability.Notification.Emitter`
F
fangJinliang1 已提交
137

L
Leon 已提交
138
| 名称      | 值    | 说明                                                |
F
fangJinliang1 已提交
139
| --------- | ---- | --------------------------------------------------- |
L
Leon 已提交
140 141 142 143
| IMMEDIATE | 0    | 表示事件被立即投递。                                 |
| HIGH      | 1    | 表示事件先于LOW优先级投递。                           |
| LOW       | 2    | 表示事件优于IDLE优先级投递,事件的默认优先级是LOW。     |
| IDLE      | 3    | 表示在没有其他事件的情况下,才投递该事件。             |
F
fangJinliang1 已提交
144

Z
zengsiyu 已提交
145 146
## InnerEvent

L
Leon 已提交
147
订阅或发送的事件,订阅事件时`EventPriority`不生效。
Z
zengsiyu 已提交
148

L
Leon 已提交
149
**系统能力**: `SystemCapability.Notification.Emitter`
X
xuzhihao 已提交
150

L
Leon 已提交
151 152 153 154
| 名称     | 类型                        | 可读 | 可写 | 说明                                 |
| -------- | ------------------------------- | ---- | ---- | ------------------------------ |
| eventId  | number                          | 是   | 是   | 事件ID,由开发者定义用来辨别事件。 |
| priority | [EventPriority](#eventpriority) | 是   | 是   | 事件被投递的优先级。             |
Z
zengsiyu 已提交
155 156 157 158 159

## EventData

发送事件时传递的数据。

L
Leon 已提交
160
**系统能力**: `SystemCapability.Notification.Emitter`
X
xuzhihao 已提交
161

X
xuzhihao 已提交
162
| 名称 | 类型           | 可读 | 可写 | 说明           |
Z
zengsiyu 已提交
163
| ---- | ------------------ | ---- | ---- | -------------- |
杨亮 已提交
164
| data | [key: string]: any | 是   | 是   | 发送事件时传递的数据,数据类型支持字符串、整型和布尔型。<br> 其中字符串长度最大为10240字节。 |