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 '@kit.BasicServicesKit'; 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以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 44 45| 错误码ID | 错误信息 | 46| -------- | ----------------------------------- | 47| 202 | not system app. | 48| 1500003 | The common event sending frequency too high. | 49| 1500007 | Failed to send the message to the common event service. | 50| 1500008 | Failed to initialize the common event service. | 51| 1500009 | Failed to obtain system parameters. | 52 53**示例：** 54 55```ts 56import { BusinessError } from '@kit.BasicServicesKit'; 57 58//指定发送的用户 59let userId = 100; 60 61//发布公共事件 62try { 63 commonEventManager.publishAsUser('event', userId, (err: BusinessError) => { 64 if (err) { 65 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 66 return; 67 } 68 console.info('publishAsUser'); 69 }); 70} catch (error) { 71 let err: BusinessError = error as BusinessError; 72 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 73} 74``` 75 76## commonEventManager.publishAsUser 77 78publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\<void>): void 79 80以回调形式向指定用户发布公共事件并指定发布信息。 81 82**系统能力：** SystemCapability.Notification.CommonEvent 83 84**系统API**：此接口为系统接口，三方应用不支持调用。 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| -------- | ---------------------- | ---- | ---------------------- | 90| event | string | 是 | 表示要发布的公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 91| userId | number | 是 | 表示指定向该用户ID发送此公共事件。 | 92| options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是 | 表示发布公共事件的属性。 | 93| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 94 95**错误码：** 96 97以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 98 99| 错误码ID | 错误信息 | 100| -------- | ----------------------------------- | 101| 202 | not system app. | 102| 1500003 | The common event sending frequency too high. | 103| 1500007 | Failed to send the message to the common event service. | 104| 1500008 | Failed to initialize the common event service. | 105| 1500009 | Failed to obtain system parameters. | 106 107**示例：** 108 109```ts 110import { BusinessError } from '@kit.BasicServicesKit'; 111 112// 公共事件相关信息 113let options:commonEventManager.CommonEventPublishData = { 114 code: 0, // 公共事件的初始代码 115 data: 'initial data',// 公共事件的初始数据 116} 117 118// 指定发送的用户 119let userId = 100; 120// 发布公共事件 121try { 122 commonEventManager.publishAsUser('event', userId, options, (err: BusinessError) => { 123 if (err) { 124 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 125 return; 126 } 127 console.info('publishAsUser'); 128 }); 129} catch (error) { 130 let err: BusinessError = error as BusinessError; 131 console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); 132} 133``` 134 135## commonEventManager.removeStickyCommonEvent<sup>10+</sup> 136 137removeStickyCommonEvent(event: string, callback: AsyncCallback\<void>): void 138 139以回调形式移除粘性公共事件。 140 141**系统能力：** SystemCapability.Notification.CommonEvent 142 143**需要权限**: ohos.permission.COMMONEVENT_STICKY 144 145**系统API**：此接口为系统接口，三方应用不支持调用。 146 147**参数：** 148 149| 参数名 | 类型 | 必填 | 说明 | 150| -------- | -------------------- | ---- | -------------------------------- | 151| event | string | 是 | 表示被移除的粘性公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 152| callback | AsyncCallback\<void> | 是 | 表示移除粘性公共事件的回调方法。 | 153 154**错误码：** 155 156以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 157 158| 错误码ID | 错误信息 | 159| -------- | ----------------------------------- | 160| 201 | The application dose not have permission to call the interface. | 161| 202 | not system app. | 162| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | 163| 1500004 | A third-party application cannot send system common events. | 164| 1500007 | Failed to send the message to the common event service. | 165| 1500008 | Failed to initialize the common event service. | 166 167**示例：** 168 169```ts 170import { BusinessError } from '@kit.BasicServicesKit'; 171 172commonEventManager.removeStickyCommonEvent('sticky_event', (err: BusinessError) => { 173 if (err) { 174 console.error(`removeStickyCommonEvent failed, errCode: ${err.code}, errMes: ${err.message}`); 175 return; 176 } 177 console.info(`removeStickyCommonEvent success`); 178}); 179``` 180 181## commonEventManager.removeStickyCommonEvent<sup>10+</sup> 182 183removeStickyCommonEvent(event: string): Promise\<void> 184 185以Promise形式移除粘性公共事件。 186 187**系统能力：** SystemCapability.Notification.CommonEvent 188 189**需要权限**: ohos.permission.COMMONEVENT_STICKY 190 191**系统API**：此接口为系统接口，三方应用不支持调用。 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| ------ | ------ | ---- | -------------------------- | 197| event | string | 是 | 表示被移除的粘性公共事件。详见[系统公共事件定义](./common_event/commonEventManager-definitions.md)。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| -------------- | ---------------------------- | 203| Promise\<void> | 表示移除粘性公共事件的对象。 | 204 205**错误码：** 206 207以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 208 209| 错误码ID | 错误信息 | 210| -------- | ----------------------------------- | 211| 201 | The application dose not have permission to call the interface. | 212| 202 | not system app. | 213| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | 214| 1500004 | A third-party application cannot send system common events. | 215| 1500007 | Failed to send the message to the common event service. | 216| 1500008 | Failed to initialize the common event service. | 217 218**示例：** 219 220```ts 221import { BusinessError } from '@kit.BasicServicesKit'; 222 223commonEventManager.removeStickyCommonEvent('sticky_event').then(() => { 224 console.info(`removeStickyCommonEvent success`); 225}).catch ((err: BusinessError) => { 226 console.error(`removeStickyCommonEvent failed, errCode: ${err.code}, errMes: ${err.message}`); 227}); 228``` 229 230## commonEventManager.setStaticSubscriberState<sup>10+</sup> 231 232setStaticSubscriberState(enable: boolean, callback: AsyncCallback\<void>): void 233 234方法介绍：为当前应用设置静态订阅事件使能或去使能状态。使用callback异步回调。 235 236**模型约束**：此接口仅可在Stage模型下使用。 237 238**系统能力：** SystemCapability.Notification.CommonEvent 239 240**系统API**：此接口为系统接口，三方应用不支持调用。 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245| ------ | ------ | ---- | -------------------------- | 246| enable | boolean | 是 | 表示静态订阅事件使能状态。 true:使能 false：去使能。 | 247| callback | AsyncCallback\<void> | 是 | 表示设置静态订阅事件使能状态的回调方法。 | 248 249**错误码：** 250 251以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 252 253| 错误码ID | 错误信息 | 254| -------- | ----------------------------------- | 255| 202 | not system app. | 256| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | 257| 1500007 | Failed to send the message to the common event service. | 258| 1500008 | Failed to initialize the common event service. | 259 260**示例：** 261 262```ts 263import { BusinessError } from '@kit.BasicServicesKit'; 264 265commonEventManager.setStaticSubscriberState(true, (err: BusinessError) => { 266 if (err.code != 0) { 267 console.error(`setStaticSubscriberState failed, errCode: ${err.code}, errMes: ${err.message}`); 268 return; 269 } 270 console.info(`setStaticSubscriberState success`); 271}); 272``` 273 274## commonEventManager.setStaticSubscriberState<sup>10+</sup> 275 276setStaticSubscriberState(enable: boolean): Promise\<void> 277 278方法介绍：为当前应用设置静态订阅事件使能或去使能状态。使用Promise异步回调。 279 280**模型约束**：此接口仅可在Stage模型下使用。 281 282**系统能力：** SystemCapability.Notification.CommonEvent 283 284**系统API**：此接口为系统接口，三方应用不支持调用。 285 286**参数：** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| ------ | ------ | ---- | -------------------------- | 290| enable | boolean | 是 | 表示静态订阅事件使能状态。 true:使能 false：去使能。 | 291 292**返回值：** 293 294| 类型 | 说明 | 295| -------------- | ---------------------------- | 296| Promise\<void> | Promise对象。无返回结果的Promise对象。| 297 298**错误码：** 299 300以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 301 302| 错误码ID | 错误信息 | 303| -------- | ----------------------------------- | 304| 202 | not system app. | 305| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | 306| 1500007 | Failed to send the message to the common event service. | 307| 1500008 | Failed to initialize the common event service. | 308 309**示例：** 310 311 312```ts 313import { BusinessError } from '@kit.BasicServicesKit'; 314 315commonEventManager.setStaticSubscriberState(false).then(() => { 316 console.info(`setStaticSubscriberState success`); 317}).catch ((err: BusinessError) => { 318 console.error(`setStaticSubscriberState failed, errCode: ${err.code}, errMes: ${err.message}`); 319}); 320``` 321 322## commonEventManager.setStaticSubscriberState<sup>12+</sup> 323 324setStaticSubscriberState(enable: boolean, events?: Array\<string>): Promise\<void> 325 326为当前应用设置静态订阅事件的使能状态，并且记录事件名称。使用Promise异步回调。 327 328**模型约束**：此接口仅可在Stage模型下使用。 329 330**系统能力**：SystemCapability.Notification.CommonEvent 331 332**系统接口**：此接口为系统接口。 333 334**参数：** 335 336| 参数名 | 类型 | 必填 | 说明 | 337| ------ | ------------- | ---- | ---------------------------------------------------- | 338| enable | boolean | 是 | 表示静态订阅事件使能状态。 true：使能 false：去使能。| 339| events | Array\<string> | 否 | 表示记录事件名称。 | 340 341**返回值：** 342 343| 类型 | 说明 | 344| -------------- | ------------------------------------ | 345| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 346 347**错误码：** 348 349以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[事件错误码](./errorcode-CommonEventService.md)。 350 351| 错误码ID | 错误信息 | 352| -------- | ------------------------------------------------------ | 353| 202 | not system app. | 354| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | 355| 1500007 | Failed to send the message to the common event service. | 356| 1500008 | Failed to initialize the common event service. | 357 358**示例：** 359 360```ts 361import { BusinessError } from '@kit.BasicServicesKit'; 362 363let evenName: string[] = ['usual.event.SEND_DATA']; 364commonEventManager.setStaticSubscriberState(true, evenName).then(() => { 365 console.info(`setStaticSubscriberState success, state is ${true}`); 366}).catch((err: BusinessError) => { 367 console.error(`setStaticSubscriberState failed, errCode: ${err.code}, errMes: ${err.message}`); 368}); 369``` 370