harmony 鸿蒙@ohos.events.emitter (Emitter)

  • 2025-06-12
  • 浏览 (4)

@ohos.events.emitter (Emitter)

The Emitter module provides the capabilities of sending and processing inter- or intra-thread events in a process. You can use the APIs of this module to subscribe to an event in persistent or one-shot manner, unsubscribe from an event, or emit an event to the event queue.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { emitter } from '@kit.BasicServicesKit';

Required Permissions

None.

emitter.on

on(event: InnerEvent, callback: Callback<EventData>): void

Subscribes to an event in persistent manner and executes a callback after the event is received.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
event InnerEvent Yes Event to subscribe to in persistent manner. The EventPriority parameter is not required and does not take effect.
callback Callback<EventData> Yes Callback to be executed when the event is received.

Example

import { Callback} from '@kit.BasicServicesKit';

let innerEvent: emitter.InnerEvent = {
  eventId: 1
};

let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
  console.info(`eventData: ${JSON.stringify(eventData)}`);
}

// Execute the callback after receiving the event whose eventId is 1.
emitter.on(innerEvent, callback);

emitter.on11+

on(eventId: string, callback: Callback<EventData>): void

Subscribes to an event in persistent manner and executes a callback after the event is received.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event to subscribe to in persistent manner. The value cannot be an empty string and exceed 10240 bytes.
callback Callback<EventData> Yes Callback to be executed when the event is received.

Example

import { Callback} from '@kit.BasicServicesKit';

let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
  console.info(`eventData: ${JSON.stringify(eventData)}`);
}
// Execute the callback after receiving the event whose eventId is eventId.
emitter.on(`eventId`, callback);

emitter.on12+

on(eventId: string, callback: Callback<GenericEventData>): void

Subscribes to an event in persistent manner and executes a callback after the event is received.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event to subscribe to in persistent manner. The value cannot be an empty string and exceed 10240 bytes.
callback Callback<GenericEventData> Yes Callback to be executed when the event is received.

Example

import { Callback} from '@kit.BasicServicesKit';

@Sendable
class Sample {
  constructor() {
    this.count = 100;
  }
  printCount() {
    console.info('Print count : ' + this.count);
  }
  count: number;
}

let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => {
  console.info(`eventData: ${JSON.stringify(eventData?.data)}`);
  if (eventData?.data instanceof Sample) {
    eventData?.data?.printCount();
  }
}
// Execute the callback after receiving the event whose eventId is eventId.
emitter.on("eventId", callback);

emitter.once

once(event: InnerEvent, callback: Callback<EventData>): void

Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
event InnerEvent Yes Event to subscribe to in one-shot manner. The EventPriority parameter is not required and does not take effect.
callback Callback<EventData> Yes Callback to be executed when the event is received.

Example

import { Callback} from '@kit.BasicServicesKit';

let innerEvent: emitter.InnerEvent = {
  eventId: 1
};

let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
  console.info(`eventData: ${JSON.stringify(eventData)}`);
}
// Execute the callback after receiving the event whose eventId is 1.
emitter.once(innerEvent, callback);

emitter.once11+

once(eventId: string, callback: Callback<EventData>): void

Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event to subscribe to in one-shot manner. The value cannot be an empty string and exceed 10240 bytes.
callback Callback<EventData> Yes Callback to be executed when the event is received.

Example

import { Callback} from '@kit.BasicServicesKit';

let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
  console.info(`eventData: ${JSON.stringify(eventData)}`);
}
// Execute the callback after receiving the event whose eventId is eventId.
emitter.once("eventId", callback);

emitter.once12+

once(eventId: string, callback: Callback<GenericEventData>): void

Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event to subscribe to in one-shot manner. The value cannot be an empty string and exceed 10240 bytes.
callback Callback<GenericEventData> Yes Callback to be executed when the event is received.

Example

import { Callback} from '@kit.BasicServicesKit';

@Sendable
class Sample {
  constructor() {
    this.count = 100;
  }
  printCount() {
    console.info('Print count : ' + this.count);
  }
  count: number;
}

