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