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## Modules to Import 10 11```ts 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 and executes a callback after the event is received. 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](#eventpriority) parameter is not required and does not take effect.| 32| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be executed when the event is received. | 33 34**Example** 35 36```ts 37let innerEvent: emitter.InnerEvent = { 38 eventId: 1 39}; 40 41// Execute the callback after receiving the event whose eventId is 1. 42emitter.on(innerEvent, () => { 43 console.info('callback'); 44}); 45``` 46 47## emitter.on<sup>11+</sup> 48 49on(eventId: string, callback: Callback\<[EventData](#eventdata)\>): void 50 51Subscribes to an event in persistent manner and executes a callback after the event is received. 52 53**System capability**: SystemCapability.Notification.Emitter 54 55**Parameters** 56 57| Name | Type | Mandatory| Description | 58| -------- | ----------------------------------- | ---- | -------------------------------------- | 59| event | string | Yes | Event to subscribe to in persistent manner. The value cannot be an empty string. | 60| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be executed when the event is received.| 61 62**Example** 63 64```ts 65// Execute the callback after receiving the event whose eventId is eventId. 66emitter.on("eventId", () => { 67 console.info('callback'); 68}); 69``` 70 71## emitter.once 72 73once(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void 74 75Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. 76 77**System capability**: SystemCapability.Notification.Emitter 78 79**Parameters** 80 81| Name | Type | Mandatory| Description | 82| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 83| event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in one-shot manner. The [EventPriority](#eventpriority) parameter is not required and does not take effect.| 84| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be executed when the event is received. | 85 86**Example** 87 88```ts 89let innerEvent: emitter.InnerEvent = { 90 eventId: 1 91}; 92 93// Execute the callback after receiving the event whose eventId is 1. 94emitter.once(innerEvent, () => { 95 console.info('once callback'); 96}); 97``` 98 99## emitter.once<sup>11+</sup> 100 101once(eventId: string, callback: Callback\<[EventData](#eventdata)\>): void 102 103Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. 104 105**System capability**: SystemCapability.Notification.Emitter 106 107**Parameters** 108 109| Name | Type | Mandatory| Description | 110| -------- | ----------------------------------- | ---- | -------------------------------------- | 111| event | string | Yes | Event to subscribe to in one-shot manner. The value cannot be an empty string. | 112| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be executed when the event is received.| 113 114**Example** 115 116```ts 117// Execute the callback after receiving the event whose eventId is eventId. 118emitter.once("eventId", () => { 119 console.info('once callback'); 120}); 121``` 122 123## emitter.off 124 125off(eventId: number): void 126 127Unsubscribes from an event. 128 129**System capability**: SystemCapability.Notification.Emitter 130 131**Parameters** 132 133| Name | Type | Mandatory| Description | 134| ------- | ------ | ---- | -------- | 135| eventId | number | Yes | Event ID.| 136 137**Example** 138 139```ts 140// Unregister the callbacks of all events whose eventID is 1. 141emitter.off(1); 142``` 143 144## emitter.off<sup>11+</sup> 145 146off(eventId: string): void 147 148Unsubscribes from an event. 149 150**System capability**: SystemCapability.Notification.Emitter 151 152**Parameters** 153 154| Name | Type | Mandatory| Description | 155| ------- | ------ | ---- | -------- | 156| eventId | string | Yes | Event ID. The value cannot be an empty string.| 157 158**Example** 159 160```ts 161// Unregister the callbacks of all events whose eventID is 1. 162emitter.off("eventId"); 163``` 164 165## emitter.off<sup>10+</sup> 166 167off(eventId: number, callback: Callback\<[EventData](#eventdata)\>): void 168 169Unsubscribes from an event. If the specified callback has been registered through the **on** or **once** API, it is unregistered. Otherwise, no processing is performed. 170 171**System capability**: SystemCapability.Notification.Emitter 172 173**Parameters** 174 175| Name | Type | Mandatory| Description | 176| ------- | ------ | ---- | ------ | 177| eventId | number | Yes | Event ID.| 178| callback<sup>10+</sup> | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister. | 179 180**Example** 181 182```ts 183// Unregister the emitterCallback callback for the event whose eventID is 1. 184// If the callback has not been registered, no processing is performed. 185emitter.off(1, () => { 186 console.info('callback'); 187}); 188``` 189 190## emitter.off<sup>11+</sup> 191 192off(eventId: string, callback: Callback\<[EventData](#eventdata)\>): void 193 194Unsubscribes from an event. If the specified callback has been registered through the **on** or **once** API, it is unregistered. Otherwise, no processing is performed. 195 196**System capability**: SystemCapability.Notification.Emitter 197 198**Parameters** 199 200| Name | Type | Mandatory| Description | 201| -------- | ----------------------------------- | ---- | -------------------------- | 202| eventId | string | Yes | Event ID. The value cannot be an empty string. | 203| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister.| 204 205**Example** 206 207```ts 208// Unregister the emitterCallback callback for the event whose eventID is eventId. 209// If the callback has not been registered, no processing is performed. 210emitter.off("eventId", () => { 211 console.info('callback'); 212}); 213``` 214 215## emitter.emit 216 217emit(event: [InnerEvent](#innerevent), data?: [EventData](#eventdata)): void 218 219Emits an event. 220 221**System capability**: SystemCapability.Notification.Emitter 222 223**Parameters** 224 225| Name| Type | Mandatory| Description | 226| ------ | ------------------------- | ---- | ------------- | 227| event | [InnerEvent](#innerevent) | Yes | Event to emit, where [EventPriority](#eventpriority) specifies the emit priority of the event.| 228| data | [EventData](#eventdata) | No | Data passed in the event.| 229 230**Example** 231 232```ts 233let eventData: emitter.EventData = { 234 data: { 235 "content": "c", 236 "id": 1, 237 } 238}; 239 240let innerEvent: emitter.InnerEvent = { 241 eventId: 1, 242 priority: emitter.EventPriority.HIGH 243}; 244 245emitter.emit(innerEvent, eventData); 246``` 247 248## emitter.emit<sup>11+</sup> 249 250emit(eventId: string, data?: [EventData](#eventdata)): void 251 252Emits the specified event. 253 254**System capability**: SystemCapability.Notification.Emitter 255 256**Parameters** 257 258| Name | Type | Mandatory| Description | 259| ------- | ----------------------- | ---- | ---------------- | 260| eventId | string | Yes | ID of the event to emit. The value cannot be an empty string. | 261| data | [EventData](#eventdata) | No | Data passed in the event.| 262 263**Example** 264 265```ts 266let eventData: emitter.EventData = { 267 data: { 268 "content": "c", 269 "id": 1, 270 } 271}; 272 273emitter.emit("eventId", eventData); 274``` 275 276## emitter.emit<sup>11+</sup> 277 278emit(eventId: string, options: [Options](#options11), data?: [EventData](#eventdata)): void 279 280Emits an event of a specified priority. 281 282**System capability**: SystemCapability.Notification.Emitter 283 284**Parameters** 285 286| Name | Type | Mandatory| Description | 287| ------- | ----------------------- | ---- | ---------------- | 288| eventId | string | Yes | ID of the event to emit. The value cannot be an empty string. | 289| options | [Options](#options11) | Yes | Event emit priority. | 290| data | [EventData](#eventdata) | No | Data passed in the event.| 291 292**Example** 293 294```ts 295let eventData: emitter.EventData = { 296 data: { 297 "content": "c", 298 "id": 1, 299 } 300}; 301 302let options: emitter.Options = { 303 priority: emitter.EventPriority.HIGH 304}; 305 306emitter.emit("eventId", options, eventData); 307``` 308 309## emitter.getListenerCount<sup>11+</sup> 310 311getListenerCount(eventId: number|string): number 312 313Obtains the number of subscriptions to a specified event. 314 315**System capability**: SystemCapability.Notification.Emitter 316 317**Parameters** 318 319| Name | Type | Mandatory| Description | 320| ------- | -------------- | ---- | -------- | 321| eventId | number\|string | Yes | Event ID. The value of the string type cannot be an empty string.| 322 323**Example** 324 325```ts 326let count = emitter.getListenerCount("eventId"); 327``` 328 329## EventPriority 330 331Enumerates the event emit priority levels. 332 333**System capability**: SystemCapability.Notification.Emitter 334 335| Name | Value | Description | 336| --------- | ---- | --------------------------------------------------- | 337| IMMEDIATE | 0 | The event will be emitted immediately. | 338| HIGH | 1 | The event will be emitted before low-priority events. | 339| LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority. | 340| IDLE | 3 | The event will be emitted after all the other events. | 341 342## InnerEvent 343 344Describes an event to subscribe to or emit. The **EventPriority** settings do not take effect under event subscription. 345 346**System capability**: SystemCapability.Notification.Emitter 347 348| Name | Type | Readable| Writable| Description | 349| -------- | ------------------------------- | ---- | ---- | ------------------------------ | 350| eventId | number | Yes | Yes | Event ID.| 351| priority | [EventPriority](#eventpriority) | Yes | Yes | Emit priority of the event. | 352 353## EventData 354 355Describes the data passed in the event. 356 357**System capability**: SystemCapability.Notification.Emitter 358 359| Name| Type | Readable| Writable| Description | 360| ---- | ------------------ | ---- | ---- | -------------- | 361| data | [key: string]: any | Yes | Yes | Data passed in the event. The value can be in any of the following types: Array, ArrayBuffer, Boolean, DataView, Date, Error, Map, Number, Object, Primitive (except symbol), RegExp, Set, String, and TypedArray. The maximum data size is 16 MB.| 362 363## Options<sup>11+</sup> 364 365Describes the event emit priority. 366 367**System capability**: SystemCapability.Notification.Emitter 368 369| Name | Type | Readable| Writable| Description | 370| -------- | ------------------------------- | ---- | ---- | -------------- | 371| priority | [EventPriority](#eventpriority) | Yes | Yes | Event priority.| 372