一、为什么需要公共事件？

开发 OpenHarmony 应用时，组件之间经常需要传递"状态变化"消息，典型场景：

1. 跨页面通知：A 页面设备状态变了，B 页面需要同步刷新，但两个页面没有直接的引用关系；
2. 跨 Ability/跨应用广播：一个模块采集到的数据，需要分发给多个订阅方（如测试框架收集用例结果）；
3. 监听系统事件：蓝牙开关变化、网络连接变化、屏幕亮灭等系统级事件。

如果全部用全局变量、回调注册表或 EventHub 硬编码，会出现耦合严重、生命周期管理混乱、跨应用无法通信的问题。公共事件（CommonEvent）机制就是官方提供的发布-订阅解耦方案：发布方不需要知道谁在听，订阅方按事件名匹配即可。

二、哪些场景适合用？

三、核心机制

3.1 发布-订阅模型

发布方 publish(event, options)
        │
        ▼
  ┌──────────────────┐
  │ 系统公共事件服务   │ 事件名匹配 + 权限校验
  └──────────────────┘
        │
        ▼
订阅方 createSubscriber + subscribe → onReceive 回调

• 发布方调用 publish 发送事件，不需要知道订阅方是谁；
• 订阅方创建订阅者（Subscriber）并声明感兴趣的事件名（可多个），系统按事件名分发；
• 事件通过系统进程中转，天然支持跨进程/跨应用。

3.2 两种订阅方式

3.3 事件类型

• 普通事件：发布后即时分发，无序；
• 有序事件：options.isOrdered 为 true，订阅者按订阅顺序依次收到，可中断后续分发；
• 粘性事件：options.isSticky 为 true，事件持久保留，后订阅者也能立刻收到最新一条。

四、核心 API

五、示例

5.1 场景说明

• 业务模块采集到"设备状态变化"后发布公共事件；
• 页面订阅该事件实时刷新 UI，页面销毁时取消订阅，避免泄漏。

5.2 发布公共事件

import commonEventManager from '@ohos.commonEventManager';

const EVENT_DEVICE_STATE_CHANGED = 'usual.event.DEVICE_STATE_CHANGED'; // 建议使用 usual.event 前缀

export function publishDeviceStateChanged(state: Record<string, Object>): void {
  let options: commonEventManager.CommonEventPublishData = {
    code: 0,
    data: JSON.stringify(state),   // 业务数据放 data 字段
    isOrdered: false,
    isSticky: false
  };
  commonEventManager.publish(EVENT_DEVICE_STATE_CHANGED, options, (err) => {
    if (err) {
      console.error('publish failed, code is ' + err.code + ', message is ' + err.message);
    } else {
      console.info('publish success');
    }
  });
}

5.3 订阅公共事件（页面侧）

import commonEventManager from '@ohos.commonEventManager';
import { BusinessError } from '@kit.BasicServicesKit';

export class DeviceEventSubscriber {
  private subscriber: commonEventManager.CommonEventSubscriber | null = null;

  /** 订阅事件：传入回调，事件到达时触发 */
  public async subscribe(onEvent: (data: string) => void): Promise<void> {
    let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
      events: [EVENT_DEVICE_STATE_CHANGED]   // 声明订阅的事件名
    };
    try {
      // 1. 创建订阅者
      this.subscriber = await commonEventManager.createSubscriber(subscribeInfo);
      // 2. 开始订阅
      await commonEventManager.subscribe(this.subscriber, (err, data) => {
        if (err) {
          console.error('receive failed, code is ' + err.code);
          return;
        }
        // data.event 为事件名，data.data 为发布时携带的数据
        onEvent(data.data ?? '');
      });
    } catch (e) {
      let err = e as BusinessError;
      console.error('subscribe failed, code is ' + err.code + ', message is ' + err.message);
    }
  }

  /** 取消订阅：页面销毁时必须调用，防止泄漏 */
  public async unsubscribe(): Promise<void> {
    if (this.subscriber) {
      await commonEventManager.unsubscribe(this.subscriber);
      this.subscriber = null;
    }
  }
}

5.4 在页面生命周期中使用

@Entry
@Component
struct DevicePage {
  private eventSubscriber: DeviceEventSubscriber = new DeviceEventSubscriber();
  @State deviceState: string = '';

  async aboutToAppear() {
    // 页面出现时注册订阅
    await this.eventSubscriber.subscribe((data: string) => {
      this.deviceState = data;   // 事件到达刷新 UI
    });
  }

  aboutToDisappear() {
    // 页面销毁时注销订阅（关键：避免订阅泄漏）
    this.eventSubscriber.unsubscribe();
  }

  build() {
    Text('设备状态: ' + this.deviceState);
  }
}

5.5 订阅系统公共事件（如蓝牙开关变化）

import { bluetoothManager } from '@kit.ConnectivityKit';
import commonEventManager from '@ohos.commonEventManager';

export function watchBluetoothState(onChanged: (state: number) => void): void {
  // 订阅系统蓝牙状态变化事件（系统事件免自定义发布方）
  let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
    events: [commonEventManager.CommonEventSupport.COMMON_EVENT_BLUETOOTH_STATE_CHANGED]
  };
  commonEventManager.createSubscriber(subscribeInfo, (err, subscriber) => {
    if (err) {
      console.error('createSubscriber failed');
      return;
    }
    commonEventManager.subscribe(subscriber, (err, data) => {
      // 解析系统携带的状态参数
      let state = (data.parameters as Record<string, number>)['state'] ?? -1;
      onChanged(state);
    });
  });
}

六、常见问题与踩坑总结