1# EventHub 2 3The **EventHub** module provides APIs to subscribe to, unsubscribe from, and trigger events. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs of this module can be used only in the stage model. 9 10## Modules to Import 11 12```ts 13import { common } from '@kit.AbilityKit'; 14``` 15 16## Usage 17 18Before using any APIs in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **UIAbility** instance. 19 20```ts 21import { UIAbility } from '@kit.AbilityKit'; 22 23export default class EntryAbility extends UIAbility { 24 eventFunc() { 25 console.log('eventFunc is called'); 26 } 27 28 onCreate() { 29 this.context.eventHub.on('myEvent', this.eventFunc); 30 } 31} 32``` 33EventHub is not a global event center. Different context objects have different EventHub objects. Event subscription, unsubscription, and triggering are performed on a specific EventHub object. Therefore, EventHub cannot be used for event transmission between VMs or processes. 34 35## EventHub.on 36 37on(event: string, callback: Function): void; 38 39Subscribes to an event. 40> **NOTE** 41> 42> When the callback is triggered by **emit**, the invoker is the **EventHub** object. To change the direction of **this** in **callback**, use an arrow function. 43 44**Atomic service API**: This API can be used in atomic services since API version 11. 45 46**System capability**: SystemCapability.Ability.AbilityRuntime.Core 47 48**Parameters** 49 50| Name | Type | Mandatory | Description | 51| -------- | -------- | -------- | -------- | 52| event | string | Yes | Event name. | 53| callback | Function | Yes | Callback invoked when the event is triggered. | 54 55**Error codes** 56 57For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 58 59| ID | Error Message | 60| ------- | -------- | 61| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 62 63**Example 1** 64When the callback is triggered by **emit**, the invoker is the **EventHub** object. The **EventHub** object does not have the **value** property. Therefore, the result **undefined** is returned. 65 66```ts 67import { UIAbility } from '@kit.AbilityKit'; 68 69export default class EntryAbility extends UIAbility { 70 value: number = 12; 71 72 onCreate() { 73 this.context.eventHub.on('myEvent', this.eventFunc); 74 } 75 76 onForeground() { 77 // Result 78 // eventFunc is called, value: undefined 79 80 this.context.eventHub.emit('myEvent'); 81 } 82 83 eventFunc() { 84 console.log(`eventFunc is called, value: ${this.value}`); 85 } 86} 87``` 88 89**Example 2** 90When the callback uses an arrow function, the invoker is the **EntryAbility** object. The **EntryAbility** object has the **value** property. Therefore, the result **12** is returned. 91 92```ts 93import { UIAbility } from '@kit.AbilityKit'; 94 95export default class EntryAbility extends UIAbility { 96 value: number = 12; 97 98 onCreate() { 99 // Anonymous functions can be used to subscribe to events. 100 this.context.eventHub.on('myEvent', () => { 101 console.log(`anonymous eventFunc is called, value: ${this.value}`); 102 }); 103 } 104 105 onForeground() { 106 // Result 107 // anonymous eventFunc is called, value: 12 108 this.context.eventHub.emit('myEvent'); 109 } 110 111 eventFunc() { 112 console.log(`eventFunc is called, value: ${this.value}`); 113 } 114} 115``` 116 117## EventHub.off 118 119off(event: string, callback?: Function): void; 120 121Unsubscribes from an event. 122 - If **callback** is specified, this API unsubscribes from the given event with the specified callback. 123 - If **callback** is not specified, this API unsubscribes from the given event with all callbacks. 124 125**Atomic service API**: This API can be used in atomic services since API version 11. 126 127**System capability**: SystemCapability.Ability.AbilityRuntime.Core 128 129**Parameters** 130 131| Name | Type | Mandatory | Description | 132| -------- | -------- | -------- | -------- | 133| event | string | Yes | Event name. | 134| callback | Function | No | Callback for the event. If **callback** is unspecified, the given event with all callbacks is unsubscribed. | 135 136**Error codes** 137 138For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 139 140| ID | Error Message | 141| ------- | -------- | 142| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 143 144**Example** 145 146```ts 147import { UIAbility } from '@kit.AbilityKit'; 148 149export default class EntryAbility extends UIAbility { 150 onCreate() { 151 this.context.eventHub.on('myEvent', this.eventFunc1); 152 this.context.eventHub.off('myEvent', this.eventFunc1); // Unsubscribe from the myEvent event with the callback eventFunc1. 153 this.context.eventHub.on('myEvent', this.eventFunc1); 154 this.context.eventHub.on('myEvent', this.eventFunc2); 155 this.context.eventHub.off('myEvent'); // Unsubscribe from the myEvent event with all the callbacks (eventFunc1 and eventFunc2). 156 } 157 158 eventFunc1() { 159 console.log('eventFunc1 is called'); 160 } 161 162 eventFunc2() { 163 console.log('eventFunc2 is called'); 164 } 165} 166``` 167 168## EventHub.emit 169 170emit(event: string, ...args: Object[]): void; 171 172Triggers an event. 173 174**Atomic service API**: This API can be used in atomic services since API version 11. 175 176**System capability**: SystemCapability.Ability.AbilityRuntime.Core 177 178**Parameters** 179 180| Name | Type | Mandatory | Description | 181| -------- | -------- | -------- | -------- | 182| event | string | Yes | Event name. | 183| ...args | Object[] | No | Variable parameters, which are passed to the callback when the event is triggered. | 184 185**Error codes** 186 187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 188 189| ID | Error Message | 190| ------- | -------- | 191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 192 193**Example** 194 195```ts 196import { UIAbility } from '@kit.AbilityKit'; 197 198export default class EntryAbility extends UIAbility { 199 onCreate() { 200 this.context.eventHub.on('myEvent', this.eventFunc); 201 } 202 203 onDestroy() { 204 // Result 205 // eventFunc is called,undefined,undefined 206 this.context.eventHub.emit('myEvent'); 207 // Result 208 // eventFunc is called,1,undefined 209 this.context.eventHub.emit('myEvent', 1); 210 // Result 211 // eventFunc is called,1,2 212 this.context.eventHub.emit('myEvent', 1, 2); 213 } 214 215 eventFunc(argOne: number, argTwo: number) { 216 console.log(`eventFunc is called, ${argOne}, ${argTwo}`); 217 } 218} 219``` 220