#moon-egui

#概述

#为什么选择 moon-egui？

• 传统 Canvas 逻辑的维护负担：手写按钮坐标计算、命中碰撞检测与图层排序，代码量大且极易产生状态不同步缺陷。
• DOM / 虚拟 DOM 的性能抖动：在 60 FPS 高频画布应用中引入保留模式框架，跨语言/跨边界调用与垃圾回收（GC）容易引发偶发掉帧。
• C/C++ 绑定的工具链门槛：基于 FFI 的外部 GUI 包装依赖复杂的本地编译链，产物体积较大，且无法享受纯粹的包管理体验。

#核心特性

• 即时模式心智：逐帧声明界面，无需维护生命周期回调与双向同步，交互判定就地完成（例如 if ui.button("保存").clicked { ... }）。
• 零 FFI 原生依赖：100% 纯 MoonBit 编写，内核解耦宿主环境，零外部运行时依赖，一行 moon add 即装即用。
• 微秒级帧管线：内置视口空间裁剪与图元合并，单帧内核开销低至 0.1ms，在百万节点画布下稳定跑满 60 FPS。
• 开箱即用套件：内置层级窗口（支持拖拽置顶与视口约束）、标签栏、支持真实键盘输入的文本框、防穿透下拉框与工具提示。

#安装

moon add ling71671/moon-egui

{
  "import": [
    "LING71671/moon-egui/src/core",
    "LING71671/moon-egui/src/draw",
    "LING71671/moon-egui/src/math",
    "LING71671/moon-egui/src/color"
  ]
}

#在线演示 (Live Demos)

• 在线交互主页 (Interactive Demo) 包含即时模式基础控件展示、菜单栏、浮动窗口与轻量画板交互预览。
• 画板与多尺度矩阵测试 (Canvas & Multi-Scale Benchmark) 包含 128² 至 1024²（16,384 ~ 1,048,576 节点）多尺度像素晶格阵列、CAD 双轴标尺、视口平移/缩放漫游、以及像素晶格分界线渲染。

#快速代码示例

fn update_ui(ui : &mut UIContext, state : &mut AppState) {
  // 1. 全局系统菜单栏
  ui.menu_bar(fn() {
    ui.menu("文件", fn() {
      if ui.menu_item("新建项目") { state.new_project() }
      if ui.menu_item("保存配置") { state.save() }
    })
    ui.menu("视图", fn() {
      if ui.menu_item("切换主题") { state.toggle_theme() }
    })
  })

  // 2. 浮动可拖拽视窗
  ui.window("控制台 & 属性监视", 50.0, 50.0, 300.0, 420.0, fn() {
    ui.label("欢迎使用 moon-egui")

    if ui.button("触发测试") {
      state.counter  1
    }

    // Blender 风格数值拖拽调节
    ui.drag_float("重力参数", &mut state.gravity, speed=0.1, min=0.0, max=20.0)
    ui.checkbox("开启物理碰撞", &mut state.collision_enabled)

    // 折叠数据面板
    ui.collapsing_header("实时渲染监控", fn() {
      ui.sparkline("实时帧率曲线", state.fps_history)
      ui.progress_bar(state.progress)
    })
  })
}

#架构体系

[ 输入事件流 (Input Events) ]
  • 鼠标指针绝对坐标与按键状态
  • 键盘按键与修饰键
  • 鼠标滚轮滑动增量 (Delta)
         │
         ▼
[ moon-egui 纯算内核 ]
  • 输入状态机 (Hover, Active, Focused)
  • 线性游标排版与 AABB 空间命中判定
  • 矩形 Scissor 裁剪栈
  • 即时模式控件逻辑求值
         │
         ▼
[ 绘制指令序列 (DrawCmd Stream) ]
  • DrawCmd::Rect(x, y, w, h, color, radius)
  • DrawCmd::Text(x, y, text, size, color)
  • DrawCmd::Line(x1, y1, x2, y2, color, width)
  • DrawCmd::Clip(x, y, w, h)
         │
         ▼
[ 可插拔渲染后端 (Render Backends) ]
  • HTML5 Canvas 2D (默认 Wasm 桥接)
  • WebGL / WebGPU (规划演进)
  • 原生窗口引擎 (Raylib / SDL / Minifb)

#核心特性矩阵

#已交付可用特性 (Available Now)

