新增UI编辑器Godot容器布局

将节点布局统一收敛到 ControlLayout 并校验 Container 参数支持 HBox、VBox、Grid、Margin、Center 的 Inspector 与 Preview 补齐布局类型、状态和预览测试及技术文档
2026-08-19 10:56:27 +08:00
parent 9eb47f637b
commit 03e513324f
23 changed files with 1015 additions and 121 deletions
@@ -0,0 +1,41 @@
+# UI 编辑器 Godot 容器布局模型
+
+更新时间：`2026-08-18`
+
+## 范围
+
+UI 编辑器节点统一采用 Godot 4.x `Control` 风格布局数据。Rust 负责持久化和参数校验；UI Editor 前端将该数据单向生成 Preview CSS。CSS 只是预览后端，不是领域模型，也不需要与 Godot 项目或运行时对接。
+
+本次是破坏性 UI 设计 schema 变更：旧 `Node.transform` 改为 `Node.layout.transform`，不提供迁移。
+
+## 数据模型
+
+每个 `Node` 保留：
+
+```text
+layout: {
+  transform,                    // anchors + offsets
+  custom_minimum_size: [x, y],
+  size_flags_horizontal: 0|1|2|3|4|8,
+  size_flags_vertical: 0|1|2|3|4|8,
+  size_flags_stretch_ratio,
+  container: None | HBox | VBox | Grid | Margin | Center
+}
+```
+
+flags 使用 Godot 数值：`ShrinkBegin=0`、`Fill=1`、`Expand=2`、`ExpandFill=3`、`ShrinkCenter=4`、`ShrinkEnd=8`。默认最小尺寸为 `[0, 0]`，flags 为 `Fill`，stretch ratio 为 `1`。
+
+Container 专属数据是互斥 tagged union：HBox/VBox 存 `alignment + separation`，Grid 存 `columns + h_separation + v_separation`，Margin 存四边 margin，Center 存 `use_top_left`。
+
+## 语义
+
+- 普通 Control：children 继续按自己的 Transform 绝对定位。
+- 父为 Container：父忽略 direct child 的 Transform，使用 child minimum size、flags 与 stretch ratio；Transform 不删除，离开 Container 后继续可用。
+- `children_display_mode` 仍是独立的 Stack/Exclusive 可见性规则；不可见 child 不参与 Container。
+- 不支持 Flex/Flow wrap；Grid 按行优先排列。
+- Margin 的 children 填满内侧矩形；Center 的 children 居中并可重叠。
+- v1 minimum size 只使用 `custom_minimum_size`。TODO：为文本、图片等组件提供 minimum-size，再与 custom minimum 逐轴取最大值。
+
+## 编辑器交互
+
+布局只在 Inspector 编辑。Preview 不为 Container 管理的 child 提供拖拽或缩放手柄；Inspector 会提示其 Transform 被父 Container 忽略。普通 Control 仍保留原 Transform 编辑和自由预览操作。