• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.events.emitter
2
3The **Emitter** module provides APIs for sending and processing in-process events, including the APIs for processing events that are subscribed to in persistent or one-shot manner, unsubscribing from events, and emitting events to the event queue.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 7.
8
9## Modules to Import
10
11```javascript
12import emitter from '@ohos.events.emitter'
13```
14
15## Required Permissions
16
17None
18
19## emitter.on
20
21on(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
22
23Subscribes to an event in persistent manner. This API uses a callback to return the event.
24
25**System capability**: SystemCapability.Notification.Emitter
26
27**Parameters**
28
29| Name  | Type                               | Mandatory| Description                                   |
30| -------- | ----------------------------------- | ---- | --------------------------------------- |
31| event    | [InnerEvent](#innerevent)           | Yes  | Event to subscribe to in persistent manner. The **EventPriority** settings do not take effect.|
32| callback | Callback\<[EventData](#eventdata)\> | Yes  | Callback used to return the event.               |
33
34**Example**
35
36```javascript
37let innerEvent = {
38    eventId: 1
39};
40function EmitterCallback(eventData) {
41    console.info('callback');
42}
43emitter.on(innerEvent, EmitterCallback);
44```
45
46## emitter.once
47
48once(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void
49
50Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is received.
51
52**System capability**: SystemCapability.Notification.Emitter
53
54**Parameters**
55
56| Name  | Type                               | Mandatory| Description                                   |
57| -------- | ----------------------------------- | ---- | --------------------------------------- |
58| event    | [InnerEvent](#innerevent)           | Yes  | Event to subscribe to in one-shot manner. The **EventPriority** settings do not take effect.|
59| callback | Callback\<[EventData](#eventdata)\> | Yes  | Callback used to return the event.               |
60
61**Example**
62
63```javascript
64let innerEvent = {
65    eventId: 1
66};
67function EmitterCallback(eventData) {
68    console.info('once callback');
69};
70emitter.once(innerEvent, EmitterCallback);
71```
72
73## emitter.off
74
75off(eventId: number): void
76
77Unsubscribes from an event.
78
79**System capability**: SystemCapability.Notification.Emitter
80
81**Parameters**
82
83| Name | Type  | Mandatory| Description  |
84| ------- | ------ | ---- | ------ |
85| eventId | number | Yes  | Event ID.|
86
87**Example**
88
89```javascript
90emitter.off(1);
91```
92
93## emitter.emit
94
95emit(event: InnerEvent, data?: EventData): void
96
97Emits an event to the event queue.
98
99**System capability**: SystemCapability.Notification.Emitter
100
101**Parameters**
102
103| Name| Type                     | Mandatory| Description          |
104| ------ | ------------------------- | ---- | -------------- |
105| event  | [InnerEvent](#innerevent) | Yes  | Event to emit.    |
106| data   | [EventData](#eventdata)   | No  | Data carried by the event.|
107
108**Example**
109
110```javascript
111let eventData = {
112    data: {
113        "content": "c",
114        "id": 1,
115    }};
116let innerEvent = {
117    eventId: 1,
118    priority: emitter.EventPriority.HIGH
119};
120emitter.emit(innerEvent, eventData);
121```
122
123## EventPriority
124
125Enumerates the event emit priority levels.
126
127**System capability**: SystemCapability.Notification.Emitter
128
129| Name     | Value  | Description                                               |
130| --------- | ---- | --------------------------------------------------- |
131| IMMEDIATE | 0    | The event will be emitted immediately.                               |
132| HIGH      | 1    | The event will be emitted before low-priority events.                        |
133| LOW       | 2    | The event will be emitted before idle-priority events. By default, an event is in LOW priority.|
134| IDLE      | 3    | The event will be emitted after all the other events.         |
135
136## InnerEvent
137
138Describes an in-process event.
139
140**System capability**: SystemCapability.Notification.Emitter
141
142| Name    | Type                       | Readable| Writable| Description                              |
143| -------- | ------------------------------- | ---- | ---- | ---------------------------------- |
144| eventId  | number                          | Yes  | Yes  | Event ID.|
145| priority | [EventPriority](#eventpriority) | Yes  | Yes  | Emit priority of the event.        |
146
147## EventData
148
149Describes the data passed in the event.
150
151**System capability**: SystemCapability.Notification.Emitter
152
153| Name| Type          | Readable| Writable| Description          |
154| ---- | ------------------ | ---- | ---- | -------------- |
155| 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. |
156