• 底层图形与绘制内核 (Core Draw Engine)：纯 MoonBit 实现的 Vec2, Rect, Color, DrawCmd 平台无关指令流，支持矩形、线段、圆、文本与嵌套矩形裁剪栈（Scissor Clipping）。
• 交互状态机与多向排版 (Layout & Space Allocation)：UIContext 维护 hot_id / active_id 状态机与布局作用域栈，支持单向垂直流、水平行内排版流（horizontal），allocate_space() 自动分配几何尺寸并完成鼠标交互命中判定。
• 核心交互控件套件 (Available Widgets)：
  • 基础输入：button（支持快捷键、主次样式与尺寸）、text_edit（纯白骨瓷单行文本输入）、label / label_colored。
  • 选择与调节：checkbox（精密复选框）、toggle（双稳态胶囊开关）、radio（同心圆单选）、slider / slider_int（连续/步进数值条）、drag_value（数字微调器）、combo_box（轻量下拉选择框）、color_button（调色板取色器）。
  • 反馈与展示：progress_bar（平滑进度条）、tooltip（悬浮气泡提示与视口防溢出）。
  • 排版微调：separator（水平发丝分割线）、spacer（弹性留白）。
• 视窗与高级容器系统 (Windows & Containers)：
  • 全局顶层菜单栏：menu_bar, menu, menu_item, menu_separator，具备前台图层投影隔离、桌面级 Hover-to-Switch 随动流转与外部点击安全闭合；
  • 自由浮动视窗：window 支持标题栏拖拽位移、动态 Z-Index 置顶管理、内容局部坐标系与 Scissor 视口裁剪；
  • 高级容器：collapsing_header（树形折叠分组）、scroll_area（滚轮驱动平滑视口滚动）、tab_bar（悬浮滑块标签导航）。
• 无头纯算与高覆盖测试：核心图元与组件逻辑完全脱离浏览器，内置 58 项自动化无头白盒单元测试（100% 通过）。
• Canvas 2D 宿主驱动器：轻量 JavaScript 桥接层与 60 FPS 渲染管线，结合 O(1) 视口边界裁剪与多尺度 LOD 架构。

#规划与演进中特性 (Planned / In Roadmap)

• 硬件加速渲染后端：WebGL / WebGPU 批量几何图元渲染器与自定义着色器流水线。
• 跨平台原生桌面桥接：Raylib / SDL3 跨平台窗口环境驱动器适配。
• 高级数据流图元：实时遥测波动折线图（Sparkline）、多视窗停靠排版系统（Docking System）。

#开发路线图（2026 年 9 月 9 日 — 9 月 25 日）

#第一阶段：核心架构与基础套件（9月9日 – 9月11日）[已全面交付]

• 里程碑 1：工程骨架与基础数学图元：Vec2, Rect, Color, InputState, DrawCmd, DrawList。
• 里程碑 2：输入状态机与基础排版：AABB 命中判定、横纵排版流、Button, Label, Checkbox, Slider, SliderInt。
• 里程碑 3：高级视窗与容器系统：Window 拖拽与动态 Z-Index 置顶、全局顶层菜单栏（MenuBar）、视口滚动（ScrollArea）、折叠分组（CollapsingHeader）。
• 里程碑 4：Canvas 2D 驱动与百万节点画板：60 FPS HTML5 Canvas 2D 宿主、自适应 LOD、GitHub Pages 自动化静态上线。

#第二阶段：专业工程能力深度演进（9月12日 – 9月25日）[推进中]

• 里程碑 5：专业桌面交互与输入系统（9月12日 – 9月15日）：全局命令面板 (CommandPalette / ⌘K)、右键上下文菜单 (ContextMenu)、多行文本输入 (text_edit_multiline)、资产树控件 (TreeView)。
• 里程碑 6：工作台排版体系与视窗停靠（9月16日 – 9月18日）：可嵌套弹性分栏器 (SplitPane)、视窗磁吸与停靠机制原型 (Docking)、动量物理弹簧微动效 (Spring Physics)。
• 里程碑 7：数据密集型组件与可视化探索（9月19日 – 9月21日）：虚拟化数据表格 (VirtualTable)、节点流连线编辑器 (NodeEditor)、工程遥测图表套件 (Plot)、矢量 SVG 导出器 (SvgExporter)。
• 里程碑 8：高性能渲染管线探索与应用范例（9月22日 – 9月24日）：WebGL 2.0 顶点合批渲染后端探索、CAD/节点/音频/IDE 四大参考演示集成。
• 里程碑 9：工程化验证、基准评测与正式发布（9月25日）：150+ 自动化无头单元测试、微秒级性能耗时报告、发布 v0.2.0 正式版本。

完整攻坚指标与详细验收准则请参阅 ROADMAP.md (English)。

#架构与技术文档

#开源许可证