NandinaUI

一个「Core + Bindings」架构的 UI 框架：Zig 实现核心，C ABI 发布，多语言绑定消费。

NandinaUI 把现代前端的成熟范式带到原生 UI 开发：

• Flutter 式组件编写语法 —— 声明式、可链式组合，描述结构而非几何坐标。
• Angular 式响应式（signal） —— 以 signal / computed / effect 驱动数据更新；并吸收 Angular 的 page / router 机制。
• shadcn 式设计体系 —— primitives 全局组件源语 + 通用设计 token，把功能拆成最小 node，新组件不断复用。
• Core + Bindings 架构 —— Zig 核心一次实现，通过 C ABI 导出；C++ 等语言可通过绑定层使用相同能力。
• 可替换渲染后端 —— 软件光栅（默认）、ThorVG 矢量渲染可切换，不改上层代码；Vulkan/wgpu 预留。
• 借鉴 EUI-NED 的文字渲染机制、slint 的组件挂载机制、Qt QML 的组件设计方式。

状态：Zig 重写推进中。Core 层（foundation → widgets）已基本落地并有测试覆盖。 C ABI、Zig/C++ 双前端、showcase 可视化画廊已完成；多页导航（Page/Router）与全包窗口入口已可用。 旧 C++/QML 主线已归档在 archive/，其设计文档作为语义参照保留。 详细路线图见 docs/development/roadmap.md。

快速开始

需要 Zig 0.16.0。

zig build run      # 运行 Zig 前端可视化画廊（SDL3 窗口）
zig build run-cpp  # 运行 C++ 前端可视化画廊（同组页面对照）
zig build test     # 运行全部分层单元测试

更完整的入门见 使用指南 · 快速开始。

分层结构

Core 层（Zig，src/）

foundation → {reactive, render, layout, theme, text} → runtime → widgets → app

层	职责	状态
foundation	几何（Point/Size/Rect/Insets）、颜色	✅ 已落地
reactive	signal / computed / effect / 依赖追踪 / batch	✅ 已落地
render	Scene / DrawCommand / Backend 接口	✅ 已落地
layout	constraints / measure-layout / Row·Column·Stack	✅ 已落地
theme	design token / palette / Theme resolver	✅ 已落地
text	字体、文本测量与布局	✅ 已落地
runtime	Node 树、事件循环、调度边界	✅ 纯逻辑核心已落地
widgets	primitives + controls	✅ 首批已落地
app	page / router / 挂载入口	🚧 骨架

ABI + Bindings 层（src/abi/ + frontend/）

层	职责	状态
abi	C ABI 导出（extern "C" 函数 + 不透明句柄）	✅ 已落地
frontend/zig	Zig 前端绑定（直通 Core，收敛再导出）	✅ 已落地
frontend/cpp	C++ 前端绑定（C ABI 之上的 RAII + 链式）	✅ 已落地

渲染后端（可替换）

render/Backend（vtable 接口）
├── render/backends/software.zig  — 纯 Zig 软件光栅（默认） ✅
├── render/backends/thorvg.zig    — ThorVG 矢量渲染 🚧（文字渲染待补）
└── render/backends/vulkan.zig    — Vulkan GPU 渲染（未来）  🗓

当前默认后端为 software（纯 Zig 软件光栅），ThorVG 暂不渲染文字。 HarfBuzz 链接但未启用 text shaping（kerning / 复杂文字待办）。 详见 docs/development/showcase-refactor-plan.md §11

文档

文档分为两条线，入口见 docs/README.md：

• 开发文档 docs/development/ —— 面向贡献者：架构、依赖规则、各子系统设计规范、路线图。
• 使用参考文档 docs/guide/ —— 面向库使用者：快速开始、核心概念、主题定制。
• 就近使用说明 —— 每个 src/<layer>/README.md 说明该层/组件如何使用，便于在代码旁查看。

构建产物

zig build 产出：

产物	说明
NandinaUI	Zig 前端 showcase（SDL3 可视化画廊）
NandinaUI-cpp	C++ 前端 showcase（同组页面对照）
libnandina_abi.a	C ABI 静态库，供绑定层使用
nandina_abi.h	C ABI 头文件（安装到 include/）

许可证

见仓库 LICENSE（如有）。