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