Designing a Multi‑Language Event System for Taro on Harmony OS

Background

In the Harmony ecosystem native apps are usually written in ArkTS, but using C++ can significantly boost framework and business performance. Taro integrates the Harmony C‑API, sinking component and layout runtime logic to the C++ layer, which greatly improves page rendering speed.

Multi‑Language Event Handling Mechanism

The event system drives the lifecycle of applications, pages and components, and acts as a bridge that allows JavaScript to invoke native ArkTS capabilities.

Design Considerations for a Cross‑Language Event‑Driven Architecture

When designing an event architecture that spans ArkTS, JavaScript and C++, it is essential to consider the constraints and runtime differences of each language and ensure ordered, efficient event propagation across them.

By implementing the low‑level event logic in C++, a high‑performance event management system avoids redundant interfaces and, together with the Harmony C-API , distributes events to the appropriate language environment while maintaining order and efficiency.

Since Taro first adapted to Harmony, the event system has evolved from a simple implementation in ArkTS to a more complete solution, confronting limitations introduced by ArkTS.

Limitations of the ArkTS Event Architecture

The ArkTS‑based event model suffers from poor performance during event bubbling, heavy syntax overhead, and callbacks that can block the main thread, degrading user experience.

Moving event handling to the C++ layer and executing it on background threads improves execution efficiency and prevents main‑thread blocking, resulting in smoother applications.

Building a Multi‑Language Event System

The system must handle various event types provided by Harmony, such as generic component events and gestures, and manage them through an event center while allowing developers to listen and dispatch events in a controlled order.

Implementation of the Event Center

The event center, a core module of the Taro runtime, registers event queues in background threads and dispatches events asynchronously, reducing main‑thread load and providing robust error handling.

Event Listening and Dispatch

Developers can create listeners in C++, ArkTS or JavaScript and add callbacks to the event queue, enabling flexible cross‑language event handling.

When an event fires, its parameters are converted to the appropriate format for each language environment, ensuring correct interpretation of simple data types and complex objects.

The event queue dispatches events to listeners in a predefined order based on their type, allowing each listener to execute its callback efficiently in its own language runtime.

Note: In ArkTS, registered events must return to the main thread for execution, and Symbol‑type events are not supported on Harmony.

Node Event Handling (domEvent)

Node events follow the classic DOM propagation model: they start at the root, travel down to the target, trigger, then bubble back up. Taro reproduces this model on Harmony to provide a consistent developer experience.

Event Types

Taro handles three node event categories: Harmony events, Harmony gesture events, and custom events. These are listened to and triggered from TaroElement via a Receiver (event receiver).

Harmony events and gestures are registered to a RenderNode and then to a Receiver , while custom events are emitted by the node or user code as needed.

Event Propagation

After a TaroElement triggers an event, it propagates upward through the node tree. Each node may stop propagation, allowing developers to intercept or modify business logic at any point.

The underlying Harmony node event mechanism differs from the ArkNode tree; to avoid interference, its bubbling must be stopped and its propagation manually managed.

Event Callbacks

Callback objects expose standard Web properties such as target , stopPropagation , and value , ensuring that when events cross language boundaries their semantics remain consistent.

Many C++ components rely on this event mechanism to update properties, pass data between nodes, and keep the UI responsive.

Summary and Outlook

Ensuring consistent event transmission across multiple language environments improves maintainability and speeds up inter‑module collaboration. The current solution already boosts response time and modular cooperation.

Remaining challenges include early workarounds that bypass ArkTS‑JS call restrictions; these could be addressed with TurboModule for more direct calls.

Future Taro for Harmony releases will further strengthen cross‑language module coordination, using the event system as a decoupling backbone for more flexible composition.