1# @ohos.commonEventManager (公共事件模块) 2 3本模块提供了公共事件的能力，包括公共事件的权限列表，发布公共事件，订阅或取消订阅公共事件，获取或修改公共事件结果代码、结果数据等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import CommonEventManager from '@ohos.commonEventManager'; 13``` 14 15## Support 16 17系统公共事件是指由系统服务或系统应用发布的事件，订阅这些系统公共事件需要特定的权限。发布或订阅这些事件需要使用如下链接中的枚举定义。 18 19全部系统公共事件枚举定义请参见[系统公共事件定义](./commonEventManager-definitions.md)。 20 21## CommonEventManager.publish 22 23publish(event: string, callback: AsyncCallback\<void>): void 24 25发布公共事件（callback形式）。 26 27**系统能力：** SystemCapability.Notification.CommonEvent 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| -------- | -------------------- | ---- | ---------------------- | 33| event | string | 是 | 表示要发送的公共事件。 | 34| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 35 36**错误码：** 37以下错误码详细介绍请参考[@ohos.commonEventManager(事件)](../errorcodes/errorcode-CommonEventService.md) 38 39|错误码ID |错误信息 | 40|-----------|--------------------| 41|1500004 |not System services or System app| 42|1500007 |message send error| 43|1500008 |CEMS error| 44|1500009 |system error| 45 46| 错误码ID | 错误信息 | 47| -------- | ----------------------------------- | 48| 1500004 | not System services. | 49| 1500007 | error sending message to Common Event Service. | 50| 1500008 | Common Event Service does not complete initialization. | 51| 1500009 | error obtaining system parameters. | 52 53**示例：** 54 55```ts 56//发布公共事件回调 57function publishCallBack(err) { 58 if (err) { 59 console.error("publish failed " + JSON.stringify(err)); 60 } else { 61 console.info("publish"); 62 } 63} 64 65//发布公共事件 66try { 67 CommonEventManager.publish("event", publishCallBack); 68} catch(err) { 69 console.error('publish failed, catch error' + JSON.stringify(err)); 70} 71``` 72 73## CommonEventManager.publish 74 75publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\<void>): void 76 77发布公共事件指定发布信息（callback形式）。 78 79**系统能力：** SystemCapability.Notification.CommonEvent 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| -------- | ---------------------- | ---- | ---------------------- | 85| event | string | 是 | 表示要发布的公共事件。 | 86| options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是 | 表示发布公共事件的属性。 | 87| callback | syncCallback\<void> | 是 | 表示被指定的回调方法。 | 88 89**错误码：** 90|错误码ID |错误信息 | 91|-----------|--------------------| 92|1500004 |not System services or System app| 93|1500007 |message send error| 94|1500008 |CEMS error| 95|1500009 |system error| 96 97 98| 错误码ID | 错误信息 | 99| -------- | ----------------------------------- | 100| 1500004 | not System services. | 101| 1500007 | error sending message to Common Event Service. | 102| 1500008 | Common Event Service does not complete initialization. | 103| 1500009 | error obtaining system parameters. | 104 105**示例：** 106 107 108```ts 109//公共事件相关信息 110var options = { 111 code: 0, //公共事件的初始代码 112 data: "initial data",//公共事件的初始数据 113 isOrdered: true //有序公共事件 114} 115 116//发布公共事件回调 117function publishCallBack(err) { 118 if (err) { 119 console.error("publish failed " + JSON.stringify(err)); 120 } else { 121 console.info("publish"); 122 } 123} 124 125//发布公共事件 126try { 127 CommonEventManager.publish("event", options, publishCallBack); 128} catch (err) { 129 console.error('publish failed, catch error' + JSON.stringify(err)); 130} 131``` 132 133 134 135## CommonEventManager.publishAsUser<sup> 136 137publishAsUser(event: string, userId: number, callback: AsyncCallback\<void>): void 138 139向指定用户发布公共事件（callback形式）。 140 141**系统能力：** SystemCapability.Notification.CommonEvent 142 143**系统API**：此接口为系统接口，三方应用不支持调用。 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| -------- | -------------------- | ---- | ---------------------------------- | 149| event | string | 是 | 表示要发送的公共事件。 | 150| userId | number | 是 | 表示指定向该用户ID发送此公共事件。 | 151| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 152 153**错误码：** 154|错误码ID |错误信息 | 155|-----------|--------------------| 156|1500004 |not System services or System app| 157|1500007 |message send error| 158|1500008 |CEMS error| 159|1500009 |system error| 160 161| 错误码ID | 错误信息 | 162| -------- | ----------------------------------- | 163| 1500004 | not System services. | 164| 1500007 | error sending message to Common Event Service. | 165| 1500008 | Common Event Service does not complete initialization. | 166| 1500009 | error obtaining system parameters. | 167 168**示例：** 169 170```ts 171//发布公共事件回调 172function publishAsUserCallBack(err) { 173 if (err) { 174 console.error("publishAsUser failed " + JSON.stringify(err)); 175 } else { 176 console.info("publishAsUser"); 177 } 178} 179 180//指定发送的用户 181var userId = 100; 182 183//发布公共事件 184try { 185 CommonEventManager.publishAsUser("event", userId, publishAsUserCallBack); 186} catch (err) { 187 console.error('publishAsUser failed, catch error' + JSON.stringify(err)); 188} 189``` 190 191 192 193## CommonEventManager.publishAsUser 194 195publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\<void>): void 196 197向指定用户发布公共事件并指定发布信息（callback形式）。 198 199**系统能力：** SystemCapability.Notification.CommonEvent 200 201**系统API**：此接口为系统接口，三方应用不支持调用。 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| -------- | ---------------------- | ---- | ---------------------- | 207| event | string | 是 | 表示要发布的公共事件。 | 208| userId | number | 是 | 表示指定向该用户ID发送此公共事件。 | 209| options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | 是 | 表示发布公共事件的属性。 | 210| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 211 212**错误码：** 213|错误码ID |错误信息 | 214|-----------|--------------------| 215|1500004 |not System services or System app| 216|1500007 |message send error| 217|1500008 |CEMS error| 218|1500009 |system error| 219 220| 错误码ID | 错误信息 | 221| -------- | ----------------------------------- | 222| 1500004 | not System services or System app. | 223| 1500007 | error sending message to Common Event Service. | 224| 1500008 | Common Event Service does not complete initialization. | 225| 1500009 | error obtaining system parameters. | 226 227**示例：** 228 229 230```ts 231//公共事件相关信息 232var options = { 233 code: 0, //公共事件的初始代码 234 data: "initial data",//公共事件的初始数据 235} 236 237//发布公共事件回调 238function publishAsUserCallBack(err) { 239 if (err) { 240 console.error("publishAsUser failed " + JSON.stringify(err)); 241 } else { 242 console.info("publishAsUser"); 243 } 244} 245 246//指定发送的用户 247var userId = 100; 248 249//发布公共事件 250try { 251 CommonEventManager.publishAsUser("event", userId, options, publishAsUserCallBack); 252} catch (err) { 253 console.error('publishAsUser failed, catch error' + JSON.stringify(err)); 254} 255``` 256 257 258 259## CommonEventManager.createSubscriber 260 261createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void 262 263创建订阅者（callback形式）。 264 265**系统能力：** SystemCapability.Notification.CommonEvent 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------------- | ------------------------------------------------------------ | ---- | -------------------------- | 271| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是 | 表示订阅信息。 | 272| callback | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 是 | 表示创建订阅者的回调方法。 | 273 274**示例：** 275 276 277```ts 278var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作 279 280//订阅者信息 281var subscribeInfo = { 282 events: ["event"] 283}; 284 285//创建订阅者回调 286function createSubscriberCallBack(err, commonEventSubscriber) { 287 if(!err) { 288 console.info("createSubscriber"); 289 subscriber = commonEventSubscriber; 290 } else { 291 console.error("createSubscriber failed " + JSON.stringify(err)); 292 } 293} 294 295//创建订阅者 296try { 297 CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack); 298} catch (err) { 299 console.error('createSubscriber failed, catch error' + JSON.stringify(err)); 300} 301``` 302 303 304 305## CommonEventManager.createSubscriber 306 307createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber> 308 309创建订阅者（Promise形式）。 310 311**系统能力：** SystemCapability.Notification.CommonEvent 312 313**参数：** 314 315| 参数名 | 类型 | 必填 | 说明 | 316| ------------- | ----------------------------------------------------- | ---- | -------------- | 317| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | 是 | 表示订阅信息。 | 318 319**返回值：** 320| 类型 | 说明 | 321| --------------------------------------------------------- | ---------------- | 322| Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | 返回订阅者对象。 | 323 324**示例：** 325 326```ts 327var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作 328 329//订阅者信息 330var subscribeInfo = { 331 events: ["event"] 332}; 333 334//创建订阅者 335try { 336 CommonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber) => { 337 console.info("createSubscriber"); 338 subscriber = commonEventSubscriber; 339}).catch((err) => { 340 console.error("createSubscriber failed " + JSON.stringify(err)); 341}); 342} catch(err) { 343 console.error('createSubscriber failed, catch error' + JSON.stringify(err)); 344} 345 346``` 347 348 349 350## CommonEventManager.subscribe 351 352subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEventData>): void 353 354订阅公共事件（callback形式）。 355 356**系统能力：** SystemCapability.Notification.CommonEvent 357 358**参数：** 359 360| 参数名 | 类型 | 必填 | 说明 | 361| ---------- | ---------------------------------------------------- | ---- | -------------------------------- | 362| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 是 | 表示订阅者对象。 | 363| callback | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | 是 | 表示接收公共事件数据的回调函数。 | 364 365**错误码：** 366 367错误码介绍请参考[@ohos.commonEventManager(事件)](../errorcodes/errorcode-CommonEventService.md) 368 369| 错误码ID | 错误信息 | 370| -------- | ----------------------------------- | 371| 801 | capability not supported. | 372| 1500007 | error sending message to Common Event Service. | 373| 1500008 | Common Event Service does not complete initialization. | 374 375**示例：** 376 377```ts 378//订阅者信息 379var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作 380 381//订阅者信息 382var subscribeInfo = { 383 events: ["event"] 384}; 385 386//订阅公共事件回调 387function SubscribeCallBack(err, data) { 388 if (err) { 389 console.error("subscribe failed " + JSON.stringify(err)); 390 } else { 391 console.info("subscribe "); 392 } 393} 394 395//创建订阅者回调 396function createSubscriberCallBack(err, commonEventSubscriber) { 397 if(!err) { 398 console.info("createSubscriber"); 399 subscriber = commonEventSubscriber; 400 //订阅公共事件 401 try { 402 CommonEventManager.subscribe(subscriber, SubscribeCallBack); 403 } catch (err) { 404 console.error("createSubscriber failed " + JSON.stringify(err)); 405 } 406 } else { 407 console.error("createSubscriber failed " + JSON.stringify(err)); 408 } 409} 410 411//创建订阅者 412try { 413 CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack); 414} catch (err) { 415 console.error('createSubscriber failed, catch error' + JSON.stringify(err)); 416} 417``` 418 419 420 421## CommonEventManager.unsubscribe 422 423unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void 424 425取消订阅公共事件（callback形式）。 426 427**系统能力：** SystemCapability.Notification.CommonEvent 428 429**参数：** 430 431| 参数名 | 类型 | 必填 | 说明 | 432| ---------- | ----------------------------------------------- | ---- | ------------------------ | 433| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | 是 | 表示订阅者对象。 | 434| callback | AsyncCallback\<void> | 否 | 表示取消订阅的回调方法。 | 435 436**错误码：** 437 438错误码介绍请参考[@ohos.commonEventManager(事件)](../errorcodes/errorcode-CommonEventService.md) 439 440| 错误码ID | 错误信息 | 441| -------- | ----------------------------------- | 442| 801 | capability not supported. | 443| 1500007 | error sending message to Common Event Service. | 444| 1500008 | Common Event Service does not complete initialization. | 445 446**示例：** 447 448```ts 449var subscriber; //用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作 450//订阅者信息 451var subscribeInfo = { 452 events: ["event"] 453}; 454//订阅公共事件回调 455function subscribeCallBack(err, data) { 456 if (err) { 457 console.info("subscribe failed " + JSON.stringify(err)); 458 } else { 459 console.info("subscribe"); 460 } 461} 462//创建订阅者回调 463function createSubscriberCallBack(err, commonEventSubscriber) { 464 if (err) { 465 console.info("createSubscriber failed " + JSON.stringify(err)); 466 } else { 467 console.info("createSubscriber"); 468 subscriber = commonEventSubscriber; 469 //订阅公共事件 470 try { 471 CommonEventManager.subscribe(subscriber, subscribeCallBack); 472 } catch(err) { 473 console.info("subscribe failed " + JSON.stringify(err)); 474 } 475 } 476} 477//取消订阅公共事件回调 478function unsubscribeCallBack(err) { 479 if (err) { 480 console.info("unsubscribe failed " + JSON.stringify(err)); 481 } else { 482 console.info("unsubscribe"); 483 } 484} 485//创建订阅者 486try { 487 CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack); 488} catch (err) { 489 console.info("createSubscriber failed " + JSON.stringify(err)); 490} 491 492//取消订阅公共事件 493try { 494 CommonEventManager.unsubscribe(subscriber, unsubscribeCallBack); 495} catch (err) { 496 console.info("unsubscribe failed " + JSON.stringify(err)); 497} 498``` 499 500## CommonEventData 501 502**系统能力：** 以下各项对应的系统能力均为SystemCapability.Notification.CommonEvent 503 504| 名称 | 类型 | 可读 | 可写 | 说明 | 505| ---------- |-------------------- | ---- | ---- | ------------------------------------------------------- | 506| event | string | 是 | 否 | 表示当前接收的公共事件名称。 | 507| bundleName | string | 是 | 否 | 表示包名称。 | 508| code | number | 是 | 否 | 表示公共事件的结果代码，用于传递int类型的数据。 | 509| data | string | 是 | 否 | 表示公共事件的自定义结果数据，用于传递string类型的数据。 | 510| parameters | {[key: string]: any} | 是 | 否 | 表示公共事件的附加信息。 | 511 512 513## CommonEventPublishData 514 515**系统能力：** 以下各项对应的系统能力均为SystemCapability.Notification.CommonEvent 516 517| 名称 | 类型 | 可读 | 可写 | 说明 | 518| --------------------- | -------------------- | ---- | ---- | ---------------------------- | 519| bundleName | string | 是 | 否 | 表示包名称。 | 520| code | number | 是 | 否 | 表示公共事件的结果代码。 | 521| data | string | 是 | 否 | 表示公共事件的自定义结果数据。 | 522| subscriberPermissions | Array\<string> | 是 | 否 | 表示订阅者的权限。 | 523| isOrdered | boolean | 是 | 否 | 表示是否是有序事件。 | 524| isSticky | boolean | 是 | 否 | 表示是否是粘性事件。仅系统应用或系统服务允许发送粘性事件。 | 525| parameters | {[key: string]: any} | 是 | 否 | 表示公共事件的附加信息。 | 526 527## CommonEventSubscribeInfo 528 529**系统能力：** 以下各项对应的系统能力均为SystemCapability.Notification.CommonEvent 530 531| 名称 | 类型 | 可读 | 可写 | 说明 | 532| ------------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 533| events | Array\<string> | 是 | 否 | 表示要发送的公共事件。 | 534| publisherPermission | string | 是 | 否 | 表示发布者的权限。 | 535| publisherDeviceId | string | 是 | 否 | 表示设备ID，该值必须是同一ohos网络上的现有设备ID。 | 536| userId | number | 是 | 否 | 表示用户ID。此参数是可选的，默认值当前用户的ID。如果指定了此参数，则该值必须是系统中现有的用户ID。 | 537| priority | number | 是 | 否 | 表示订阅者的优先级。值的范围是-100到1000。 | 538