HarmonyOS EventHub 模块详解
一、引言
EventHub 模块在 HarmonyOS 应用开发中扮演着重要角色，它提供了事件中心的功能，包括事件订阅、取消订阅以及触发事件等操作，为应用内的模块间通信提供了有效的机制。
二、模块基本信息
- 接口支持版本：首批接口从 API version 9 开始支持，后续版本的新增接口采用上角标单独标记起始版本。
- 适用模型：本模块接口仅可在 Stage 模型下使用。
三、导入模块
在使用 EventHub 功能前，需导入相关模块，使用以下语句：
import { common } from '@kit.AbilityKit';
四、使用说明
- 首先要通过 UIAbility 实例的成员变量
context来获取 EventHub 对象。示例代码如下：
import { UIAbility } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
eventFunc() {
console.log('eventFunc is called');
}
onCreate() {
this.context.eventHub.on('myEvent', this.eventFunc);
}
}
- 需要注意的是，EventHub 不是全局的事件中心，不同的
context对象拥有不同的 EventHub 对象，事件的订阅、取消订阅、触发都作用在某一个具体的 EventHub 对象上，因此不能用于虚拟机间或者进程间的事件传递。
五、EventHub.on 方法
- 功能：用于订阅指定事件。
-
说明：当
callback被emit触发时，调用方是 EventHub 对象，如果要修改callback中this的指向，可以使用箭头函数。从 API version 11 开始，该接口支持在元服务中使用，其系统能力为SystemCapability.Ability.AbilityRuntime.Core。 -
参数：
-
event（必填，string类型）：事件名称。 -
callback（必填，Function类型）：事件回调，事件触发后调用。
-
- 错误码：若出现参数错误，错误码为 401，可能原因包括必填参数未指定、参数类型不正确或参数验证失败，详细参考通用错误码。
-
示例：
- 示例 1：
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
value: number = 12;
onCreate() {
try {
this.context.eventHub.on('myEvent', this.eventFunc);
} catch (e) {
let code: number = (e as BusinessError).code;
let msg: string = (e as BusinessError).message;
console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
}
}
onForeground() {
try {
// 结果：
// eventFunc is called, value: undefined
this.context.eventHub.emit('myEvent');
} catch (e) {
let code: number = (e as BusinessError).code;
let msg: string = (e as BusinessError).message;
console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
}
}
eventFunc() {
console.log(`eventFunc is called, value: ${this.value}`);
}
}
在这个示例中，由于 callback 被 emit 触发时调用方是 EventHub 对象，而 EventHub 对象没有 value 属性，所以结果是 undefined。
- 示例 2：
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
value: number = 12;
onCreate() {
try {
// 支持使用匿名函数订阅事件
this.context.eventHub.on('myEvent', () => {
console.log(`anonymous eventFunc is called, value: ${this.value}`);
});
} catch (e) {
let code: number = (e as BusinessError).code;
let msg: string = (e as BusinessError).message;
console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
}
}
onForeground() {
try {
// 结果：
// anonymous eventFunc is called, value: 12
this.context.eventHub.emit('myEvent');
} catch (e) {
let code: number = (e as BusinessError).code;
let msg: string = (e as BusinessError).message;
console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
}
}
eventFunc() {
console.log(`eventFunc is called, value: ${this.value}`);
}
}
此示例中，callback 使用箭头函数，调用方变为 EntryAbility 对象，该对象存在 value 属性，所以结果是 12。
六、EventHub.off 方法
- 功能：取消订阅指定事件。
-
说明：传入
callback时，取消指定的callback对指定事件的订阅，当该事件触发后，将不会回调该callback；不传callback则取消所有callback对指定事件的订阅。从 API version 11 开始支持在元服务中使用，系统能力为SystemCapability.Ability.AbilityRuntime.Core。 -
参数：
-
event（必填，string类型）：事件名称。 -
callback（可选，Function类型）：事件回调。如果不传callback，则取消订阅该事件下所有callback。
-
- 错误码：参数错误时返回 401，原因同 EventHub.on 方法。
- 示例：
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onCreate() {
try {
this.context.eventHub.on('myEvent', this.eventFunc1);
this.context.eventHub.off('myEvent', this.eventFunc1); // 取消 eventFunc1 对 myEvent 事件的订阅
this.context.eventHub.on('myEvent', this.eventFunc1);
this.context.eventHub.on('myEvent', this.eventFunc2);
this.context.eventHub.off('myEvent'); // 取消 eventFunc1 和 eventFunc2 对 myEvent 事件的订阅
} catch (e) {
let code: number = (e as BusinessError).code;
let msg: string = (e as BusinessError).message;
console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
}
}
eventFunc1() {
console.log('eventFunc1 is called');
}
eventFunc2() {
console.log('eventFunc2 is called');
}
}
七、EventHub.emit 方法
- 功能：触发指定事件。
-
说明：从 API version 11 开始支持在元服务中使用，系统能力为
SystemCapability.Ability.AbilityRuntime.Core。 -
参数：
-
event（必填，string类型）：事件名称。 -
...args（可选，Object[]类型）：可变参数，事件触发时，传递给回调函数的参数。
-
- 错误码：参数错误返回 401。
- 示例：
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onCreate() {
this.context.eventHub.on('myEvent', this.eventFunc);
}
onDestroy() {
try {
// 结果：
// eventFunc is called,undefined,undefined
this.context.eventHub.emit('myEvent');
// 结果：
// eventFunc is called,1,undefined
this.context.eventHub.emit('myEvent', 1);
// 结果：
// eventFunc is called,1,2
this.context.eventHub.emit('myEvent', 1, 2);
} catch (e) {
let code: number = (e as BusinessError).code;
let msg: string = (e as BusinessError).message;
console.error(`EventHub emit error, code: ${code}, msg: ${msg}`);
}
}
eventFunc(argOne: number, argTwo: number) {
console.log(`eventFunc is called, ${argOne}, ${argTwo}`);
}
}
通过对 EventHub 模块的这些方法的了解和运用，开发者可以在 HarmonyOS 应用中有效地实现事件驱动的编程逻辑，增强应用的交互性和灵活性。
