How nervjs/taro-harmony-capi-library works
Project Type and Purpose
• The project is a C++ library intended for building a UI and runtime engine. It integrates JavaScript execution (via JSI executors and QuickJS implementations), DOM management, CSS styling (cssom), animation, event handling, and native module exports.
• The library seems to focus on bridging JavaScript with native C++ operations (as seen in directories like arkjs and engine) and offers extensive runtime modules (in the runtime directory) that manage DOM nodes, stylesheets, and event handling.
File Structure – Identify Main Modules
• arkjs: Contains core files (ArkJS.cpp/h, ArkTSBridge.cpp/h, Scope.h). This module likely handles JavaScript integration and provides the interface for bridging types and executing JS code from C++.
• engine: This module is split into several parts:
– jsi_executor: Implements JavaScript invocation/execution functions. It includes native module support and factories for QuickJS executors.
– quickjs_jsi and react_common: Provide runtime support using the QuickJS engine and React integration patterns (invoking methods, managing module registries, handling callbacks).
• exports: Likely exposes public APIs for document/model management, event handling, and framework integration (notably for React and NAPI bridges).
• runtime: This is the largest module and includes subdirectories for:
– API: Specific node APIs.
– cssom: CSS Object Model – handling stylesheets, parsers, dimensions, fonts, and their parameters.
– dom: Manages everything from node definitions, element rendering, animations, events (including complex gesture, touch, and user events) to event factories.
– Other runtime functionalities such as vsync, resource management, and rendering.
• helper: Contains various utility functions and classes (e.g., file management, logging, timer, string/array utilities) that underpin different modules.
• system and taro: Provide system and instance management functionalities, as well as native logging and possibly platform-specific adjustments.
• thread: Manages task runners, executors, and threading functionality ensuring asynchronous and concurrent task handling.
• patches: Contains configuration adjustments and patches for third-party libraries (e.g., folly, libevent) to support the cross-platform or embedded requirements.
• types: Contains TypeScript definition files and scripts; likely to aid in integration with TypeScript/JS frameworks or serve as API contracts.
Components Impacting the Architecture
• JavaScript Integration: arkjs and engine modules manage JavaScript execution, bridging the gap between native C++ and JS runtime (using JSI executors and factories).
• Rendering and DOM: The runtime directory’s extensive sub-modules (dom, cssom, animation, event) represent the system’s rendering engine and dynamic UI behavior.
• API and Exports: The exports folder, along with taro and runtime/api, exposes interfaces for developers to interact with the library.
• Concurrency: The thread module indicates a design that employs multi-threading and asynchronous task handling.
• External Integration: Files like commitlint.config.js, CMakeLists.txt, patches for external libraries, and GitHub workflows hint at continuous integration and automated build processes.
Relationships and Interactions
• The engine module interacts with arkjs and the runtime to provide a smooth JavaScript execution environment that supports the UI system.
• The runtime’s DOM, CSSOM, and event components work in tandem to construct a dynamic user interface driven by the underlying engine.
• Helper utilities are used across modules to provide cross-cutting concerns such as logging, file operations, and performance metrics.
• The exports layer serves as the interface between the library’s core functionality and clients (for native module integration or exposing APIs to higher-level applications).
• The test directory (and CI configurations under .github/workflows) ensures architectural reliability and proper functioning of these interactions.
Important Architectural Patterns
• Modularity: The project is clearly divided into modules by functionality (engine, runtime, helper, etc.), which aids in separation of concerns.
• Layered Architecture: Lower-level utilities and patches support the mid-level execution (JSI engines and helper libraries) and high-level runtime features (DOM, CSSOM, events).
• Plugin/Bridge Patterns: The presence of bridge files (e.g., ArkTSBridge) and multiple executor factories point towards an extensible design that can integrate with different JavaScript runtimes.
• Event-Driven and Asynchronous Processing: The threading and event modules emphasize asynchronous data flows, common in UI frameworks.