企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

本文围绕仓颉（Cangjie）语言 BasicServicesKit 套件中的CommonEventSubscribeInfo类展开，讲解这个用于描述公共事件（CES，Common Event Service）订阅者信息的 API 的完整字段语义、构造参数与默认值。读完本篇，你将能够正确构建订阅者信息对象，并结合CommonEventManager.createSubscriber/subscribe/unsubscribe完成一套可运行、可退订的动态公共事件订阅方案，同时理解优先级、发布者权限过滤等参数在事件分发与安全控制中的实际作用。

1. CommonEventSubscribeInfo 在公共事件体系中的位置

CES 为应用提供订阅、发布、退订公共事件的能力（见 公共事件简介）。其中公共事件按发送方式可分为无序、有序和粘性三类，而CommonEventSubscribeInfo正是"动态订阅"这一流程的输入：

1. 构造CommonEventSubscribeInfo，声明要订阅的事件列表及过滤条件；
2. 调用CommonEventManager.createSubscriber(subscribeInfo)创建订阅者对象CommonEventSubscriber（见 动态订阅公共事件）；
3. 调用CommonEventManager.subscribe(subscriber, callback)开始接收事件；
4. 业务结束后调用CommonEventManager.unsubscribe(subscriber)取消订阅，避免订阅者对象内存泄漏。

上述管理类接口的完整定义见 ohos.common_event_manager（公共事件模块）。

2. 类定义与构造器

CommonEventSubscribeInfo通过import kit.BasicServicesKit.*导入，其完整声明如下（系统能力：SystemCapability.Notification.CommonEvent，起始版本：22）：

public class CommonEventSubscribeInfo { public var events: Array<String> public var priority: Int32 public var userId: Int32 public var publisherPermission: String public var publisherDeviceId: String public var publisherBundleName: String public init( events: Array<String>, publisherPermission!: String = "", publisherDeviceId!: String = "", userId!: Int32 = UNDEFINED_USER, priority!: Int32 = 0, publisherBundleName!: String = "" ) }

该类用于表示订阅者的信息，即"谁（哪个用户）、以什么优先级、只接收哪些发布者发布的事件"。其构造器init(Array<String>, String, String, Int32, Int32, String)用于构造CommonEventSubscribeInfo对象，参数如下：

从声明可以看出，只有events是必填的位置参数，其余均为带默认值的命名参数（!为仓颉命名参数标记），因此最简单的用法是CommonEventSubscribeInfo([eventName])。

3. 字段详解

3.1 var events：订阅的事件列表

public var events: Array<String>

功能：表示要订阅的公共事件。类型：Array<String>。读写能力：可读写。系统能力：SystemCapability.Notification.CommonEvent。起始版本：22。

events中的每个元素是事件名称字符串。订阅系统公共事件时，应使用Support类中定义的常量而非手写字符串。Support类提供了大量系统事件常量，例如：

public static const COMMON_EVENT_BATTERY_LOW: String = "usual.event.BATTERY_LOW" public static const COMMON_EVENT_SCREEN_ON: String = "usual.event.SCREEN_ON" public static const COMMON_EVENT_AIRPLANE_MODE_CHANGED: String = "usual.event.AIRPLANE_MODE" public static const COMMON_EVENT_NETWORK_STATE_CHANGED: String = "usual.event.NETWORK_STATE_CHANGED"

完整常量列表见 系统定义的公共事件（class Support）。需要注意，部分常量标注为"预留事件，暂未支持"（如COMMON_EVENT_ABILITY_ADDED、多数蓝牙事件等），接入前应先确认目标事件是否已支持。

3.2 var priority：订阅者优先级

public var priority: Int32

功能：表示订阅者的优先级。值的范围是 -100 到 1000，超过上下限的优先级将被设置为上下限值。类型：Int32，可读写，起始版本 22。

priority在有序公共事件的场景下才真正发挥作用：CES 在转发有序公共事件时，会优先将事件发送给优先级较高的订阅者，等待其成功接收后再发给优先级较低的订阅者；若多个订阅者优先级相同，则它们将随机接收到事件（见 公共事件运作机制）。默认值为 0，即不显式设置时所有订阅者处于同一优先级。

3.3 var publisherPermission：发布者权限过滤

public var publisherPermission: String

功能：表示发布者的权限，订阅方将只能接收到具有该权限的发送方发布的事件。类型：String，可读写，起始版本 22。

这是订阅方的安全手段之一。订阅自定义公共事件后，任意应用都可能向该事件名发送潜在的恶意公共事件；通过设置publisherPermission，可以要求发布者必须持有指定权限，从而限制事件来源的可信范围。

3.4 var publisherBundleName：发布者包名过滤

public var publisherBundleName: String

