AdaptiveGrid 自适应网格

RenderAdaptiveGridPanel 根据可用宽度和最小列宽自动计算列数。它适合卡片列表、指标面板和需要兼容不同窗口宽度的页面。

LIVE CANVAS可运行组件示例

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

API 总览

主类：

RenderAdaptiveGridPanel

何时使用

看板卡片、快捷入口、指标块需要随窗口宽度改变列数。
子项宽度应该一致，但高度可以不同。
某些子项需要横跨多列，例如宽卡片或重点指标。

何时不要使用

需要严格行列轨道、固定列定义、跨行跨列。使用 GridPanel。
数据量很大并需要虚拟滚动。使用 GridView、ItemsControl 或专门数据组件。
表单字段需要稳定阅读顺序。优先使用 EntryGrid 或 GridPanel。

最小示例

import { RenderAdaptiveGridPanel, RenderText } from 'ds-ui' const cards = new RenderAdaptiveGridPanel({  minColumnWidth: 220,  maxColumns: 4,  columnGap: 12,  rowGap: 12,}) cards.addChild(new RenderText('概览卡片'))cards.addChild(new RenderText('宽卡片'), { columnSpan: 2 })

当容器变宽时，列数会增加；当容器变窄时，列数会减少，但不会小于 minColumns。

构造参数

参数	类型	默认值	说明
`minColumnWidth`	`number`	必填	每列允许的最小宽度。内部会限制不小于 `1`。
`minColumns`	`number`	`1`	最少列数。内部会限制不小于 `1`。
`maxColumns`	`number`	子节点数量	最多列数。未设置时按子节点数量和可用宽度决定。
`columnGap`	`number`	主题 `itemSpacing`	列间距。
`rowGap`	`number`	主题 `itemSpacing`	行间距。

子节点数据

通过 addChild(child, data) 或 setChildData(child, data) 设置子项数据。

字段	类型	默认值	说明
`columnSpan`	`number`	`1`	子节点占用列数。布局时会限制在 `1..当前列数`。

import { RenderAdaptiveGridPanel, RenderText } from 'ds-ui' const cards = new RenderAdaptiveGridPanel({ minColumnWidth: 180 })cards.addChild(new RenderText('普通卡片'))cards.addChild(new RenderText('横跨两列'), { columnSpan: 2 })

属性和方法

API	返回值	说明
`children`	`RenderBox[]`	当前子节点列表。业务代码不应直接改数组。
`childData`	`Map<RenderBox, AdaptiveGridPanelChildData>`	子节点布局数据。业务代码应通过方法修改。
`minColumnWidth`	`number`	读写最小列宽，修改后触发布局。
`minColumns`	`number`	读写最少列数，修改后触发布局。
`maxColumns`	`number \| undefined`	读写最多列数，修改后触发布局。
`columnGap`	`number`	读写列间距，修改后触发布局。
`rowGap`	`number`	读写行间距，修改后触发布局。
`addChild(child, data?)`	`void`	添加子节点和可选布局数据。
`setChildData(child, data)`	`void`	修改已有子节点的布局数据。未知子节点会被忽略。
`clearChildren()`	`void`	清空子节点、childData 和父子关系。

布局规则

根据父约束宽度、minColumnWidth、minColumns、maxColumns 计算当前列数。
父约束宽度有限时，组件宽度取父级最大宽度。
父约束宽度无界时，组件宽度取 列数 * minColumnWidth + 间距。
每个子项按顺序放入网格；当前行剩余列数不足时换到下一行。
columnSpan 大于当前列数时会被压到当前列数。
每行高度取该行所有子项布局后的最大高度。

AdaptiveGrid 只做列数自适应，不做 masonry 的“最短列”排列。如果卡片高度差异很大且希望填补空洞，使用 Masonry。

动态更新

修改 minColumnWidth、minColumns、maxColumns、columnGap、rowGap 或子节点数据后会触发布局。业务代码应避免在每次 paint 或 hover 中修改这些属性。

响应式页面通常在外层 resize 后由布局约束自然驱动列数变化，不需要手动监听窗口宽度并频繁设置列数。

常见错误

minColumnWidth 设置过小

列数会变多，但卡片内容可能挤压、文字重叠或频繁换行。minColumnWidth 应按内容最小可读宽度设置，而不是按视觉设计稿猜测。

用 AdaptiveGrid 做复杂表单

自适应换列会改变字段阅读顺序。复杂表单应使用固定轨道布局。

期望自动虚拟化

AdaptiveGrid 会布局所有子节点，不会按可视区跳过。大量数据需要数据组件或外部虚拟化。

使用建议

指标卡片、业务入口、模块面板优先使用 AdaptiveGridPanel。
minColumnWidth 要按真实内容选择，不要只按视觉宽度猜测。
复杂表单不建议使用 AdaptiveGridPanel，因为字段换列后会影响阅读顺序；表单优先使用 GridPanel。
超大列表仍然应使用数据组件或虚拟列表。