1# @ohos.commonEventManager (公共事件模块)(系统应用) 2 3本模块提供了公共事件相关的能力，包括发布公共事件、订阅公共事件、以及退订公共事件。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 当前界面仅包含本模块的系统接口，其他公开接口参见[CommonEventManager](./js-apis-commonEventManager.md)。 10 11## 导入模块 12 13```ts 14import CommonEventManager from '@ohos.commonEventManager'; 15``` 16 17## Support 18 19系统公共事件是指由系统服务或系统应用发布的事件，订阅这些系统公共事件需要特定的权限。发布或订阅这些事件需要使用如下链接中的枚举定义。 20 21全部系统公共事件枚举定义请参见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 22 23## CommonEventManager.publishAsUser<sup> 24 25publishAsUser(event: string, userId: number, callback: AsyncCallback\<void>): void 26 27以回调的形式向指定用户发布公共事件。 28 29**系统能力：** SystemCapability.Notification.CommonEvent 30 31**系统API**：此接口为系统接口，三方应用不支持调用。 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| -------- | -------------------- | ---- | ---------------------------------- | 37| event | string | 是 | 表示要发送的公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 38| userId | number | 是 | 表示指定向该用户ID发送此公共事件。 | 39| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 40 41**错误码：** 42 43错误码介绍请参考[@ohos.commonEventManager(事件)](./errorcode-CommonEventService.md) 44 45| 错误码ID | 错误信息 | 46| -------- | ----------------------------------- | 47| 1500004 | not System services. | 48| 1500007 | error sending message to Common Event Service. | 49| 1500008 | Common Event Service does not complete initialization. | 50| 1500009 | error obtaining system parameters. | 51 52**示例：** 53 54```ts 55import Base from '@ohos.base'; 56 57//发布公共事件回调 58function publishCB(err:Base.BusinessError) { 59 if (err) { 60 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 61 } else { 62 console.info("publishAsUser"); 63 } 64} 65 66//指定发送的用户 67let userId = 100; 68 69//发布公共事件 70try { 71 CommonEventManager.publishAsUser("event", userId, publishCB); 72} catch (error) { 73 let err:Base.BusinessError = error as Base.BusinessError; 74 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 75} 76``` 77 78## CommonEventManager.publishAsUser 79 80publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\<void>): void 81 82以回调形式向指定用户发布公共事件并指定发布信息。 83 84**系统能力：** SystemCapability.Notification.CommonEvent 85 86**系统API**：此接口为系统接口，三方应用不支持调用。 87 88**参数：** 89 90| 参数名 | 类型 | 必填 | 说明 | 91| -------- | ---------------------- | ---- | ---------------------- | 92| event | string | 是 | 表示要发布的公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 93| userId | number | 是 | 表示指定向该用户ID发送此公共事件。 | 94| options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是 | 表示发布公共事件的属性。 | 95| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 96 97**错误码：** 98 99错误码介绍请参考[@ohos.commonEventManager(事件)](./errorcode-CommonEventService.md) 100 101| 错误码ID | 错误信息 | 102| -------- | ----------------------------------- | 103| 1500004 | not System services or System app. | 104| 1500007 | error sending message to Common Event Service. | 105| 1500008 | Common Event Service does not complete initialization. | 106| 1500009 | error obtaining system parameters. | 107 108**示例：** 109 110 111```ts 112import Base from '@ohos.base'; 113 114//公共事件相关信息 115let options:CommonEventManager.CommonEventPublishData = { 116 code: 0, //公共事件的初始代码 117 data: "initial data",//公共事件的初始数据 118} 119 120//发布公共事件回调 121function publishCB(err:Base.BusinessError) { 122 if (err) { 123 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 124 } else { 125 console.info("publishAsUser"); 126 } 127} 128 129//指定发送的用户 130let userId = 100; 131 132//发布公共事件 133try { 134 CommonEventManager.publishAsUser("event", userId, options, publishCB); 135} catch (error) { 136 let err:Base.BusinessError = error as Base.BusinessError; 137 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 138} 139``` 140 141## CommonEventManager.removeStickyCommonEvent<sup>10+</sup> 142 143removeStickyCommonEvent(event: string, callback: AsyncCallback\<void>): void 144 145以回调形式移除粘性公共事件。 146 147**系统能力：** SystemCapability.Notification.CommonEvent 148 149**需要权限**: ohos.permission.COMMONEVENT_STICKY 150 151**系统API**：此接口为系统接口，三方应用不支持调用。 152 153**参数：** 154 155| 参数名 | 类型 | 必填 | 说明 | 156| -------- | -------------------- | ---- | -------------------------------- | 157| event | string | 是 | 表示被移除的粘性公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 158| callback | AsyncCallback\<void> | 是 | 表示移除粘性公共事件的回调方法。 | 159 160**错误码：** 161 162错误码介绍请参考[@ohos.commonEventManager(事件)](./errorcode-CommonEventService.md) 163 164| 错误码ID | 错误信息 | 165| -------- | ----------------------------------- | 166| 1500004 | not system service. | 167| 1500007 | error sending message to Common Event Service. | 168| 1500008 | Common Event Service does not complete initialization. | 169 170**示例：** 171 172 173```ts 174import Base from '@ohos.base'; 175 176CommonEventManager.removeStickyCommonEvent("sticky_event", (err:Base.BusinessError) => { 177 if (err) { 178 console.info(`Remove sticky event AsyncCallback failed, errCode: ${err.code}, errMes: ${err.message}`); 179 return; 180 } 181 console.info(`Remove sticky event AsyncCallback success`); 182}); 183``` 184 185## CommonEventManager.removeStickyCommonEvent<sup>10+</sup> 186 187removeStickyCommonEvent(event: string): Promise\<void> 188 189以Promise形式移除粘性公共事件。 190 191**系统能力：** SystemCapability.Notification.CommonEvent 192 193**需要权限**: ohos.permission.COMMONEVENT_STICKY 194 195**系统API**：此接口为系统接口，三方应用不支持调用。 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| ------ | ------ | ---- | -------------------------- | 201| event | string | 是 | 表示被移除的粘性公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 202 203**返回值：** 204 205| 类型 | 说明 | 206| -------------- | ---------------------------- | 207| Promise\<void> | 表示移除粘性公共事件的对象。 | 208 209**错误码：** 210 211错误码介绍请参考[@ohos.commonEventManager(事件)](./errorcode-CommonEventService.md) 212 213| 错误码ID | 错误信息 | 214| -------- | ----------------------------------- | 215| 1500004 | not system service. | 216| 1500007 | error sending message to Common Event Service. | 217| 1500008 | Common Event Service does not complete initialization. | 218 219**示例：** 220 221 222```ts 223import Base from '@ohos.base'; 224 225CommonEventManager.removeStickyCommonEvent("sticky_event").then(() => { 226 console.info(`Remove sticky event AsyncCallback success`); 227}).catch ((err:Base.BusinessError) => { 228 console.info(`Remove sticky event AsyncCallback failed, errCode: ${err.code}, errMes: ${err.message}`); 229}); 230``` 231 232## CommonEventManager.setStaticSubscriberState<sup>10+</sup> 233 234setStaticSubscriberState(enable: boolean, callback: AsyncCallback\<void>): void; 235 236方法介绍：为当前应用设置静态订阅事件使能或去使能状态。使用callback异步回调。 237 238**模型约束**：此接口仅可在Stage模型下使用。 239 240**系统能力：** SystemCapability.Notification.CommonEvent 241 242**系统API**：此接口为系统接口，三方应用不支持调用。 243 244**参数：** 245 246| 参数名 | 类型 | 必填 | 说明 | 247| ------ | ------ | ---- | -------------------------- | 248| enable | boolean | 是 | 表示静态订阅事件使能状态。 true:使能 false：去使能。 | 249| callback | AsyncCallback\<void> | 是 | 表示设置静态订阅事件使能状态的回调方法。 | 250 251**错误码：** 252 253错误码介绍请参考[@ohos.commonEventManager(事件)](./errorcode-CommonEventService.md) 254 255| 错误码ID | 错误信息 | 256| -------- | ----------------------------------- | 257| 1500007 | error sending message to Common Event Service. | 258| 1500008 | Common Event Service does not complete initialization. | 259 260**示例：** 261 262 263```ts 264import Base from '@ohos.base'; 265 266CommonEventManager.setStaticSubscriberState(true, (err:Base.BusinessError) => { 267 if (!err) { 268 console.info(`Set static subscriber state callback failed, err is null.`); 269 return; 270 } 271 if (err.code !== undefined && err.code != null) { 272 console.info(`Set static subscriber state callback failed, errCode: ${err.code}, errMes: ${err.message}`); 273 return; 274 } 275 console.info(`Set static subscriber state callback success`); 276}); 277``` 278 279## CommonEventManager.setStaticSubscriberState<sup>10+</sup> 280 281setStaticSubscriberState(enable: boolean): Promise\<void>; 282 283方法介绍：为当前应用设置静态订阅事件使能或去使能状态。使用Promise异步回调。 284 285**模型约束**：此接口仅可在Stage模型下使用。 286 287**系统能力：** SystemCapability.Notification.CommonEvent 288 289**系统API**：此接口为系统接口，三方应用不支持调用。 290 291**参数：** 292 293| 参数名 | 类型 | 必填 | 说明 | 294| ------ | ------ | ---- | -------------------------- | 295| enable | boolean | 是 | 表示静态订阅事件使能状态。 true:使能 false：去使能。 | 296 297**返回值：** 298 299| 类型 | 说明 | 300| -------------- | ---------------------------- | 301| Promise\<void> | 表示设置静态订阅事件使能状态的对象。 | 302 303**错误码：** 304 305错误码介绍请参考[@ohos.commonEventManager(事件)](./errorcode-CommonEventService.md) 306 307| 错误码ID | 错误信息 | 308| -------- | ----------------------------------- | 309| 1500007 | error sending message to Common Event Service. | 310| 1500008 | Common Event Service does not complete initialization. | 311 312**示例：** 313 314 315```ts 316import Base from '@ohos.base'; 317 318CommonEventManager.setStaticSubscriberState(false).then(() => { 319 console.info(`Set static subscriber state promise success`); 320}).catch ((err:Base.BusinessError) => { 321 console.info(`Set static subscriber state promise failed, errCode: ${err.code}, errMes: ${err.message}`); 322}); 323``` 324