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 应用中有效地实现事件驱动的编程逻辑，增强应用的交互性和灵活性。