# 布局控件（不写坐标搭骨架）

> 预置内部布局的容器：行/列/网格/流式行/固定面板/停靠/侧栏/手风琴/占位。
> 返回目录：[index.md](index.md)；全量选项字典（最权威）：[widget-schema.generated.json](../widget-schema.generated.json)。

## 12. 布局控件（不写坐标搭骨架；对照 canvas 内部布局）

> 都是**容器**（子组件放 `widgets: []`），与 `group-panel` 一样继承背景/边框/滚动条/面板缩放（`use-panel-scale`/`panel-scale`/`panel-content-fit`）等通用项。行/网格默认 `container-layout:"grid"`（行=扁平 12×1 轨道，网格=`grid-tree` 分割树），列/流式行默认 `fluid`，固定面板默认 `static`——这就是它们与分组面板的本质差异：**默认布局不同的预置容器**。
>
> ⚠️ **写工程 JSON 时必须把 `container-layout` 显式写进 `options`**。上面这些「预置」来自组件 `meta.defaultOptions`——`viewer.addWidget` 与编辑器插入**会补**预置（`addWidget({type:"layout-row"})` 读到 `container-layout="grid"`）；但**手写工程 JSON 直接载入不补**，`container-layout` 按通用默认回落 `static`，子项各自按 `position` 定位——不写坐标的子项就全叠在左上角，看着像「只出来一个组件」。同理，选了 `fluid` 要一并写 `flex-direction`/`fluid-wrap`，选了 `grid` 要写 `grid-columns`/`grid-rows` 或 `grid-tree`。
>
> 共享排布项：`fluid-justify-content`/`fluid-align-items`/`fluid-gap-value`、`children-no-events`/`child-state-follow`/`child-select-exclusive`、`canvas-grow`（页面开 `fill-auto-expand` 时：`reflow` 吃满剩余空间让子项重排 / `scale` 保持设计比例——`scale` 只管尺寸不管位置，别摆在画布增长那一侧，见 [envelope.md](../envelope.md) §4.1）。

| type | 名称 | 默认尺寸 | 结构/特有项 |
|---|---|---|---|
| `layout-row` | 行布局 | `[600,120]` | 预置 `grid` 布局 `grid-columns:12, grid-rows:1`——子组件按栅格单元格放置（子项写 `grid-col-span`/`grid-row-span` 跨格、`grid-col-start` 定位），拖分隔条调比例 |
| `layout-column` | 列布局 | `[240,400]` | 预置 `fluid`+`flex-direction:column`+`fluid-wrap:nowrap`（纵向流式栈，**非栅格**；子项用 `fluid-width-type`/`fluid-height-type` 等） |
| `layout-grid` | 网格布局 | `[600,400]` | 预置 `grid` + `grid-tree` 分割树（创建即种九宫格骨架 + 9 个 `placeholder` 叶子，拖分隔条只调相邻两兄弟比例；不写 `grid-columns`/`grid-rows` 扁平轨道数） |
| `layout-flow-row` | 流式行 | `[600,120]` | 预置 `fluid`+`row`+`wrap`（卡片墙，放不下自动换行；子项用 `fluid-width-type` 等） |
| `layout-fixed-panel` | 固定面板 | `[400,300]` | 预置 `static`（定位容器，内容钉死坐标） |
| `layout-dock` | 停靠布局 | `[960,640]` | 上/下/左/右停靠区+中间主区：`widgets` 前 5 个子容器依序=左/右/底/顶/中；`left-enabled`/`right-enabled`/`bottom-enabled`/`top-enabled`+`*-size`(px 或 %)+`*-default-state`(`expanded`/`collapsed`)、`overlay`(悬浮覆盖)、`resizable`；折叠按钮 `toggle-*`、分隔线 `divider-*` |
| `layout-sidebar` | 侧边栏 | `[640,400]` | 主区+可折叠侧栏：`dock-side`(左/右/上/下)、`side-size`、`default-state`、`overlay`/`resizable`、`toggle-*`/`divider-*`；`widgets` 前 2 个子容器=侧栏/主区 |
| `layout-accordion` | 手风琴 | `[320,480]` | 多可折叠分区：`sections`(分区列表,=子面板 name)、`single-expand`(单开)、`default-expanded`(如 `"0"` 或 `"0,2"`)、`show-toggle-all`、`header-size`/`panel-min-height`；标题样式 `header-*`、面板 `panel-*` |
| `placeholder` | 占位 | `[120,80]` | 空白占位块（布局对齐/预留），无特有选项 |

无组件特有绑定字段。选型：整屏三段式骨架→`layout-dock`；可收纳侧栏→`layout-sidebar`；等分格子→`layout-row`/`layout-column`/`layout-grid`；卡片墙→`layout-flow-row`（数据驱动的卡片墙用 `data-repeater`）；折叠列表→`layout-accordion`。