GridPanel 网格布局

LIVE CANVAS可运行组件示例

ON-DEMAND RUNTIME交互式示例将在进入视区时启动避免文档首屏同时初始化多个 Canvas Runtime

RenderGridPanel 用行列轨道布局子节点，适合表单、属性面板、统计卡片和需要严格对齐的区域。

API 总览

主类：

RenderGridPanel

轨道 helper：

gridPx(value)
gridFr(value?, options?)
gridStar(value?, options?)
gridAuto(options?)

构造参数

new RenderGridPanel(options?) 的 options：

参数	类型	默认值	说明
`columns`	`GridPanelTrack[]`	`[]`	列轨道定义。未传时布局阶段使用一个 `gridFr()`。
`columnDefinitions`	`GridPanelTrack[]`	`undefined`	`columns` 的别名；`columns` 优先。
`rows`	`GridPanelTrack[]`	`[]`	行轨道定义。不足时按内容自动补 `gridAuto()`。
`rowDefinitions`	`GridPanelTrack[]`	`undefined`	`rows` 的别名；`rows` 优先。
`columnGap`	`number`	主题 `itemSpacing`	列间距。
`rowGap`	`number`	主题 `itemSpacing`	行间距。

子项数据

通过 addChild(child, data) 设置子项所在单元格。

字段	类型	默认值	说明
`row`	`number`	自动放置	起始行。
`column`	`number`	自动放置	起始列。
`rowSpan`	`number`	`1`	跨越行数。
`columnSpan`	`number`	`1`	跨越列数。

轨道类型

RenderGridPanel 支持三类轨道：

gridPx(value)：固定像素宽度或高度。
gridFr(value) / gridStar(value)：按比例分配剩余空间。
gridAuto()：根据内容自然尺寸决定大小。

基本用法

import { RenderGridPanel, RenderText, RenderTextBox, gridAuto, gridFr, gridPx } from 'ds-ui' const form = new RenderGridPanel({  columns: [gridPx(96), gridFr(1), gridPx(96), gridFr(1)],  rows: [gridAuto(), gridAuto()],  columnGap: 8,  rowGap: 8,}) const nameLabel = new RenderText('姓名')nameLabel.verticalAlignment = 'center'const departmentLabel = new RenderText('科室')departmentLabel.verticalAlignment = 'center' form.addChild(nameLabel, { row: 0, column: 0 })form.addChild(new RenderTextBox({ placeholder: '输入姓名' }), { row: 0, column: 1 })form.addChild(departmentLabel, { row: 0, column: 2 })form.addChild(new RenderTextBox({ placeholder: '输入科室' }), { row: 0, column: 3 })

跨行跨列

子节点可以通过 rowSpan 和 columnSpan 占用多个单元格。

import { RenderGridPanel, RenderText, RenderTextBox, gridAuto, gridFr } from 'ds-ui' const grid = new RenderGridPanel({  columns: [gridFr(1), gridFr(1), gridFr(1)],  rows: [gridAuto(), gridAuto()],  columnGap: 8,  rowGap: 8,}) grid.addChild(new RenderText('基础信息'), { row: 0, column: 0, columnSpan: 3 })grid.addChild(new RenderTextBox({ placeholder: '备注' }), { row: 1, column: 0, columnSpan: 3 })

对齐方式

每个子节点直接使用统一属性：

horizontalAlignment: start、center、end、stretch
verticalAlignment: start、center、end、stretch

默认是 stretch，适合输入框和表格等需要填满单元格的组件。

alignment 属于子组件本身，GridPanel 不提供另一套面板级 item alignment。显式 width 会阻止默认 stretch 拉伸；如果没有再设置 alignment，组件会停在单元格起点。只有 maxWidth 时，默认 stretch 仍会提供单元格的 tight 约束，宽度上限不会产生缩窄效果。要让 maxWidth 生效并居中，需要同时设置 horizontalAlignment = 'center'。

全页居中表单

外层 Grid 使用单个 fr 行列提供完整页面槽位，表单本身使用 maxWidth 限制宽度并声明居中：

import { RenderBorder, RenderGridPanel, gridAuto, gridFr } from 'ds-ui' const form = new RenderGridPanel({  columns: [gridFr(1)],  rows: [gridAuto()],}) const host = new RenderGridPanel({  columns: [gridFr(1)],  rows: [gridFr(1)],  padding: 24,}) const card = new RenderBorder({ child: form })card.maxWidth = 520card.horizontalAlignment = 'center'card.verticalAlignment = 'center'host.addChild(card)

如果不设置 width 或 maxWidth，带 fr 列的表单 Grid 会占满外层单元格，因而看不出水平居中效果。

属性和方法

API	类型 / 返回值	说明
`children`	`RenderBox[]`	当前子节点列表。业务代码不应直接修改数组。
`childData`	`Map<RenderBox, GridPanelChildData>`	子节点布局数据。业务代码应通过 `addChild()` 管理。
`columns`	`GridPanelTrack[]`	当前列定义。直接替换后应调用 `setColumnDefinitions()` 或确保触发布局。
`rows`	`GridPanelTrack[]`	当前行定义。直接替换后应调用 `setRowDefinitions()` 或确保触发布局。
`columnGap`	`number`	列间距。赋值会触发布局。
`rowGap`	`number`	行间距。赋值会触发布局。
`setColumnDefinitions(columns)`	`void`	替换列轨道并触发布局。
`setRowDefinitions(rows)`	`void`	替换行轨道并触发布局。
`addChild(child, data?)`	`void`	添加子节点和布局数据。
`clearChildren()`	`void`	清空所有子节点、childData 和父子关系，并触发布局。

布局规则

父约束宽度有限时，fr 轨道分配剩余宽度。
父约束高度有限时，fr 行分配剩余高度。
auto 轨道按子节点自然尺寸测量，并受 min/max 限制。
px 轨道使用固定像素。
未显式提供列时，默认使用一个 gridFr()。
未显式提供足够行时，会按子项占用范围自动补 gridAuto()。
stretch 对齐会用单元格 tight 约束布局子节点；其他对齐会保留子节点自然尺寸并在单元格内定位。

使用建议

表单标签列使用 gridPx，输入列使用 gridFr。
不确定内容高度时，行使用 gridAuto。
页面主区域不要用非常细碎的网格堆叠；复杂页面先用 DockPanel 或 StackPanel 分区，再在局部用 GridPanel 对齐。
大列表、大表格不应直接放入 GridPanel 后让外层滚动，应让数据组件或 ScrollViewer 管理滚动。