k88936
03e513324f
将节点布局统一收敛到 ControlLayout 并校验 Container 参数 支持 HBox、VBox、Grid、Margin、Center 的 Inspector 与 Preview 补齐布局类型、状态和预览测试及技术文档
2.0 KiB
2.0 KiB
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 保留：
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 编辑和自由预览操作。