文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载本文围绕仓颉Cangjie语言 BasicServicesKit 套件中的CommonEventSubscribeInfo类展开讲解这个用于描述公共事件CESCommon Event Service订阅者信息的 API 的完整字段语义、构造参数与默认值。读完本篇你将能够正确构建订阅者信息对象并结合CommonEventManager.createSubscriber/subscribe/unsubscribe完成一套可运行、可退订的动态公共事件订阅方案同时理解优先级、发布者权限过滤等参数在事件分发与安全控制中的实际作用。1. CommonEventSubscribeInfo 在公共事件体系中的位置CES 为应用提供订阅、发布、退订公共事件的能力见 公共事件简介。其中公共事件按发送方式可分为无序、有序和粘性三类而CommonEventSubscribeInfo正是动态订阅这一流程的输入构造CommonEventSubscribeInfo声明要订阅的事件列表及过滤条件调用CommonEventManager.createSubscriber(subscribeInfo)创建订阅者对象CommonEventSubscriber见 动态订阅公共事件调用CommonEventManager.subscribe(subscriber, callback)开始接收事件业务结束后调用CommonEventManager.unsubscribe(subscriber)取消订阅避免订阅者对象内存泄漏。上述管理类接口的完整定义见 ohos.common_event_manager公共事件模块。2. 类定义与构造器CommonEventSubscribeInfo通过import kit.BasicServicesKit.*导入其完整声明如下系统能力SystemCapability.Notification.CommonEvent起始版本22public class CommonEventSubscribeInfo { public var events: ArrayString public var priority: Int32 public var userId: Int32 public var publisherPermission: String public var publisherDeviceId: String public var publisherBundleName: String public init( events: ArrayString, publisherPermission!: String , publisherDeviceId!: String , userId!: Int32 UNDEFINED_USER, priority!: Int32 0, publisherBundleName!: String ) }该类用于表示订阅者的信息即谁哪个用户、以什么优先级、只接收哪些发布者发布的事件。其构造器init(ArrayString, String, String, Int32, Int32, String)用于构造CommonEventSubscribeInfo对象参数如下参数名类型必填默认值说明eventsArrayString是-表示要订阅的公共事件。publisherPermissionString否命名参数。表示发布者的权限订阅方将只能接收到具有该权限的发送方发布的事件。publisherDeviceIdString否命名参数。表示设备ID。通过ohos.deviceInfo获取 udid作为订阅者的设备ID。预留能力暂不支持。userIdInt32否UNDEFINED_USER命名参数。表示用户ID。此参数是可选的默认值为当前用户的ID。如果指定了此参数则该值必须是系统中现有的用户ID。priorityInt32否0命名参数。表示订阅者的优先级。值的范围是 -100 到 1000超过上下限的优先级将被设置为上下限值。publisherBundleNameString否命名参数。表示要订阅的发布者的 bundleName。从声明可以看出只有events是必填的位置参数其余均为带默认值的命名参数!为仓颉命名参数标记因此最简单的用法是CommonEventSubscribeInfo([eventName])。3. 字段详解3.1 var events订阅的事件列表public var events: ArrayString功能表示要订阅的公共事件。类型ArrayString。读写能力可读写。系统能力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用户 IDpublic var userId: Int32功能表示用户ID。此参数是可选的默认值为当前用户的ID。如果指定了此参数则该值必须是系统中现有的用户ID。类型Int32可读写起始版本 22。构造器默认值为UNDEFINED_USER即沿用当前用户。多用户设备上如需订阅其他用户空间下的事件才需要显式传入合法的系统用户ID传入无效值会触发错误码 1500006Invalid 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、发布者携带的dataString、codeInt32、bundleName及parameters附加信息等字段详见 ohos.common_event_data。业务结束后必须主动取消订阅订阅者对象的生命周期需要接入方管理不再使用时需主动销毁释放避免内存泄漏CommonEventManager.unsubscribe(subscriber)完整退订流程与代码见 取消动态订阅公共事件。4.1 关键接口的异常行为使用CommonEventSubscribeInfo创建订阅者并订阅时主要涉及以下接口与错误码接口可能的 BusinessException 错误码createSubscriber1500008Common Event Service does not complete initializationsubscribe801Capability not supported1500007Failed to send the message to the common event service1500008Failed to initialize the common event service1500010The count of subscriber exceed system specificationunsubscribe801Capability not supported15000071500008其中 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_subscriberohos.common_event_data发布公共事件赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉语言查询设备电量ohos.battery_infoBasicServicesKit 电量信息模块API 详解仓颉语言查询设备电量ohos.battery_infoBasicServicesKit 电量信息模块API 详解 本篇技术指南围绕 OpenHarmony文档知识库教程OpenHarmonyWayback Machine浏览器扩展给网页存档留一份完整底稿让消失的内容找得回来Wayback Machine浏览器扩展给网页存档留一份完整底稿让消失的内容找得回来 周日深夜我照例点开收藏夹里那篇写了三年的老文章想为手头的新稿子引一前端浏览器控制今日热门项目推荐Cangjie TOML - 仓颉语言生态的TOML解析利器今日热门项目推荐Cangjie TOML 仓颉语言生态的TOML解析利器 项目价值 Cangjie TOML作为仓颉语言生态中的关键组件填补了该语言在配置文后端上一篇MCreator新手入门从零开始解决常见问题下一篇Baekjoon 动态规划入门题集Dynamic Programming 1全解析递推式构建、推荐题单与仓库源码实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/16 2:13:24 · 阅读 1.2k 仓颉（Cangjie）开发指南：深入解析 BasicServicesKit 中 CommonEventSubscribeInfo 订阅者信息类
文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载本文围绕仓颉Cangjie语言 BasicServicesKit 套件中的CommonEventSubscribeInfo类展开讲解这个用于描述公共事件CESCommon Event Service订阅者信息的 API 的完整字段语义、构造参数与默认值。读完本篇你将能够正确构建订阅者信息对象并结合CommonEventManager.createSubscriber/subscribe/unsubscribe完成一套可运行、可退订的动态公共事件订阅方案同时理解优先级、发布者权限过滤等参数在事件分发与安全控制中的实际作用。1. CommonEventSubscribeInfo 在公共事件体系中的位置CES 为应用提供订阅、发布、退订公共事件的能力见 公共事件简介。其中公共事件按发送方式可分为无序、有序和粘性三类而CommonEventSubscribeInfo正是动态订阅这一流程的输入构造CommonEventSubscribeInfo声明要订阅的事件列表及过滤条件调用CommonEventManager.createSubscriber(subscribeInfo)创建订阅者对象CommonEventSubscriber见 动态订阅公共事件调用CommonEventManager.subscribe(subscriber, callback)开始接收事件业务结束后调用CommonEventManager.unsubscribe(subscriber)取消订阅避免订阅者对象内存泄漏。上述管理类接口的完整定义见 ohos.common_event_manager公共事件模块。2. 类定义与构造器CommonEventSubscribeInfo通过import kit.BasicServicesKit.*导入其完整声明如下系统能力SystemCapability.Notification.CommonEvent起始版本22public class CommonEventSubscribeInfo { public var events: ArrayString public var priority: Int32 public var userId: Int32 public var publisherPermission: String public var publisherDeviceId: String public var publisherBundleName: String public init( events: ArrayString, publisherPermission!: String , publisherDeviceId!: String , userId!: Int32 UNDEFINED_USER, priority!: Int32 0, publisherBundleName!: String ) }该类用于表示订阅者的信息即谁哪个用户、以什么优先级、只接收哪些发布者发布的事件。其构造器init(ArrayString, String, String, Int32, Int32, String)用于构造CommonEventSubscribeInfo对象参数如下参数名类型必填默认值说明eventsArrayString是-表示要订阅的公共事件。publisherPermissionString否命名参数。表示发布者的权限订阅方将只能接收到具有该权限的发送方发布的事件。publisherDeviceIdString否命名参数。表示设备ID。通过ohos.deviceInfo获取 udid作为订阅者的设备ID。预留能力暂不支持。userIdInt32否UNDEFINED_USER命名参数。表示用户ID。此参数是可选的默认值为当前用户的ID。如果指定了此参数则该值必须是系统中现有的用户ID。priorityInt32否0命名参数。表示订阅者的优先级。值的范围是 -100 到 1000超过上下限的优先级将被设置为上下限值。publisherBundleNameString否命名参数。表示要订阅的发布者的 bundleName。从声明可以看出只有events是必填的位置参数其余均为带默认值的命名参数!为仓颉命名参数标记因此最简单的用法是CommonEventSubscribeInfo([eventName])。3. 字段详解3.1 var events订阅的事件列表public var events: ArrayString功能表示要订阅的公共事件。类型ArrayString。读写能力可读写。系统能力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用户 IDpublic var userId: Int32功能表示用户ID。此参数是可选的默认值为当前用户的ID。如果指定了此参数则该值必须是系统中现有的用户ID。类型Int32可读写起始版本 22。构造器默认值为UNDEFINED_USER即沿用当前用户。多用户设备上如需订阅其他用户空间下的事件才需要显式传入合法的系统用户ID传入无效值会触发错误码 1500006Invalid 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、发布者携带的dataString、codeInt32、bundleName及parameters附加信息等字段详见 ohos.common_event_data。业务结束后必须主动取消订阅订阅者对象的生命周期需要接入方管理不再使用时需主动销毁释放避免内存泄漏CommonEventManager.unsubscribe(subscriber)完整退订流程与代码见 取消动态订阅公共事件。4.1 关键接口的异常行为使用CommonEventSubscribeInfo创建订阅者并订阅时主要涉及以下接口与错误码接口可能的 BusinessException 错误码createSubscriber1500008Common Event Service does not complete initializationsubscribe801Capability not supported1500007Failed to send the message to the common event service1500008Failed to initialize the common event service1500010The count of subscriber exceed system specificationunsubscribe801Capability not supported15000071500008其中 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_subscriberohos.common_event_data发布公共事件赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉语言查询设备电量ohos.battery_infoBasicServicesKit 电量信息模块API 详解仓颉语言查询设备电量ohos.battery_infoBasicServicesKit 电量信息模块API 详解 本篇技术指南围绕 OpenHarmony文档知识库教程OpenHarmonyWayback Machine浏览器扩展给网页存档留一份完整底稿让消失的内容找得回来Wayback Machine浏览器扩展给网页存档留一份完整底稿让消失的内容找得回来 周日深夜我照例点开收藏夹里那篇写了三年的老文章想为手头的新稿子引一前端浏览器控制今日热门项目推荐Cangjie TOML - 仓颉语言生态的TOML解析利器今日热门项目推荐Cangjie TOML 仓颉语言生态的TOML解析利器 项目价值 Cangjie TOML作为仓颉语言生态中的关键组件填补了该语言在配置文后端上一篇MCreator新手入门从零开始解决常见问题下一篇Baekjoon 动态规划入门题集Dynamic Programming 1全解析递推式构建、推荐题单与仓库源码实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考