• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 '@ohos.app.ability.common';
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 '@ohos.app.ability.UIAbility';
22
23export default class EntryAbility extends UIAbility {
24    eventFunc(){
25        console.log('eventFunc is called');
26    }
27
28    onForeground() {
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**System capability**: SystemCapability.Ability.AbilityRuntime.Core
45
46**Parameters**
47
48| Name| Type| Mandatory| Description|
49| -------- | -------- | -------- | -------- |
50| event | string | Yes| Event name.|
51| callback | Function | Yes| Callback invoked when the event is triggered.|
52
53**Example**
54
55```ts
56import UIAbility from '@ohos.app.ability.UIAbility';
57
58export default class EntryAbility extends UIAbility {
59    value: number = 12;
60
61    onForeground() {
62        this.context.eventHub.on('myEvent', this.eventFunc);
63        // Anonymous functions can be used to subscribe to events.
64        this.context.eventHub.on('myEvent', () => {
65            console.log(`anonymous eventFunc is called, value: ${this.value}`);
66        });
67        // Result
68        // eventFunc is called, value: undefined
69        // anonymous eventFunc is called, value: 12
70        this.context.eventHub.emit('myEvent');
71    }
72
73    eventFunc() {
74        console.log(`eventFunc is called, value: ${this.value}`);
75    }
76}
77```
78
79## EventHub.off
80
81off(event: string, callback?: Function): void;
82
83Unsubscribes from an event.
84 - If **callback** is specified, this API unsubscribes from the given event with the specified callback.
85 - If **callback** is not specified, this API unsubscribes from the given event with all callbacks.
86
87**System capability**: SystemCapability.Ability.AbilityRuntime.Core
88
89**Parameters**
90
91| Name| Type| Mandatory| Description|
92| -------- | -------- | -------- | -------- |
93| event | string | Yes| Event name.|
94| callback | Function | No| Callback for the event. If **callback** is unspecified, the given event with all callbacks is unsubscribed.|
95
96**Example**
97
98```ts
99import UIAbility from '@ohos.app.ability.UIAbility';
100
101export default class EntryAbility extends UIAbility {
102    onForeground() {
103        this.context.eventHub.on('myEvent', this.eventFunc1);
104        this.context.eventHub.off('myEvent', this.eventFunc1); // Unsubscribe from the myEvent event with the callback eventFunc1.
105        this.context.eventHub.on('myEvent', this.eventFunc1);
106        this.context.eventHub.on('myEvent', this.eventFunc2);
107        this.context.eventHub.off('myEvent');  // Unsubscribe from the myEvent event with all the callbacks (eventFunc1 and eventFunc2).
108    }
109
110    eventFunc1() {
111        console.log('eventFunc1 is called');
112    }
113
114    eventFunc2() {
115        console.log('eventFunc2 is called');
116    }
117}
118```
119
120## EventHub.emit
121
122emit(event: string, ...args: Object[]): void;
123
124Triggers an event.
125
126**System capability**: SystemCapability.Ability.AbilityRuntime.Core
127
128**Parameters**
129
130| Name| Type| Mandatory| Description|
131| -------- | -------- | -------- | -------- |
132| event | string | Yes| Event name.|
133| ...args | Object[] | No| Variable parameters, which are passed to the callback when the event is triggered.|
134
135**Example**
136
137```ts
138import UIAbility from '@ohos.app.ability.UIAbility';
139
140export default class EntryAbility extends UIAbility {
141    onForeground() {
142        this.context.eventHub.on('myEvent', this.eventFunc);
143        // Result
144        // eventFunc is called,undefined,undefined
145        this.context.eventHub.emit('myEvent');
146        // Result
147        // eventFunc is called,1,undefined
148        this.context.eventHub.emit('myEvent', 1);
149        // Result
150        // eventFunc is called,1,2
151        this.context.eventHub.emit('myEvent', 1, 2);
152    }
153
154    eventFunc(argOne: number, argTwo: number) {
155        console.log(`eventFunc is called, ${argOne}, ${argTwo}`);
156    }
157}
158```
159