1# CommonEventSubscriber 2 3> **说明：** 4> 5> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6 7## 使用说明 8 9在使用CommonEventSubscriber的功能前，需要通过CommonEvent.createSubscriber获取subscriber对象。 10 11```ts 12import CommonEvent from '@ohos.commonEvent'; 13let subscriber; // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作 14 15// 订阅者信息 16let subscribeInfo = { 17 events: ["event"] 18}; 19 20// 创建订阅者回调 21function createCB(err, commonEventSubscriber) { 22 if (err.code) { 23 console.error(`createSubscriber failed, code is ${err.code}`); 24 } else { 25 console.info("createSubscriber"); 26 subscriber = commonEventSubscriber; 27 } 28} 29 30// 创建订阅者 31CommonEvent.createSubscriber(subscribeInfo, createCB); 32``` 33 34## getCode 35 36getCode(callback: AsyncCallback\<number>): void 37 38以回调形式获取公共事件代码。 39 40**系统能力**：`SystemCapability.Notification.CommonEvent` 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| -------- | ---------------------- | ---- | ------------------ | 46| callback | AsyncCallback\<number\> | 是 | 公共事件代码。 | 47 48**示例：** 49 50```ts 51//获取有序公共事件代码回调 52function getCodeCB(err, code) { 53 if (err.code) { 54 console.error(`getCode failed, code is ${err.code}, message is ${err.message}`); 55 } else { 56 console.info("getCode " + JSON.stringify(code)); 57 } 58} 59subscriber.getCode(getCodeCB); 60``` 61 62## getCode 63 64getCode(): Promise\<number> 65 66以Promise形式获取公共事件代码。 67 68**系统能力**：`SystemCapability.Notification.CommonEvent` 69 70**返回值：** 71 72| 类型 | 说明 | 73| ---------------- | -------------------- | 74| Promise\<number> | 公共事件代码。 | 75 76**示例：** 77 78```ts 79subscriber.getCode().then((code) => { 80 console.info("getCode " + JSON.stringify(code)); 81}).catch((err) => { 82 console.error(`getCode failed, code is ${err.code}, message is ${err.message}`); 83}); 84``` 85 86## setCode 87 88setCode(code: number, callback: AsyncCallback\<void>): void 89 90以回调形式设置公共事件的代码。 91 92**系统能力**：`SystemCapability.Notification.CommonEvent` 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| -------- | -------------------- | ---- | ---------------------- | 98| code | number | 是 | 公共事件的代码。 | 99| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 100 101**示例：** 102 103```ts 104//设置有序公共事件的代码回调 105function setCodeCB(err) { 106 if (err.code) { 107 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 108 } else { 109 console.info("setCode"); 110 } 111} 112subscriber.setCode(1, setCodeCB); 113``` 114 115## setCode 116 117setCode(code: number): Promise\<void> 118 119以Promise形式设置公共事件的代码。 120 121**系统能力**：`SystemCapability.Notification.CommonEvent` 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ------ | ------ | ---- | ------------------ | 127| code | number | 是 | 公共事件的代码。 | 128 129**返回值：** 130 131| 类型 | 说明 | 132| ---------------- | -------------------- | 133| Promise\<void> | 返回一个Promise的结果。 | 134 135**示例：** 136 137```ts 138subscriber.setCode(1).then(() => { 139 console.info("setCode"); 140}).catch((err) => { 141 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 142}); 143``` 144 145## getData 146 147getData(callback: AsyncCallback\<string>): void 148 149以回调形式获取公共事件的数据。 150 151**系统能力**：`SystemCapability.Notification.CommonEvent` 152 153**参数：** 154 155| 参数名 | 类型 | 必填 | 说明 | 156| -------- | ---------------------- | ---- | -------------------- | 157| callback | AsyncCallback\<string> | 是 | 公共事件的数据。 | 158 159**示例：** 160 161```ts 162//获取有序公共事件代码数据回调 163function getDataCB(err, data) { 164 if (err.code) { 165 console.error(`getData failed, code is ${err.code}, message is ${err.message}`); 166 } else { 167 console.info("getData " + JSON.stringify(data)); 168 } 169} 170subscriber.getData(getDataCB); 171``` 172 173## getData 174 175getData(): Promise\<string> 176 177以Promise形式获取公共事件的数据。 178 179**系统能力**：`SystemCapability.Notification.CommonEvent` 180 181**返回值：** 182 183| 类型 | 说明 | 184| ---------------- | ------------------ | 185| Promise\<string> | 公共事件的数据。 | 186 187**示例：** 188 189```ts 190subscriber.getData().then((data) => { 191 console.info("getData " + JSON.stringify(data)); 192}).catch((err) => { 193 console.error(`getData failed, code is ${err.code}, message is ${err.message}`); 194}); 195``` 196 197## setData 198 199setData(data: string, callback: AsyncCallback\<void>): void 200 201以回调形式设置公共事件的数据。 202 203**系统能力**：`SystemCapability.Notification.CommonEvent` 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| -------- | -------------------- | ---- | -------------------- | 209| data | string | 是 | 公共事件的数据。 | 210| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 211 212**示例：** 213 214```ts 215//设置有序公共事件的结果数据回调 216function setDataCB(err) { 217 if (err.code) { 218 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 219 } else { 220 console.info("setData"); 221 } 222} 223subscriber.setData("publish_data_changed", setDataCB); 224``` 225 226## setData 227 228setData(data: string): Promise\<void> 229 230以Promise形式设置公共事件的果数据。 231 232**系统能力**：`SystemCapability.Notification.CommonEvent` 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| ------ | ------ | ---- | -------------------- | 238| data | string | 是 | 公共事件的数据。 | 239 240**返回值：** 241 242| 类型 | 说明 | 243| ---------------- | -------------------- | 244| Promise\<void> | 返回一个Promise的结果。 | 245 246**示例：** 247 248```ts 249subscriber.setData("publish_data_changed").then(() => { 250 console.info("setData"); 251}).catch((err) => { 252 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 253}); 254``` 255 256## setCodeAndData 257 258setCodeAndData(code: number, data: string, callback:AsyncCallback\<void>): void 259 260以回调形式设置公共事件代码和数据。 261 262**系统能力**：`SystemCapability.Notification.CommonEvent` 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| -------- | -------------------- | ---- | ---------------------- | 268| code | number | 是 | 公共事件的代码。 | 269| data | string | 是 | 公共事件的数据。 | 270| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 271 272**示例：** 273 274```ts 275//设置有序公共事件的代码和数据回调 276function setCodeDataCB(err) { 277 if (err.code) { 278 console.error(`setCodeAndData failed, code is ${err.code}, message is ${err.message}`); 279 } else { 280 console.info("setCodeDataCallback"); 281 } 282} 283subscriber.setCodeAndData(1, "publish_data_changed", setCodeDataCB); 284``` 285 286## setCodeAndData 287 288setCodeAndData(code: number, data: string): Promise\<void> 289 290以Promise形式设置公共事件的代码和数据。 291 292**系统能力**：`SystemCapability.Notification.CommonEvent` 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| ------ | ------ | ---- | -------------------- | 298| code | number | 是 | 公共事件的代码。 | 299| data | string | 是 | 公共事件的数据。 | 300 301**返回值：** 302 303| 类型 | 说明 | 304| ---------------- | -------------------- | 305| Promise\<void> | 返回一个Promise。 | 306 307**示例：** 308 309```ts 310subscriber.setCodeAndData(1, "publish_data_changed").then(() => { 311 console.info("setCodeAndData"); 312}).catch((err) => { 313 console.error(`setCodeAndData failed, code is ${err.code}, message is ${err.message}`); 314}); 315``` 316 317## isOrderedCommonEvent 318 319isOrderedCommonEvent(callback: AsyncCallback\<boolean>): void 320 321以回调形式查询当前公共事件的是否为有序公共事件。 322 323返回true代表是有序公共事件，false代表不是有序公共事件。 324 325**系统能力**：`SystemCapability.Notification.CommonEvent` 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| -------- | ----------------------- | ---- | ---------------------------------- | 331| callback | AsyncCallback\<boolean> | 是 | 当前公共事件的是否为有序公共事件。 | 332 333**示例：** 334 335```ts 336//获取当前公共事件是否为有序事件的回调 337function isOrderedCB(err, isOrdered) { 338 if (err.code) { 339 console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); 340 } else { 341 console.info("isOrdered " + JSON.stringify(isOrdered)); 342 } 343} 344subscriber.isOrderedCommonEvent(isOrderedCB); 345``` 346 347## isOrderedCommonEvent 348 349isOrderedCommonEvent(): Promise\<boolean> 350 351以Promise形式查询当前公共事件的是否为有序公共事件。 352 353返回true代表是有序公共事件，false代表不是有序公共事件。 354 355**系统能力**：`SystemCapability.Notification.CommonEvent` 356 357**返回值：** 358 359| 类型 | 说明 | 360| ----------------- | -------------------------------- | 361| Promise\<boolean> | 当前公共事件的是否为有序公共事件。 | 362 363**示例：** 364 365```ts 366subscriber.isOrderedCommonEvent().then((isOrdered) => { 367 console.info("isOrdered " + JSON.stringify(isOrdered)); 368}).catch((err) => { 369 console.error(`isOrdered failed, code is ${err.code}, message is ${err.message}`); 370}); 371``` 372 373## isStickyCommonEvent 374 375isStickyCommonEvent(callback: AsyncCallback\<boolean>): void 376 377以回调形式检查当前公共事件是否为一个粘性事件。 378 379返回true代表是粘性公共事件，false代表不是粘性公共事件。 380 381**系统能力**：`SystemCapability.Notification.CommonEvent` 382 383**参数：** 384 385| 参数名 | 类型 | 必填 | 说明 | 386| -------- | ----------------------- | ---- | ---------------------------------- | 387| callback | AsyncCallback\<boolean> | 是 | 当前公共事件的是否为粘性公共事件。 | 388 389**示例：** 390 391```ts 392//获取当前公共事件是否为粘性事件的回调 393function isStickyCB(err, isSticky) { 394 if (err.code) { 395 console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); 396 } else { 397 console.info("isSticky " + JSON.stringify(isSticky)); 398 } 399} 400subscriber.isStickyCommonEvent(isStickyCB); 401``` 402 403## isStickyCommonEvent 404 405isStickyCommonEvent(): Promise\<boolean> 406 407以Promise形式检查当前公共事件是否为一个粘性事件。 408 409返回true代表是粘性公共事件，false代表不是粘性公共事件。 410 411**系统能力**：`SystemCapability.Notification.CommonEvent` 412 413**返回值：** 414 415| 类型 | 说明 | 416| ----------------- | -------------------------------- | 417| Promise\<boolean> | 当前公共事件的是否为粘性公共事件。 | 418 419**示例：** 420 421```ts 422subscriber.isStickyCommonEvent().then((isSticky) => { 423 console.info("isSticky " + JSON.stringify(isSticky)); 424}).catch((err) => { 425 console.error(`isSticky failed, code is ${err.code}, message is ${err.message}`); 426}); 427``` 428 429## abortCommonEvent 430 431abortCommonEvent(callback: AsyncCallback\<void>): void 432 433以回调形式取消当前的有序公共事件，取消后，有序公共事件不再向下一个订阅者传递。 434 435**系统能力**：`SystemCapability.Notification.CommonEvent` 436 437**参数：** 438 439| 参数名 | 类型 | 必填 | 说明 | 440| -------- | -------------------- | ---- | -------------------- | 441| callback | AsyncCallback\<void> | 是 | 取消当前的有序公共事件。 | 442 443**示例：** 444 445```ts 446//取消当前有序公共事件的回调 447function abortCB(err) { 448 if (err.code) { 449 console.error(`abortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 450 } else { 451 console.info("abortCommonEvent"); 452 } 453} 454subscriber.abortCommonEvent(abortCB); 455``` 456 457## abortCommonEvent 458 459abortCommonEvent(): Promise\<void> 460 461以Promise形式取消当前的有序公共事件，取消后，公共事件不再向下一个订阅者传递。 462 463**系统能力**：`SystemCapability.Notification.CommonEvent` 464 465**返回值：** 466 467| 类型 | 说明 | 468| ---------------- | -------------------- | 469| Promise\<void> | 返回一个Promise的结果。 | 470 471**示例：** 472 473```ts 474subscriber.abortCommonEvent().then(() => { 475 console.info("abortCommonEvent"); 476}).catch((err) => { 477 console.error(`abortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 478}); 479``` 480 481## clearAbortCommonEvent 482 483clearAbortCommonEvent(callback: AsyncCallback\<void>): void 484 485以回调形式清除当前有序公共事件。 486 487**系统能力**：`SystemCapability.Notification.CommonEvent` 488 489**参数：** 490 491| 参数名 | 类型 | 必填 | 说明 | 492| -------- | -------------------- | ---- | -------------------- | 493| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法。 | 494 495**示例：** 496 497```ts 498//清除当前公共事件取消状态的回调 499function clearAbortCB(err) { 500 if (err.code) { 501 console.error(`clearAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 502 } else { 503 console.info("clearAbortCommonEvent"); 504 } 505} 506subscriber.clearAbortCommonEvent(clearAbortCB); 507``` 508 509## clearAbortCommonEvent 510 511clearAbortCommonEvent(): Promise\<void> 512 513以Promise形式清除当前有序公共事件。 514 515**系统能力**：`SystemCapability.Notification.CommonEvent` 516 517**返回值：** 518 519| 类型 | 说明 | 520| ---------------- | -------------------- | 521| Promise\<void> | 返回一个Promise的结果。 | 522 523**示例：** 524 525```ts 526subscriber.clearAbortCommonEvent().then(() => { 527 console.info("clearAbortCommonEvent"); 528}).catch((err) => { 529 console.error(`clearAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 530}); 531``` 532 533## getAbortCommonEvent 534 535getAbortCommonEvent(callback: AsyncCallback\<boolean>): void 536 537以回调形式获取当前有序公共事件是否取消的状态。 538 539**系统能力**：`SystemCapability.Notification.CommonEvent` 540 541**参数：** 542 543| 参数名 | 类型 | 必填 | 说明 | 544| -------- | ----------------------- | ---- | ---------------------------------- | 545| callback | AsyncCallback\<boolean> | 是 | 表示当前有序公共事件是否取消的状态。 | 546 547**示例：** 548 549```ts 550//获取当前有序公共事件是否取消的回调 551function getAbortCB(err, abortEvent) { 552 if (err.code) { 553 console.error(`getAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 554 } else { 555 console.info("abortCommonEvent " + abortEvent) 556 } 557} 558subscriber.getAbortCommonEvent(getAbortCB); 559``` 560 561## getAbortCommonEvent 562 563getAbortCommonEvent(): Promise\<boolean> 564 565以Promise形式获取当前有序公共事件是否取消的状态。 566 567**系统能力**：`SystemCapability.Notification.CommonEvent` 568 569**返回值：** 570 571| 类型 | 说明 | 572| ----------------- | ---------------------------------- | 573| Promise\<boolean> | 表示当前有序公共事件是否取消的状态。 | 574 575**示例：** 576 577```ts 578subscriber.getAbortCommonEvent().then((abortEvent) => { 579 console.info("abortCommonEvent " + JSON.stringify(abortEvent)); 580}).catch((err) => { 581 console.error(`getAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 582}); 583``` 584 585## getSubscribeInfo 586 587getSubscribeInfo(callback: AsyncCallback\<CommonEventSubscribeInfo>): void 588 589以回调形式获取订阅者的订阅信息。 590 591**系统能力**：`SystemCapability.Notification.CommonEvent` 592 593**参数：** 594 595| 参数名 | 类型 | 必填 | 说明 | 596| -------- | ------------------------------------------------------------ | ---- | ---------------------- | 597| callback | AsyncCallback\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | 是 | 表示订阅者的订阅信息。 | 598 599**示例：** 600 601```ts 602//获取订阅者信息回调 603function getCB(err, subscribeInfo) { 604 if (err.code) { 605 console.error(`getSubscribeInfo failed, code is ${err.code}, message is ${err.message}`); 606 } else { 607 console.info("subscribeInfo " + JSON.stringify(subscribeInfo)); 608 } 609} 610subscriber.getSubscribeInfo(getCB); 611``` 612 613## getSubscribeInfo 614 615getSubscribeInfo(): Promise\<CommonEventSubscribeInfo> 616 617以Promise形式获取订阅者的订阅信息。 618 619**系统能力**：`SystemCapability.Notification.CommonEvent` 620 621**返回值：** 622 623| 类型 | 说明 | 624| ------------------------------------------------------------ | ---------------------- | 625| Promise\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | 表示订阅者的订阅信息。 | 626 627**示例：** 628 629```ts 630subscriber.getSubscribeInfo().then((subscribeInfo) => { 631 console.info("subscribeInfo " + JSON.stringify(subscribeInfo)); 632}).catch((err) => { 633 console.error(`getSubscribeInfo failed, code is ${err.code}, message is ${err.message}`); 634}); 635``` 636 637## finishCommonEvent<sup>9+</sup> 638 639finishCommonEvent(callback: AsyncCallback\<void>): void 640 641以回调形式结束当前有序公共事件。 642 643**系统能力**：`SystemCapability.Notification.CommonEvent` 644 645**参数：** 646 647| 参数名 | 类型 | 必填 | 说明 | 648| -------- | -------------------- | ---- | -------------------------------- | 649| callback | AsyncCallback\<void> | 是 | 表示有序公共事件结束后的回调函数。 | 650 651**示例：** 652 653```ts 654//结束当前有序公共事件的回调 655function finishCB(err) { 656 if (err.code) { 657 console.error(`finishCommonEvent failed, code is ${err.code}, message is ${err.message}`); 658 } else { 659 console.info("FinishCommonEvent"); 660 } 661} 662 663subscriber.finishCommonEvent(finishCB); 664``` 665 666## finishCommonEvent<sup>9+</sup> 667 668finishCommonEvent(): Promise\<void> 669 670以Promise形式结束当前有序公共事件。 671 672**系统能力**：`SystemCapability.Notification.CommonEvent` 673 674**返回值：** 675 676| 类型 | 说明 | 677| ---------------- | -------------------- | 678| Promise\<void> | 返回一个Promise的结果。 | 679 680**示例：** 681 682```ts 683subscriber.finishCommonEvent().then(() => { 684 console.info("FinishCommonEvent"); 685}).catch((err) => { 686 console.error(`finishCommonEvent failed, code is ${err.code}, message is ${err.message}`); 687}); 688```