FlexUI Engine 详细设计方案
1. 概述
flexui-engine 是 FlexUI 的跨端原生渲染引擎，派生于腾讯 Hippy 框架，支持 HarmonyOS 和 Android 平台。引擎负责将 FlexUI 的组件树渲染为原生 UI 控件。
1.1 设计目标
- 跨平台原生渲染：将 FlexUI 组件映射为 Android View 或 HarmonyOS ArkUI 组件
- JS 引擎驱动：通过 V8 (Android) / Hermes (HarmonyOS) 执行 JavaScript 逻辑
- 高性能布局：集成 Flexbox 布局引擎
- DOM 兼容层：提供类 Web DOM 接口的 C++ 实现
- DevTools 支持：内置调试和性能分析工具
1.2 平台支持
| 平台 | JS 引擎 | 渲染后端 | 布局引擎 |
|---|---|---|---|
| HarmonyOS | Hermes | ArkUI 原生组件 | Flexbox |
| Android | V8 | Android View 系统 | Flexbox |
2. 架构设计
┌──────────────────────────────────────────────────────┐
│ Entry (OHOS / Android) │
│ ┌──────────────────────────────────────────────────┐ │
│ │ FlexView / Agent UI Page │ │
│ └──────────────────┬───────────────────────────────┘ │
├─────────────────────┼────────────────────────────────┤
│ Driver (JS 运行时) │
│ ┌──────────────────┴───────────────────────────────┐ │
│ │ JS Engine (Hermes / V8) │ │
│ │ ├── hippy-ascf adapter (FlexUI ↔ Hippy 桥接) │ │
│ │ ├── JS Bundle 加载/执行 │ │
│ │ └── Native Module 注册 │ │
│ └──────────────────┬───────────────────────────────┘ │
├─────────────────────┼────────────────────────────────┤
│ DOM (C++ 实现) │
│ ┌──────────────────┴───────────────────────────────┐ │
│ │ Element / Node / Document 树 │ │
│ │ CSS 样式解析与计算 │ │
│ │ Layout (Flexbox) │ │
│ │ Event Dispatch │ │
│ └──────────────────┬───────────────────────────────┘ │
├─────────────────────┼────────────────────────────────┤
│ Framework (平台框架) │
│ ┌──────────────────┴───────────────────────────────┐ │
│ │ android/connector ← C++ ↔ Java ↔ View │ │
│ │ ohos/connector ← C++ ↔ ArkTS ↔ ArkUI │ │
│ └──────────────────┬───────────────────────────────┘ │
├─────────────────────┼────────────────────────────────┤
│ Renderer (原生渲染) │
│ ┌──────────────────┴───────────────────────────────┐ │
│ │ Android: Android View 层级渲染 │ │
│ │ OHOS: ArkUI 原生组件渲染 │ │
│ └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
3. 核心模块
3.1 Entry（入口模块）
HarmonyOS/Android 应用的入口层，负责初始化引擎并加载 FlexUI 页面。
OHOS Entry (flexui-engine/entry/):
entry/
├── src/main/ets/
│ ├── entryability/EntryAbility.ets → 应用入口
│ └── pages/Index.ets → FlexView 演示页面
├── src/main/resources/rawfile/ascf/ → JS Bundle 资源
└── module.json5 → 模块配置
Bundle: 应用包名在 build-profile.json5 中配置
3.2 Driver（JS 驱动层）
负责 JavaScript 引擎的初始化、JS Bundle 加载和 Native Module 注册。
C++ 层 (flexui-engine/driver/js/):
driver/js/
├── include/driver/
│ ├── engine.h → JS 引擎抽象 (Engine)
│ ├── scope.h → JS 作用域
│ └── napi/ → NAPI 绑定层 (Hermes)
│ └── hermes/
│ ├── hermes_ctx.h → Hermes 上下文
│ └── hermes_class_definition.h → Hermes 类定义
├── src/
│ ├── engine.cc → 引擎实现 (VM 创建, 生命周期)
│ └── ...
└── packages/
└── hippy-ascf/ → Hippy-ASCF 适配器 (npm 包)
Engine 核心能力：
- 创建 JS VM (HermesRuntime / V8)
- 管理 JS 作用域 (Scope)
- 注册 Native Module (RegisterMap)
- 保存/查找 ClassTemplate
- 管理 FunctionWrapper 和 CallbackWrapper
hippy-ascf 适配器 (driver/js/packages/hippy-ascf/)：
- 将 FlexUI/ASCF 组件映射到 Hippy 的 Native Module
- 处理组件创建、属性更新、事件分发
- JS 线程与 UI 线程的桥接
3.3 DOM（C++ 实现）
提供类 Web DOM 接口的 C++ 实现，是引擎的布局和渲染核心。
dom/
├── include/dom/
│ ├── element.h → 元素节点
│ ├── node.h → 基础节点
│ ├── document.h → 文档对象
│ └── ...
└── src/dom/
├── element.cc → 元素实现
├── node.cc → 节点实现
└── ...
功能：
- 完整的 DOM 树管理 (父子关系、遍历)
- CSS 属性解析与应用
- Flexbox 布局计算
- 事件系统 (捕获/冒泡/分发)
- 样式继承与层叠
3.4 Framework（平台框架）
连接 C++ DOM 层与原生 UI 控件的桥接层。
Android Framework:
framework/android/connector/
├── dom/ → C++ ↔ Java DOM 连接器
│ └── src/main/cpp/ → JNI 桥接
├── driver/ → JS 引擎 ↔ Native 连接器
│ └── js/ → NativeCallback, NativeRunnable
├── renderer/ → 渲染连接器
└── support/ → 支持库
OHOS Framework:
framework/ohos/
└── connector/ → C++ ↔ ArkTS 连接器
3.5 Modules（平台模块）
提供平台能力的 Native 模块：
modules/
├── android/ → Android 原生能力 (网络、存储、传感器等)
├── ohos/ → HarmonyOS 原生能力
├── footstone/ → 跨平台基础模块 (日志、线程、任务调度)
└── vfs/ → 虚拟文件系统 (资源加载)
3.6 Renderer（原生渲染器）
renderer/native/android/
├── Renderer.java → 抽象渲染器
├── NativeRenderer.java → 原生渲染器实现
├── RenderProxy.java → 渲染代理
├── RenderExceptionHandler.java → 异常处理
└── component/
├── Component.java → 组件基类 (Drawable.Callback)
├── BackgroundDrawable → 背景绘制
├── TextDrawable → 文本绘制
└── RippleDrawable → 涟漪效果
3.7 DevTools（调试工具）
devtools/
├── android/ → Android 调试后端
└── ohos/ → HarmonyOS 调试后端
支持：
- 组件树检查
- 网络请求监控
- 日志查看
- 性能分析
4. 渲染流程
1. Entry Ability 启动
│
2. JS Engine 初始化 (Hermes / V8)
│
3. 加载 JS Bundle (rawfile/ascf/index.js)
│
4. JS 执行 FlexUI 组件代码
│ └── @flexui/core 创建组件树
│
5. hippy-ascf adapter 接收组件操作
│ └── createElement / setAttribute / appendChild 等
│
6. DOM 层创建/更新 C++ Element 树
│ └── CSS 解析 + Flexbox 布局计算
│
7. Framework Connector 将变更传递给 Renderer
│ ├── Android: JNI → Android View 操作
│ └── OHOS: NAPI → ArkUI 组件操作
│
8. 原生 UI 渲染到屏幕
5. JS Bundle
5.1 构建流程
源码 (.hxml/.css/.js)
│
├── flexui-template-compiler (Rust→WASM)
│ └── HXML → ProcGen JS
│
├── flexui-stylesheet-compiler (Rust→WASM)
│ └── CSS 作用域处理
│
└── Webpack (flexui-webpack-plugin)
└── 打包为 JS Bundle
│
└── 复制到 entry/src/main/resources/rawfile/ascf/index.js
5.2 构建命令
# 完整开发周期: webpack → hvigorw → 安装 → 启动
./build.sh dev
# 仅构建 HAP
./build.sh build
# 安装到设备
./build.sh install
# 启动应用
./build.sh start
# 查看日志
./build.sh logs
6. 设计决策
6.1 为什么派生于 Hippy？
- 成熟的跨端方案：Hippy 已在腾讯多个亿级应用中验证
- Flexbox 布局引擎：内建的高性能布局引擎
- JS 引擎抽象：支持 V8、Hermes、JSC 等多种 JS 引擎
- 完善的 Native Module 体系：可复用的平台能力模块
6.2 为什么 DOM 用 C++ 实现？
- 性能：C++ DOM 操作比 JavaScript 快 10-100 倍
- 跨平台共享：Android 和 OHOS 共用同一套 DOM 代码
- 布局计算：Flexbox 布局算法在 C++ 中执行更高效
6.3 hippy-ascf adapter 的角色
Hippy 原始组件模型与 FlexUI/ASCF 不完全一致，adapter 负责：
- 组件标签名映射 (FlexUI → Hippy View)
- 属性格式转换 (FlexUI props → Hippy props)
- 事件类型转换 (FlexUI events → Hippy events)
- Shadow Tree 同步策略适配
6.4 为什么 OHOS 用 Hermes 而非 V8？
- HarmonyOS 原生支持：Hermes 是 OpenHarmony 推荐的 JS 引擎
- 体积更小：Hermes 比 V8 更适合移动端
- AOT 编译：Hermes 支持预编译字节码，减少首屏加载时间