1# @ohos.events.emitter (Emitter) 2 3本模块提供了在同一进程不同线程间或同一线程内发送和处理事件的能力，支持持续订阅事件、单次订阅事件、取消订阅事件及发送事件到事件队列。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { emitter } from '@kit.BasicServicesKit'; 13``` 14 15## 权限列表 16 17无权限要求。 18 19## emitter.on 20 21on(event: InnerEvent, callback: Callback\<EventData\>): void 22 23持续订阅指定的事件，并在接收到该事件时，执行对应的回调处理函数。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力**: `SystemCapability.Notification.Emitter` 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 33| event | [InnerEvent](#innerevent) | 是 | 持续订阅的事件，其中[EventPriority](#eventpriority)，在订阅事件时无需指定，也不生效。 | 34| callback | Callback\<[EventData](#eventdata)\> | 是 | 接收到该事件时需要执行的回调处理函数。 | 35 36**示例：** 37 38```ts 39import { Callback} from '@kit.BasicServicesKit'; 40 41let innerEvent: emitter.InnerEvent = { 42 eventId: 1 43}; 44 45let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 46 console.info(`eventData: ${JSON.stringify(eventData)}`); 47} 48 49// 收到eventId为1的事件后执行回调函数 50emitter.on(innerEvent, callback); 51``` 52 53## emitter.on<sup>11+</sup> 54 55on(eventId: string, callback: Callback\<EventData\>): void 56 57持续订阅指定的事件，并在接收到该事件时，执行对应的回调处理函数。 58 59**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 60 61**系统能力**: `SystemCapability.Notification.Emitter` 62 63**参数：** 64 65| 参数名 | 类型 | 必填 | 说明 | 66| -------- | ----------------------------------- | ---- | -------------------------------------- | 67| eventId | string | 是 | 持续订阅的事件。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 68| callback | Callback\<[EventData](#eventdata)\> | 是 | 接收到该事件时需要执行的回调处理函数。 | 69 70**示例：** 71 72```ts 73import { Callback} from '@kit.BasicServicesKit'; 74 75let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 76 console.info(`eventData: ${JSON.stringify(eventData)}`); 77} 78// 收到eventId为"eventId"的事件后执行回调函数 79emitter.on(`eventId`, callback); 80``` 81 82## emitter.on<sup>12+</sup> 83 84on<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void 85 86持续订阅指定的事件，并在接收到该事件时，执行对应的回调处理函数。 87 88**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 89 90**系统能力**: `SystemCapability.Notification.Emitter` 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| -------- | ----------------------------------- | ---- | -------------------------------------- | 96| eventId | string | 是 | 持续订阅的事件。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 97| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | 是 | 接收到该事件时需要执行的回调处理函数。 | 98 99**示例：** 100 101```ts 102import { Callback} from '@kit.BasicServicesKit'; 103 104@Sendable 105class Sample { 106 constructor() { 107 this.count = 100; 108 } 109 printCount() { 110 console.info('Print count : ' + this.count); 111 } 112 count: number; 113} 114 115let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { 116 console.info(`eventData: ${JSON.stringify(eventData?.data)}`); 117 if (eventData?.data instanceof Sample) { 118 eventData?.data?.printCount(); 119 } 120} 121// 收到eventId为"eventId"的事件后执行回调函数 122emitter.on("eventId", callback); 123``` 124 125## emitter.once 126 127once(event: InnerEvent, callback: Callback\<EventData\>): void 128 129单次订阅指定的事件，在接收到该事件且执行完对应的回调函数后，自动取消订阅。 130 131**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 132 133**系统能力**: `SystemCapability.Notification.Emitter` 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 139| event | [InnerEvent](#innerevent) | 是 | 单次订阅的事件，其中[EventPriority](#eventpriority)，在订阅事件时无需指定，也不生效。 | 140| callback | Callback\<[EventData](#eventdata)\> | 是 | 接收到该事件时需要执行的回调处理函数。 | 141 142**示例：** 143 144```ts 145import { Callback} from '@kit.BasicServicesKit'; 146 147let innerEvent: emitter.InnerEvent = { 148 eventId: 1 149}; 150 151let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 152 console.info(`eventData: ${JSON.stringify(eventData)}`); 153} 154// 收到eventId为1的事件后执行该回调函数 155emitter.once(innerEvent, callback); 156``` 157 158## emitter.once<sup>11+</sup> 159 160once(eventId: string, callback: Callback\<EventData\>): void 161 162单次订阅指定的事件，在接收到该事件且执行完对应的回调函数后，自动取消订阅。 163 164**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 165 166**系统能力**: `SystemCapability.Notification.Emitter` 167 168**参数：** 169 170| 参数名 | 类型 | 必填 | 说明 | 171| -------- | ----------------------------------- | ---- | -------------------------------------- | 172| eventId | string | 是 | 单次订阅的事件。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 173| callback | Callback\<[EventData](#eventdata)\> | 是 | 接收到该事件时需要执行的回调处理函数。 | 174 175**示例：** 176 177```ts 178import { Callback} from '@kit.BasicServicesKit'; 179 180let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 181 console.info(`eventData: ${JSON.stringify(eventData)}`); 182} 183// 收到eventId为"eventId"的事件后执行该回调函数 184emitter.once("eventId", callback); 185``` 186 187## emitter.once<sup>12+</sup> 188 189once<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void 190 191单次订阅指定的事件，在接收到该事件且执行完相应的回调函数后，自动取消订阅。 192 193**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 194 195**系统能力**: `SystemCapability.Notification.Emitter` 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| -------- | ----------------------------------- | ---- | -------------------------------------- | 201| eventId | string | 是 | 单次订阅的事件。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 202| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | 是 | 接收到该事件时需要执行的回调处理函数。 | 203 204**示例：** 205 206```ts 207import { Callback} from '@kit.BasicServicesKit'; 208 209@Sendable 210class Sample { 211 constructor() { 212 this.count = 100; 213 } 214 printCount() { 215 console.info('Print count : ' + this.count); 216 } 217 count: number; 218} 219 220let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { 221 console.info(`eventData: ${JSON.stringify(eventData?.data)}`); 222 if (eventData?.data instanceof Sample) { 223 eventData?.data?.printCount(); 224 } 225} 226// 收到eventId为"eventId"的事件后执行回调函数 227emitter.once("eventId", callback); 228``` 229 230## emitter.off 231 232off(eventId: number): void 233 234取消事件ID为eventId的所有订阅。 235 236使用该接口取消某个事件订阅后，已通过[emit](#emitteremit)接口发布但尚未被执行的事件将被取消。 237 238**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 239 240**系统能力**: `SystemCapability.Notification.Emitter` 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245| ------- | ------ | ---- | -------- | 246| eventId | number | 是 | 事件ID。 | 247 248**示例：** 249 250```ts 251// 取消eventID为1的所有事件回调处理函数 252emitter.off(1); 253``` 254 255## emitter.off<sup>11+</sup> 256 257off(eventId: string): void 258 259取消事件ID为eventId的所有订阅。 260 261使用该接口取消某个事件订阅后，已通过[emit](#emitteremit11)接口发布但尚未被执行的事件将被取消。 262 263**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 264 265**系统能力**: `SystemCapability.Notification.Emitter` 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------- | ------ | ---- | -------- | 271| eventId | string | 是 | 事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 272 273**示例：** 274 275```ts 276// 取消eventID为"eventId"的所有事件回调处理函数 277emitter.off("eventId"); 278``` 279 280## emitter.off<sup>10+</sup> 281 282off(eventId: number, callback: Callback\<EventData\>): void 283 284取消事件ID为eventId且回调处理函数为callback的订阅。仅当已使用[on](#emitteron)或[once](#emitteronce)接口订阅callback时，该接口才生效。 285 286使用该接口取消某个事件订阅后，已通过[emit](#emitteremit)接口发布但尚未被执行的事件将被取消。 287 288**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 289 290**系统能力**: `SystemCapability.Notification.Emitter` 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| ------- | ------ | ---- | ------ | 296| eventId | number | 是 | 事件ID。 | 297| callback | Callback\<[EventData](#eventdata)\> | 是 | 事件的回调处理函数。 | 298 299**示例：** 300 301```ts 302import { Callback} from '@kit.BasicServicesKit'; 303 304let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 305 console.info(`eventData: ${JSON.stringify(eventData)}`); 306} 307// 取消eventID为1的事件回调处理函数，callback对象应使用订阅时的对象 308// 如果该回调处理函数没有被订阅，则不做任何处理 309emitter.off(1, callback); 310``` 311 312## emitter.off<sup>11+</sup> 313 314off(eventId: string, callback: Callback\<EventData\>): void 315 316取消事件ID为eventId且回调处理函数为callback的订阅。仅当已使用[on](#emitteron11)或[once](#emitteronce11)接口订阅callback时，该接口才生效。 317 318使用该接口取消某个事件订阅后，已通过[emit](#emitteremit11)接口发布但尚未被执行的事件将被取消。 319 320**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 321 322**系统能力**: `SystemCapability.Notification.Emitter` 323 324**参数：** 325 326| 参数名 | 类型 | 必填 | 说明 | 327| -------- | ----------------------------------- | ---- | -------------------------- | 328| eventId | string | 是 | 事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 329| callback | Callback\<[EventData](#eventdata)\> | 是 | 事件的回调处理函数。 | 330 331**示例：** 332 333```ts 334import { Callback} from '@kit.BasicServicesKit'; 335 336let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { 337 console.info(`eventData: ${JSON.stringify(eventData)}`); 338} 339// 取消eventID为"eventId"的事件回调处理函数，callback对象应使用订阅时的对象 340// 如果该回调处理函数没有被订阅，则不做任何处理 341emitter.off("eventId", callback); 342``` 343 344## emitter.off<sup>12+</sup> 345 346off<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void 347 348取消事件ID为eventId且回调处理函数为callback的订阅。仅当已使用[on](#emitteron12)或[once](#emitteronce12)接口订阅callback时，该接口才生效。 349 350使用该接口取消某个事件订阅后，已通过[emit](#emitteremit12)接口发布但尚未被执行的事件将被取消。 351 352**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 353 354**系统能力**: `SystemCapability.Notification.Emitter` 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| -------- | ----------------------------------- | ---- | -------------------------- | 360| eventId | string | 是 | 事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 361| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | 是 | 事件的回调处理函数。 | 362 363**示例：** 364 365```ts 366import { Callback} from '@kit.BasicServicesKit'; 367 368@Sendable 369class Sample { 370 constructor() { 371 this.count = 100; 372 } 373 printCount() { 374 console.info('Print count : ' + this.count); 375 } 376 count: number; 377} 378 379let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { 380 console.info(`eventData: ${JSON.stringify(eventData?.data)}`); 381 if (eventData?.data instanceof Sample) { 382 eventData?.data?.printCount(); 383 } 384} 385// 取消eventID为"eventId"的事件回调处理函数，callback对象应使用订阅时的对象 386// 如果该回调处理函数没有被订阅，则不做任何处理 387emitter.off("eventId", callback); 388``` 389 390## emitter.emit 391 392emit(event: InnerEvent, data?: EventData): void 393 394发送指定事件。 395 396**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 397 398**系统能力**: `SystemCapability.Notification.Emitter` 399 400**参数：** 401 402| 参数名 | 类型 | 必填 | 说明 | 403| ------ | ------------------------- | ---- | ------------- | 404| event | [InnerEvent](#innerevent) | 是 | 发送的事件，其中[EventPriority](#eventpriority)用于指定事件被发送的优先级。 | 405| data | [EventData](#eventdata) | 否 | 事件携带的数据。 | 406 407**示例：** 408 409```ts 410let eventData: emitter.EventData = { 411 data: { 412 "content": "content", 413 "id": 1, 414 } 415}; 416 417let innerEvent: emitter.InnerEvent = { 418 eventId: 1, 419 priority: emitter.EventPriority.HIGH 420}; 421 422emitter.emit(innerEvent, eventData); 423``` 424 425## emitter.emit<sup>11+</sup> 426 427emit(eventId: string, data?: EventData): void 428 429发送指定事件。 430 431**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 432 433**系统能力**: `SystemCapability.Notification.Emitter` 434 435**参数：** 436 437| 参数名 | 类型 | 必填 | 说明 | 438| ------- | ----------------------- | ---- | ---------------- | 439| eventId | string | 是 | 发送的事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 440| data | [EventData](#eventdata) | 否 | 事件携带的数据。 | 441 442**示例：** 443 444```ts 445let eventData: emitter.EventData = { 446 data: { 447 "content": "content", 448 "id": 1, 449 } 450}; 451 452emitter.emit("eventId", eventData); 453``` 454 455## emitter.emit<sup>12+</sup> 456 457emit<T\>(eventId: string, data?: GenericEventData<T\>): void 458 459发送指定事件。 460 461**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 462 463**系统能力**: `SystemCapability.Notification.Emitter` 464 465**参数：** 466 467| 参数名 | 类型 | 必填 | 说明 | 468| ------- | ----------------------- | ---- | ---------------- | 469| eventId | string | 是 | 发送的事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 470| data | [GenericEventData<T\>](#genericeventdatat12) | 否 | 事件携带的数据。 | 471 472**示例：** 473 474```ts 475@Sendable 476class Sample { 477 constructor() { 478 this.count = 100; 479 } 480 printCount() { 481 console.info('Print count : ' + this.count); 482 } 483 count: number; 484} 485 486let eventData: emitter.GenericEventData<Sample> = { 487 data: new Sample() 488}; 489emitter.emit("eventId", eventData); 490``` 491 492## emitter.emit<sup>11+</sup> 493 494emit(eventId: string, options: Options, data?: EventData): void 495 496发送指定优先级事件。 497 498**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 499 500**系统能力**: `SystemCapability.Notification.Emitter` 501 502**参数：** 503 504| 参数名 | 类型 | 必填 | 说明 | 505| ------- | ----------------------- | ---- | ---------------- | 506| eventId | string | 是 | 发送的事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 507| options | [Options](#options11) | 是 | 事件优先级。 | 508| data | [EventData](#eventdata) | 否 | 事件携带的数据。 | 509 510**示例：** 511 512```ts 513let eventData: emitter.EventData = { 514 data: { 515 "content": "content", 516 "id": 1, 517 } 518}; 519 520let options: emitter.Options = { 521 priority: emitter.EventPriority.HIGH 522}; 523 524emitter.emit("eventId", options, eventData); 525``` 526 527## emitter.emit<sup>12+</sup> 528 529emit<T\>(eventId: string, options: Options, data?: GenericEventData<T\>): void 530 531发送指定优先级事件。 532 533**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 534 535**系统能力**: `SystemCapability.Notification.Emitter` 536 537**参数：** 538 539| 参数名 | 类型 | 必填 | 说明 | 540| ------- | ----------------------- | ---- | ---------------- | 541| eventId | string | 是 | 发送的事件ID。取值为长度不超过10240字节的自定义字符串，且不可为空字符。 | 542| options | [Options](#options11) | 是 | 事件优先级。 | 543| data | [GenericEventData<T\>](#genericeventdatat12) | 否 | 事件携带的数据。 | 544 545**示例：** 546 547```ts 548@Sendable 549class Sample { 550 constructor() { 551 this.count = 100; 552 } 553 printCount() { 554 console.info('Print count : ' + this.count); 555 } 556 count: number; 557} 558 559let options: emitter.Options = { 560 priority: emitter.EventPriority.HIGH 561}; 562let eventData: emitter.GenericEventData<Sample> = { 563 data: new Sample() 564}; 565 566emitter.emit("eventId", options, eventData); 567``` 568 569## emitter.getListenerCount<sup>11+</sup> 570 571getListenerCount(eventId: number | string): number 572 573获取指定事件的订阅数。 574 575**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 576 577**系统能力**: `SystemCapability.Notification.Emitter` 578 579**参数：** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| ------- | -------------- | ---- | -------- | 583| eventId | number \| string | 是 | 事件ID，string类型的eventId不支持空字符串。 | 584 585**示例：** 586 587```ts 588let count = emitter.getListenerCount("eventId"); 589``` 590 591## EventPriority 592 593表示事件的优先级。 594 595**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 596 597**系统能力**: `SystemCapability.Notification.Emitter` 598 599| 名称 | 值 | 说明 | 600| --------- | ---- | --------------------------------------------------- | 601| IMMEDIATE | 0 | 表示事件被立即投递。 | 602| HIGH | 1 | 表示事件先于LOW优先级投递。 | 603| LOW | 2 | 表示事件优于IDLE优先级投递，事件的默认优先级是LOW。 | 604| IDLE | 3 | 表示在没有其他事件的情况下，才投递该事件。 | 605 606## InnerEvent 607 608订阅或发送的事件，订阅事件时`EventPriority`不生效。 609 610**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 611 612**系统能力**: `SystemCapability.Notification.Emitter` 613 614| 名称 | 类型 | 只读 | 可选 | 说明 | 615| -------- | ------------------------------- | ---- | ---- | ------------------------------ | 616| eventId | number | 否 | 否 | 事件ID，由开发者定义，用于辨别事件。 | 617| priority | [EventPriority](#eventpriority) | 否 | 是 | 事件的优先级，默认值为EventPriority.LOW。 | 618 619## EventData 620 621发送事件时传递的数据。 622 623**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 624 625**系统能力**: `SystemCapability.Notification.Emitter` 626 627| 名称 | 类型 | 只读 | 可选 | 说明 | 628| ---- | ------------------ | ---- | ---- | -------------- | 629| data | { [key: string]: any } | 否 | 是 | 发送事件时传递的数据，支持数据类型包括Array、ArrayBuffer、Boolean、DataView、Date、Error、Map、Number、Object、Primitive（除了symbol）、RegExp、Set、String、TypedArray，数据大小最大为16M。 | 630 631## Options<sup>11+</sup> 632 633发送事件的优先级。 634 635**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 636 637**系统能力**: `SystemCapability.Notification.Emitter` 638 639| 名称 | 类型 | 只读 | 可选 | 说明 | 640| -------- | ------------------------------- | ---- | ---- | -------------- | 641| priority | [EventPriority](#eventpriority) | 否 | 是 | 事件的优先级，默认值为EventPriority.LOW。 | 642 643## GenericEventData<T\><sup>12+</sup> 644 645发送事件时传递的泛型数据。 646 647**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 648 649**系统能力**: `SystemCapability.Notification.Emitter` 650 651| 名称 | 类型 | 只读 | 可选 | 说明 | 652| -------- | ------------------------------- | ---- | ---- | -------------- | 653| data | T | 否 | 是 | 发送事件时传递的数据。T：泛型类型。 |