1# EventHub
2
3EventHub模块提供了事件中心，提供订阅、取消订阅、触发事件的能力。
4
5> **说明：**
6>
7>  - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。  
8>  - 本模块接口仅可在Stage模型下使用。
9
10## 导入模块
11
12```ts
13import { common } from '@kit.AbilityKit';
14```
15
16## 使用说明
17
18在使用eventHub的功能前，需要通过UIAbility实例的成员变量context获取。
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不是全局的事件中心，不同的context对象拥有不同的EventHub对象，事件的订阅、取消订阅、触发都作用在某一个具体的EventHub对象上，因此不能用于虚拟机间或者进程间的事件传递。
34
35## EventHub.on
36
37on(event: string, callback: Function): void;
38
39订阅指定事件。
40> **说明：**
41>
42>  callback被emit触发时，调用方是EventHub对象，如果要修改callback中this的指向，可以使用箭头函数。
43
44**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
45
46**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
47
48**参数：**
49
50| 参数名 | 类型 | 必填 | 说明 |
51| -------- | -------- | -------- | -------- |
52| event | string | 是 | 事件名称。 |
53| callback | Function | 是 | 事件回调，事件触发后调用。 |
54
55**错误码**：
56
57以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
58
59| 错误码ID | 错误信息 |
60| ------- | -------- |
61| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
62
63**示例1：**
64callback被emit触发时，调用方是EventHub对象。EventHub对象没有value属性，因此结果是undefined。
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    // 结果：
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**示例2：**
90callback使用箭头函数时，调用方是EntryAbility对象。EntryAbility对象里存在value属性，因此结果是12。
91
92```ts
93import { UIAbility } from '@kit.AbilityKit';
94
95export default class EntryAbility extends UIAbility {
96  value: number = 12;
97
98  onCreate() {
99    // 支持使用匿名函数订阅事件
100    this.context.eventHub.on('myEvent', () => {
101      console.log(`anonymous eventFunc is called, value: ${this.value}`);
102    });
103  }
104
105  onForeground() {
106    // 结果：
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
121取消订阅指定事件。
122 - 传入callback：取消指定的callback对指定事件的订阅，当该事件触发后，将不会回调该callback。
123 - 不传callback：取消所有callback对指定事件的订阅。
124
125**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
126
127**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
128
129**参数：**
130
131| 参数名 | 类型 | 必填 | 说明 |
132| -------- | -------- | -------- | -------- |
133| event | string | 是 | 事件名称。 |
134| callback | Function | 否 | 事件回调。如果不传callback，则取消订阅该事件下所有callback。 |
135
136**错误码**：
137
138以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
139
140| 错误码ID | 错误信息 |
141| ------- | -------- |
142| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
143
144**示例：**
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); // 取消eventFunc1对myEvent事件的订阅
153    this.context.eventHub.on('myEvent', this.eventFunc1);
154    this.context.eventHub.on('myEvent', this.eventFunc2);
155    this.context.eventHub.off('myEvent'); // 取消eventFunc1和eventFunc2对myEvent事件的订阅
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
172触发指定事件。
173
174**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
175
176**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
177
178**参数：**
179
180| 参数名 | 类型 | 必填 | 说明 |
181| -------- | -------- | -------- | -------- |
182| event | string | 是 | 事件名称。 |
183| ...args | Object[] | 否 | 可变参数，事件触发时，传递给回调函数的参数。 |
184
185**错误码**：
186
187以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
188
189| 错误码ID | 错误信息 |
190| ------- | -------- |
191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
192
193**示例：**
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    // 结果：
205    // eventFunc is called,undefined,undefined
206    this.context.eventHub.emit('myEvent');
207    // 结果：
208    // eventFunc is called,1,undefined
209    this.context.eventHub.emit('myEvent', 1);
210    // 结果：
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