let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => {
  console.info(`eventData: ${JSON.stringify(eventData?.data)}`);
  if (eventData?.data instanceof Sample) {
    eventData?.data?.printCount();
  }
}
// Execute the callback after receiving the event whose eventId is eventId.
emitter.once("eventId", callback);

emitter.off

off(eventId: number): void

Unsubscribes from all events with the specified event ID.

After this API is used to unsubscribe from an event, the event that has been published through the emit API but has not been executed will be unsubscribed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId number Yes Event ID.

Example

// Unregister the callbacks of all events whose eventID is 1.
emitter.off(1);

emitter.off11+

off(eventId: string): void

Unsubscribes from all events with the specified event ID.

After this API is used to unsubscribe from an event, the event that has been published through the emit API but has not been executed will be unsubscribed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event ID. The value cannot be an empty string and exceed 10240 bytes.

Example

// Unregister the callbacks of all events whose eventID is eventId.
emitter.off("eventId");

emitter.off10+

off(eventId: number, callback: Callback<EventData>): void

Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when Callback<EventData> has been registered through the on or once API. Otherwise, no processing is performed.

After this API is used to unsubscribe from an event, the event that has been published through the emit API but has not been executed will be unsubscribed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId number Yes Event ID.
callback Callback<EventData> Yes Callback to unregister.

Example

import { Callback} from '@kit.BasicServicesKit';

let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
  console.info(`eventData: ${JSON.stringify(eventData)}`);
}
// Unregister the callback of the event whose eventID is 1. The callback object must be the registered object.
// If the callback has not been registered, no processing is performed.
emitter.off(1, callback);

emitter.off11+

off(eventId: string, callback: Callback<EventData>): void

Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when Callback<EventData> has been registered through the on or once API. Otherwise, no processing is performed.

After this API is used to unsubscribe from an event, the event that has been published through the emit API but has not been executed will be unsubscribed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event ID. The value cannot be an empty string and exceed 10240 bytes.
callback Callback<EventData> Yes Callback to unregister.

Example

import { Callback} from '@kit.BasicServicesKit';

let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => {
  console.info(`eventData: ${JSON.stringify(eventData)}`);
}
// Unregister the callback of the event whose eventID is eventId. The callback object must be the registered object.
// If the callback has not been registered, no processing is performed.
emitter.off("eventId", callback);

emitter.off12+

off(eventId: string, callback: Callback<GenericEventData>): void

Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when Callback<EventData> has been registered through the on or once API. Otherwise, no processing is performed.

After this API is used to unsubscribe from an event, the event that has been published through the emit API but has not been executed will be unsubscribed.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes Event ID. The value cannot be an empty string and exceed 10240 bytes.
callback Callback<GenericEventData> Yes Callback to unregister.

Example

import { Callback} from '@kit.BasicServicesKit';

@Sendable
class Sample {
  constructor() {
    this.count = 100;
  }
  printCount() {
    console.info('Print count : ' + this.count);
  }
  count: number;
}

let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => {
  console.info(`eventData: ${JSON.stringify(eventData?.data)}`);
  if (eventData?.data instanceof Sample) {
    eventData?.data?.printCount();
  }
}
// Unregister the callback of the event whose eventID is eventId. The callback object must be the registered object.
// If the callback has not been registered, no processing is performed.
emitter.off("eventId", callback);

emitter.emit

emit(event: InnerEvent, data?: EventData): void

Emits the specified event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
event InnerEvent Yes Event to emit, where EventPriority specifies the emit priority of the event.
data EventData No Data passed in the event.

Example

let eventData: emitter.EventData = {
  data: {
    "content": "content",
    "id": 1,
  }
};

let innerEvent: emitter.InnerEvent = {
  eventId: 1,
  priority: emitter.EventPriority.HIGH
};

emitter.emit(innerEvent, eventData);

emitter.emit11+

emit(eventId: string, data?: EventData): void

