• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.events.emitter (Emitter)
2
3The **Emitter** module provides the capabilities of sending and processing inter- or intra-thread events in a process. You can use the APIs of this module to subscribe to an event in persistent or one-shot manner, unsubscribe from an event, or emit an event to the event queue.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used in the FA model or stage model.
10
11## Modules to Import
12
13```ts
14import emitter from '@ohos.events.emitter';
15```
16
17## Required Permissions
18
19None
20
21## emitter.on
22
23on(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
24
25Subscribes to an event in persistent manner and executes a callback after the event is received.
26
27**System capability**: SystemCapability.Notification.Emitter
28
29**Parameters**
30
31| Name  | Type                               | Mandatory| Description                                                    |
32| -------- | ----------------------------------- | ---- | ------------------------------------------------------ |
33| event    | [InnerEvent](#innerevent)           | Yes  | Event to subscribe to in persistent manner. The [EventPriority](#eventpriority) settings do not take effect.|
34| callback | Callback\<[EventData](#eventdata)\> | Yes  | Callback to execute after the event is received.                      |
35
36**Example**
37
38```ts
39let innerEvent: emitter.InnerEvent = {
40  eventId: 1
41};
42
43// Execute the callback after receiving the event whose eventId is 1.
44emitter.on(innerEvent, () => {
45  console.info('callback');
46});
47```
48
49## emitter.once
50
51once(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
52
53Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed.
54
55**System capability**: SystemCapability.Notification.Emitter
56
57**Parameters**
58
59| Name  | Type                               | Mandatory| Description                                                                           |
60| -------- | ----------------------------------- | ---- | ------------------------------------------------------------------------------ |
61| event    | [InnerEvent](#innerevent)           | Yes  | Event to subscribe to in one-shot manner. The [EventPriority](#eventpriority) settings do not take effect.|
62| callback | Callback\<[EventData](#eventdata)\> | Yes  | Callback to execute after the event is received.                                            |
63
64**Example**
65
66```ts
67let innerEvent: emitter.InnerEvent = {
68    eventId: 1
69};
70
71// Execute the callback after receiving the event whose eventId is 1.
72emitter.once(innerEvent, () => {
73    console.info('once callback');
74});
75```
76
77## emitter.off
78
79off(eventId: number): void
80
81Unsubscribes from an event.
82
83**System capability**: SystemCapability.Notification.Emitter
84
85**Parameters**
86
87| Name | Type  | Mandatory| Description  |
88| ------- | ------ | ---- | ------ |
89| eventId | number | Yes  | Event ID.|
90
91**Example**
92
93```ts
94// Unregister the callbacks of all events whose eventID is 1.
95emitter.off(1);
96```
97
98## emitter.off<sup>10+<sup>
99
100off(eventId: number, callback: Callback\<[EventData](#eventdata)\>): void
101
102Unsubscribes from an event. If the specified callback has been registered through the **on** or **once** API, it is unregistered. Otherwise, no processing is performed.
103
104**System capability**: SystemCapability.Notification.Emitter
105
106**Parameters**
107
108| Name | Type  | Mandatory| Description  |
109| ------- | ------ | ---- | ------ |
110| eventId | number | Yes  | Event ID.|
111| callback<sup>10+</sup> | Callback\<[EventData](#eventdata)\> | Yes  | Callback to unregister.  |
112
113**Example**
114
115```ts
116// Unregister the emitterCallback callback for the event whose eventID is 1.
117// If the callback has not been registered, no processing is performed.
118emitter.off(1, () => {
119  console.info('callback');
120});
121```
122
123## emitter.emit
124
125emit(event: [InnerEvent](#innerevent), data?: [EventData](#eventdata)): void
126
127Emits an event.
128
129**System capability**: SystemCapability.Notification.Emitter
130
131**Parameters**
132
133| Name| Type                     | Mandatory| Description          |
134| ------ | ------------------------- | ---- | ------------- |
135| event  | [InnerEvent](#innerevent) | Yes  | Event to emit, where [EventPriority](#eventpriority) specifies the emit priority of the event.|
136| data   | [EventData](#eventdata)   | No  | Data carried by the event.|
137
138**Example**
139
140```ts
141let eventData: emitter.EventData = {
142    data: {
143        "content": "c",
144        "id": 1,
145    }
146};
147
148let innerEvent: emitter.InnerEvent = {
149    eventId: 1,
150    priority: emitter.EventPriority.HIGH
151};
152
153emitter.emit(innerEvent, eventData);
154```
155
156## EventPriority
157
158Enumerates the event emit priority levels.
159
160**System capability**: SystemCapability.Notification.Emitter
161
162| Name     | Value   | Description                                               |
163| --------- | ---- | --------------------------------------------------- |
164| IMMEDIATE | 0    | The event will be emitted immediately.                                |
165| HIGH      | 1    | The event will be emitted before low-priority events.                          |
166| LOW       | 2    | The event will be emitted before idle-priority events. By default, an event is in LOW priority.    |
167| IDLE      | 3    | The event will be emitted after all the other events.            |
168
169## InnerEvent
170
171Describes an event to subscribe to or emit. The **EventPriority** settings do not take effect under event subscription.
172
173**System capability**: SystemCapability.Notification.Emitter
174
175| Name    | Type                       | Readable| Writable| Description                                |
176| -------- | ------------------------------- | ---- | ---- | ------------------------------ |
177| eventId  | number                          | Yes  | Yes  | Event ID.|
178| priority | [EventPriority](#eventpriority) | Yes  | Yes  | Emit priority of the event.            |
179
180## EventData
181
182Describes the data passed in the event.
183
184**System capability**: SystemCapability.Notification.Emitter
185
186| Name| Type          | Readable| Writable| Description          |
187| ---- | ------------------ | ---- | ---- | -------------- |
188| data | [key: string]: any | Yes  | Yes  | Data carried by the event. The value can be a string, integer, or Boolean, wherein a string contains a maximum of 10240 bytes. |
189