FlexUI 学习文档索引

面向理解 FlexUI 项目内部机制的学习/梳理型文档（区别于 docs/design/ 的模块设计文档、docs/guide/ 的使用指南）。

每篇以端到端流程为主线，带精确的 file:line 引用，可直接跳转源码。（flexui-engine-modules-overview.md 为参考型模块地图，非流程）

---

文档列表

文档	主题	一句话
flexui-project-overview.md	项目全景	以端到端流程串联所有核心模块（编译 → 打包 → 引擎 → Agent → 渲染），分「业务开发者 / 框架构建者 / 最终用户」三视角
flexui-engine-modules-overview.md	引擎模块地图（参考型）	按功能维度完整梳理 flexui-engine/ 所有模块（基础设施/引擎/渲染/接入/能力/调试），标注独立工程 vs 目录、开源来源、依赖关系
packages-modules-overview.md	内核模块地图（参考型）	完整梳理 packages/ 组件框架内核 4 个模块（core/ascf/shadow-sync/previewer）；@flexui/core = glass-easel 改名 fork，及整条 glass-easel 生态 → FlexUI 血统对照
text-component-render-flow.md	渲染链：text 组件端到端	从 ASCF <text> 封装 → glass-easel Backend → SceneBuilder（JS↔C++ 边界）→ C++ DOM → OHOS 原生 ARKUI_NODE_TEXT 上屏
ohos-component-rendering-analysis.md	渲染层剖析：ArkUI NDK 接口 + 扩展方式	鸿蒙端 C-API 建节点主路径用到的全部 ArkUI NDK 接口；NDK 没有的组件如何扩展（自绘 ARKUI_NODE_CUSTOM / 逃生舱嵌 ArkTS 组件 / XComponent）；canvas、map 可行性
as-apis-engine-integration.md	模块契约：as_apis 如何与引擎配合	从引擎模块系统视角，梳理 as_apis HAR 模块的注册、发现、实例化、运行时调用、销毁全流程，以及 FlexUINativeModuleBase / FlexUIModuleManager / FlexUIAPIProvider 等关键接口
ascf-jsapi-bridge.md	能力链：ASCF JSAPI 桥接	wx.* 小程序 API 如何经 as_apis 模块（Layer 2 分发 + Layer 1 实现）落到鸿蒙 @kit.*，再回调 JS
js-native-bridge-call-patterns.md	桥接机制：JS ↔ Native 调用模式全解	梳理 JS 调用 Native 的所有场景（fire-and-forget / 同步 / Promise / 回调 / 手动生命周期 / internalBinding），逐一追踪完整链路，精确到 file:line
flexview-card-load-flow.md	加载链：FlexView url → 卡片上屏	卡片装载全链路（runBundle 执行 pack.js 注册 → loadInstance → __loadInstance__ → run 渲染），并回答 pack.js 里「组件」与「接口调用」分别走渲染桥 / 能力桥的处理方式
flexui-component-extension-guide.md	自定义组件：扩展组件开发指南	从零创建自定义原生渲染组件（JS 注册 → ArkTS 视图 → 引擎注入），以 BadgeView 为完整示例，含端到端数据流与常见问题解决方案
flexui-engine-ohos-usage-guide.md	使用指导：引擎 OHOS 平台接入	基于改名后最新代码的接入指南：FlexUIEngine.ensureInit + FlexView 卡片路线（推荐）与 createFlexUIEngine + FlexUIRoot 底层路线，含 Hippy→FlexUI 命名对照、配置项/回调/状态码表、构建命令与 FAQ

---

阅读顺序建议

① flexui-project-overview.md   —— 先建立全局地图（两条价值链、7 大子系统、9 步流程）
        │   （配套 flexui-engine-modules-overview.md —— 引擎内部模块地图，随时查阅）
        │
        ├─ ①′ flexview-card-load-flow.md            —— 卡片装载链（FlexView url → pack.js 注册 → loadInstance → 渲染），两条桥的「接通」过程
        │
        ├─ ② text-component-render-flow.md         —— 深入「画界面」这条桥（渲染链，端到端 + 代码位置）
        │       └─ ②′ ohos-component-rendering-analysis.md —— 鸿蒙渲染层剖析（ArkUI NDK 接口 + 组件扩展方式）
        │
        └─ ③ ascf-jsapi-bridge.md                  —— 深入「调能力」这条桥（JSAPI 链）

FlexUI JS 侧对原生的调用分两条并列的桥，②③ 正好各讲一条：

技能包/组件 JS
   ├─ 渲染：new FlexUI.SceneBuilder().create/build   → 原生渲染   （见 ②）
   └─ 能力：wx.setStorage / wx.request / wx.login     → 鸿蒙 Kit   （见 ③）

---

待补充（Roadmap）

按需扩展，保持「一篇一条端到端链路」的粒度：

• image / scroll-view 等其它组件的渲染差异（对照 text 链）
• 事件回传链路：原生手势（tap）→ C++ → JS glass-easel（bind:tap 触发）
• 样式链路：CSS 字符串（color / rpx）→ C++ → ARKUI_NODE_TEXT 属性值的转换
• Agent 主循环：AgentLoop（think → tool-call → card 渲染）端到端
• 技能包编译链路：.hxml/.css → WASM 编译器 → .pack.js

---

相关目录：docs/design/（模块设计）· docs/dev-pitfalls.md（踩坑排查）· docs/engine/（引擎文档）