1# @ohos.events.emitter (Emitter) 2 3本模块提供了在同一进程不同线程间，或同一进程同一线程内，发送和处理事件的能力，包括持续订阅事件、单次订阅事件、取消订阅事件，以及发送事件到事件队列的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import emitter from '@ohos.events.emitter'; 13``` 14 15## 权限列表 16 17无权限要求。 18 19## emitter.on 20 21on(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void 22 23持续订阅指定的事件，并在接收到该事件时，执行对应的回调处理函数。 24 25**系统能力**: `SystemCapability.Notification.Emitter` 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| -------- | ----------------------------------- | ---- | ------------------------------------------------------ | 31| event | [InnerEvent](#innerevent) | 是 | 持续订阅的事件，其中[EventPriority](#eventpriority)，在订阅事件时无需指定，也不生效 | 32| callback | Callback\<[EventData](#eventdata)\> | 是 | 接收到该事件时需要执行的回调处理函数 | 33 34**示例：** 35 36```ts 37let innerEvent: emitter.InnerEvent = { 38 eventId: 1 39}; 40 41// 收到eventId为1的事件后执行回调函数 42emitter.on(innerEvent, () => { 43 console.info('callback'); 44}); 45``` 46 47## emitter.once 48 49once(event: [InnerEvent](#innerevent), callback: Callback\<[EventData](#eventdata)\>): void 50 51单次订阅指定的事件，并在接收到该事件并执行完相应的回调函数后，自动取消订阅。 52 53**系统能力**: `SystemCapability.Notification.Emitter` 54 55**参数：** 56 57| 参数名 | 类型 | 必填 | 说明 | 58| -------- | ----------------------------------- | ---- | ------------------------------------------------------------------------------ | 59| event | [InnerEvent](#innerevent) | 是 | 单次订阅的事件，其中[EventPriority](#eventpriority)，在订阅事件时无需指定，也不生效 | 60| callback | Callback\<[EventData](#eventdata)\> | 是 | 接收到该事件时需要执行的回调处理函数 | 61 62**示例：** 63 64```ts 65let innerEvent: emitter.InnerEvent = { 66 eventId: 1 67}; 68 69// 收到eventId为1的事件后执行该回调函数 70emitter.once(innerEvent, () => { 71 console.info('once callback'); 72}); 73``` 74 75## emitter.off 76 77off(eventId: number): void 78 79取消针对该事件ID的订阅。 80 81**系统能力**: `SystemCapability.Notification.Emitter` 82 83**参数：** 84 85| 参数名 | 类型 | 必填 | 说明 | 86| ------- | ------ | ---- | ------ | 87| eventId | number | 是 | 事件ID | 88 89**示例：** 90 91```ts 92// 取消eventID为1的所有事件回调处理函数 93emitter.off(1); 94``` 95 96## emitter.off<sup>10+<sup> 97 98off(eventId: number, callback: Callback\<[EventData](#eventdata)\>): void 99 100取消针对该事件ID的订阅，传入可选参数callback，并且该callback已经通过on或者once接口订阅，则取消该订阅；否则，不做任何处理。 101 102**系统能力**: `SystemCapability.Notification.Emitter` 103 104**参数：** 105 106| 参数名 | 类型 | 必填 | 说明 | 107| ------- | ------ | ---- | ------ | 108| eventId | number | 是 | 事件ID | 109| callback<sup>10+</sup> | Callback\<[EventData](#eventdata)\> | 是 | API version 10 新增取消该事件的回调处理函数。 | 110 111**示例：** 112 113```ts 114// 取消eventID为1的事件回调处理函数 emitterCallback 115// 如果该回调处理函数没有被订阅，则不做任何处理 116emitter.off(1, () => { 117 console.info('callback'); 118}); 119``` 120 121## emitter.emit 122 123emit(event: [InnerEvent](#innerevent), data?: [EventData](#eventdata)): void 124 125发送指定的事件。 126 127**系统能力**: `SystemCapability.Notification.Emitter` 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| ------ | ------------------------- | ---- | ------------- | 133| event | [InnerEvent](#innerevent) | 是 | 发送的事件，其中[EventPriority](#eventpriority)用于指定事件被发送的优先级 | 134| data | [EventData](#eventdata) | 否 | 事件携带的数据 | 135 136**示例：** 137 138```ts 139let eventData: emitter.EventData = { 140 data: { 141 "content": "c", 142 "id": 1, 143 } 144}; 145 146let innerEvent: emitter.InnerEvent = { 147 eventId: 1, 148 priority: emitter.EventPriority.HIGH 149}; 150 151emitter.emit(innerEvent, eventData); 152``` 153 154## EventPriority 155 156用于表示事件被发送的优先级。 157 158**系统能力**: `SystemCapability.Notification.Emitter` 159 160| 名称 | 值 | 说明 | 161| --------- | ---- | --------------------------------------------------- | 162| IMMEDIATE | 0 | 表示事件被立即投递。 | 163| HIGH | 1 | 表示事件先于LOW优先级投递。 | 164| LOW | 2 | 表示事件优于IDLE优先级投递，事件的默认优先级是LOW。 | 165| IDLE | 3 | 表示在没有其他事件的情况下，才投递该事件。 | 166 167## InnerEvent 168 169订阅或发送的事件，订阅事件时`EventPriority`不生效。 170 171**系统能力**: `SystemCapability.Notification.Emitter` 172 173| 名称 | 类型 | 可读 | 可写 | 说明 | 174| -------- | ------------------------------- | ---- | ---- | ------------------------------ | 175| eventId | number | 是 | 是 | 事件ID，由开发者定义用来辨别事件。 | 176| priority | [EventPriority](#eventpriority) | 是 | 是 | 事件被投递的优先级。 | 177 178## EventData 179 180发送事件时传递的数据。 181 182**系统能力**: `SystemCapability.Notification.Emitter` 183 184| 名称 | 类型 | 可读 | 可写 | 说明 | 185| ---- | ------------------ | ---- | ---- | -------------- | 186| data | [key: string]: any | 是 | 是 | 发送事件时传递的数据，数据类型支持字符串、整型和布尔型。<br> 其中字符串长度最大为10240字节。 | 187