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';
68import { BusinessError } from '@kit.BasicServicesKit';
69
70export default class EntryAbility extends UIAbility {
71  value: number = 12;
72
73  onCreate() {
74    try {
75      this.context.eventHub.on('myEvent', this.eventFunc);
76    } catch (e) {
77      let code: number = (e as BusinessError).code;
78      let msg: string = (e as BusinessError).message;
79      console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
80    }
81  }
82
83  onForeground() {
84    try {
85      // Result
86      // eventFunc is called, value: undefined
87      this.context.eventHub.emit('myEvent');
88    } catch (e) {
89      let code: number = (e as BusinessError).code;
90      let msg: string = (e as BusinessError).message;
91      console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
92    }
93  }
94
95  eventFunc() {
96    console.log(`eventFunc is called, value: ${this.value}`);
97  }
98}
99```
100
101**Example 2**
102When 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.
103
104```ts
105import { UIAbility } from '@kit.AbilityKit';
106import { BusinessError } from '@kit.BasicServicesKit';
107
108export default class EntryAbility extends UIAbility {
109  value: number = 12;
110
111  onCreate() {
112    try {
113      // Anonymous functions can be used to subscribe to events.
114      this.context.eventHub.on('myEvent', () => {
115        console.log(`anonymous eventFunc is called, value: ${this.value}`);
116      });
117    } catch (e) {
118      let code: number = (e as BusinessError).code;
119      let msg: string = (e as BusinessError).message;
120      console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
121    }
122  }
123
124  onForeground() {
125    try {
126      // Result
127      // anonymous eventFunc is called, value: 12
128      this.context.eventHub.emit('myEvent');
129    } catch (e) {
130      let code: number = (e as BusinessError).code;
131      let msg: string = (e as BusinessError).message;
132      console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
133    }
134  }
135
136  eventFunc() {
137    console.log(`eventFunc is called, value: ${this.value}`);
138  }
139}
140```
141
142## EventHub.off
143
144off(event: string, callback?: Function): void;
145
146Unsubscribes from an event.
147 - If **callback** is specified, this API unsubscribes from the given event with the specified callback.
148 - If **callback** is not specified, this API unsubscribes from the given event with all callbacks.
149
150**Atomic service API**: This API can be used in atomic services since API version 11.
151
152**System capability**: SystemCapability.Ability.AbilityRuntime.Core
153
154**Parameters**
155
156| Name| Type| Mandatory| Description|
157| -------- | -------- | -------- | -------- |
158| event | string | Yes| Event name.|
159| callback | Function | No| Callback for the event. If **callback** is unspecified, the given event with all callbacks is unsubscribed.|
160
161**Error codes**
162
163For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
164
165| ID| Error Message|
166| ------- | -------- |
167| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
168
169**Example**
170
171```ts
172import { UIAbility } from '@kit.AbilityKit';
173import { BusinessError } from '@kit.BasicServicesKit';
174
175export default class EntryAbility extends UIAbility {
176  onCreate() {
177    try {
178      this.context.eventHub.on('myEvent', this.eventFunc1);
179      this.context.eventHub.off('myEvent', this.eventFunc1); // Unsubscribe from the myEvent event with the callback eventFunc1.
180      this.context.eventHub.on('myEvent', this.eventFunc1);
181      this.context.eventHub.on('myEvent', this.eventFunc2);
182      this.context.eventHub.off('myEvent'); // Unsubscribe from the myEvent event with all the callbacks (eventFunc1 and eventFunc2).
183    } catch (e) {
184      let code: number = (e as BusinessError).code;
185      let msg: string = (e as BusinessError).message;
186      console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
187    }
188  }
189
190  eventFunc1() {
191    console.log('eventFunc1 is called');
192  }
193
194  eventFunc2() {
195    console.log('eventFunc2 is called');
196  }
197}
198```
199
200## EventHub.emit
201
202emit(event: string, ...args: Object[]): void;
203
204Triggers an event.
205
206**Atomic service API**: This API can be used in atomic services since API version 11.
207
208**System capability**: SystemCapability.Ability.AbilityRuntime.Core
209
210**Parameters**
211
212| Name| Type| Mandatory| Description|
213| -------- | -------- | -------- | -------- |
214| event | string | Yes| Event name.|
215| ...args | Object[] | No| Variable parameters, which are passed to the callback when the event is triggered.|
216
217**Error codes**
218
219For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
220
221| ID| Error Message|
222| ------- | -------- |
223| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
224
225**Example**
226
227```ts
228import { UIAbility } from '@kit.AbilityKit';
229import { BusinessError } from '@kit.BasicServicesKit';
230
231export default class EntryAbility extends UIAbility {
232  onCreate() {
233    this.context.eventHub.on('myEvent', this.eventFunc);
234  }
235
236  onDestroy() {
237    try {
238      // Result
239      // eventFunc is called,undefined,undefined
240      this.context.eventHub.emit('myEvent');
241      // Result
242      // eventFunc is called,1,undefined
243      this.context.eventHub.emit('myEvent', 1);
244      // Result
245      // eventFunc is called,1,2
246      this.context.eventHub.emit('myEvent', 1, 2);
247    } catch (e) {
248      let code: number = (e as BusinessError).code;
249      let msg: string = (e as BusinessError).message;
250      console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
251    }
252  }
253
254  eventFunc(argOne: number, argTwo: number) {
255    console.log(`eventFunc is called, ${argOne}, ${argTwo}`);
256  }
257}
258```
259