Emits the specified event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes ID of the event to emit. The value cannot be an empty string and exceed 10240 bytes.
data EventData No Data passed in the event.

Example

let eventData: emitter.EventData = {
  data: {
  "content": "content",
  "id": 1,
  }
};

emitter.emit("eventId", eventData);

emitter.emit12+

emit(eventId: string, data?: GenericEventData): void

Emits the specified event.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes ID of the event to emit. The value cannot be an empty string and exceed 10240 bytes.
data GenericEventData No Data passed in the event.

Example

@Sendable
class Sample {
  constructor() {
    this.count = 100;
  }
  printCount() {
    console.info('Print count : ' + this.count);
  }
  count: number;
}

let eventData: emitter.GenericEventData<Sample> = {
  data: new Sample()
};
emitter.emit("eventId", eventData);

emitter.emit11+

emit(eventId: string, options: Options, data?: EventData): void

Emits an event of a specified priority.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes ID of the event to emit. The value cannot be an empty string and exceed 10240 bytes.
options Options Yes Event emit priority.
data EventData No Data passed in the event.

Example

let eventData: emitter.EventData = {
  data: {
    "content": "content",
    "id": 1,
  }
};

let options: emitter.Options = {
  priority: emitter.EventPriority.HIGH
};

emitter.emit("eventId", options, eventData);

emitter.emit12+

emit(eventId: string, options: Options, data?: GenericEventData): void

Emits an event of a specified priority.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId string Yes ID of the event to emit. The value cannot be an empty string and exceed 10240 bytes.
options Options Yes Event emit priority.
data GenericEventData No Data passed in the event.

Example

@Sendable
class Sample {
  constructor() {
    this.count = 100;
  }
  printCount() {
    console.info('Print count : ' + this.count);
  }
  count: number;
}

let options: emitter.Options = {
  priority: emitter.EventPriority.HIGH
};
let eventData: emitter.GenericEventData<Sample> = {
  data: new Sample()
};

emitter.emit("eventId", options, eventData);

emitter.getListenerCount11+

getListenerCount(eventId: number|string): number

Obtains the number of subscriptions to a specified event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Parameters

Name Type Mandatory Description
eventId number |string Yes Event ID. The value of the string type cannot be an empty string.

Example

let count = emitter.getListenerCount("eventId");

EventPriority

Enumerates the event priorities.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Name Value Description
IMMEDIATE 0 The event will be emitted immediately.
HIGH 1 The event will be emitted before low-priority events.
LOW 2 The event will be emitted before idle-priority events. By default, an event is in LOW priority.
IDLE 3 The event will be emitted after all the other events.

InnerEvent

Describes an event to subscribe to or emit. The EventPriority settings do not take effect under event subscription.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Name Type Read Only Optional Description
eventId number No No Event ID.
priority EventPriority No Yes Event priority. The default value is EventPriority.LOW.

EventData

Describes the data passed in the event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.Emitter

Name Type Read Only Optional Description
data { [key: string]: any } No Yes Data passed in the event. The value can be in any of the following types: Array, ArrayBuffer, Boolean, DataView, Date, Error, Map, Number, Object, Primitive (except symbol), RegExp, Set, String, and TypedArray. The maximum data size is 16 MB.

Options11+

Describes the event emit priority.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Name Type Read Only Optional Description
priority EventPriority No Yes Event priority. The default value is EventPriority.LOW.

GenericEventData12+

Describes the generic data passed in the event.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Notification.Emitter

Name Type Read Only Optional Description
data T No Yes Data passed in the event. T: generic type.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Basic Services Kit

harmony 鸿蒙DeviceInfo

harmony 鸿蒙InitSync

harmony 鸿蒙OH_Print

harmony 鸿蒙OsAccount

harmony 鸿蒙Pasteboard

harmony 鸿蒙Print_Margin

harmony 鸿蒙Print_PageSize

harmony 鸿蒙Print_PrintAttributes

harmony 鸿蒙Print_PrintDocCallback

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/4OQELy
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录