功能：表示要订阅的发布者的 bundleName。类型：String，可读写，起始版本 22。

与publisherPermission配合，publisherBundleName可将接收范围精确限定到某个具体应用，是订阅方限制发布方范围的另一种方式。

3.5 var publisherDeviceId：设备 ID（预留）

public var publisherDeviceId: String

功能：表示设备ID。通过@ohos.deviceInfo获取 udid，作为订阅者的设备ID。预留能力，暂不支持。类型：String，可读写，起始版本 22。

该字段为跨设备订阅预留的扩展点，当前版本不可用，接入代码中保持默认空字符串即可。

3.6 var userId：用户 ID

public var userId: Int32

功能：表示用户ID。此参数是可选的，默认值为当前用户的ID。如果指定了此参数，则该值必须是系统中现有的用户ID。类型：Int32，可读写，起始版本 22。

构造器默认值为UNDEFINED_USER，即沿用当前用户。多用户设备上如需订阅其他用户空间下的事件，才需要显式传入合法的系统用户ID；传入无效值会触发错误码 1500006（Invalid userId，见 事件错误码）。

4. 实战：用 CommonEventSubscribeInfo 完成一次动态订阅

结合 动态订阅公共事件 的开发步骤，一个典型的动态订阅流程如下。订阅者信息中的event字段需要替换为实际的事件名称：

import kit.BasicServicesKit.* import kit.PerformanceAnalysisKit.Hilog import ohos.base.* import ohos.business_exception.* // 订阅者信息，其中events字段需要替换为实际的事件名称 let support1 = Support.COMMON_EVENT_SCREEN_ON let events = [support1] let subscribeInfo = CommonEventSubscribeInfo(events) // 创建订阅者，保存返回的subscriber，用于后续订阅、退订、接收事件回调 try { let subscriber = CommonEventManager.createSubscriber(subscribeInfo) // 订阅回调函数会在接收到事件时触发 let callback = { a: ?BusinessException, b: ?CommonEventData => Hilog.info(0, "TestCEM", "callback excute success!") } CommonEventManager.subscribe(subscriber, callback) } catch (e: BusinessException) { Hilog.error(0, "AppLogCj", "errorCode = ${e.code}, errorMsg = ${e.message}") }

回调收到的事件数据由CommonEventData描述，包含事件名event、发布者携带的data（String）、code（Int32）、bundleName及parameters（附加信息）等字段，详见 ohos.common_event_data。

业务结束后必须主动取消订阅（订阅者对象的生命周期需要接入方管理，不再使用时需主动销毁释放，避免内存泄漏）：

CommonEventManager.unsubscribe(subscriber)

完整退订流程与代码见 取消动态订阅公共事件。

4.1 关键接口的异常行为

使用CommonEventSubscribeInfo创建订阅者并订阅时，主要涉及以下接口与错误码：

其中 1500010 提示系统对订阅者数量有上限，长期不unsubscribe的订阅者会占用配额。模块特有的更多错误码（如 1500005 未找到订阅者、1500006 无效 userId）及处理步骤，见 事件错误码。

5. 安全注意事项

CommonEventSubscribeInfo的两个过滤字段本质上是公共事件的安全边界（见 公共事件安全注意事项）：

• 公共事件发布方：如果不加限制，任何应用都可以订阅公共事件并读取相关信息，应避免在公共事件中携带敏感信息。可通过发布侧的CommonEventPublishData中的subscriberPermissions、bundleName参数限制接收方范围；
• 公共事件订阅方：订阅自定义公共事件后，任意应用都可以向订阅者发送潜在的恶意公共事件。应通过CommonEventSubscribeInfo中的publisherPermission指定发布者所需权限、通过publisherBundleName指定发布者的包名，限制发布方范围；
• 自定义公共事件名称应确保全局唯一，否则可能与其他公共事件冲突。

此外，订阅部分系统公共事件需要先申请相应权限，申请方式参见 判断应用模式与权限。

6. 小结

CommonEventSubscribeInfo是仓颉 BasicServicesKit 公共事件订阅链路的入口数据结构：events决定"监听什么"，priority决定有序事件分发顺序，publisherPermission/publisherBundleName决定"只信任谁"，userId/publisherDeviceId分别处理多用户与跨设备场景（后者当前为预留能力）。掌握其字段语义后，再按"构造信息 → createSubscriber → subscribe → unsubscribe"的流程组织代码，即可获得一套完整、安全、可回收的动态公共事件订阅能力。相关文档可进一步查阅：

• ohos.common_event_subscribe_info（本文档源）
• ohos.common_event_manager（公共事件模块）
• ohos.common_event_subscriber
• ohos.common_event_data
• 发布公共事件

• 文档
• 知识库
• 教程
• OpenHarmony