AdaptiveGrid 自适应网格

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

API 总览

主类：

• RenderAdaptiveGridPanel

相关 public type：

• AdaptiveGridPanelChildData

导入：

import { RenderAdaptiveGridPanel, type AdaptiveGridPanelChildData } from 'ds-ui'

何时使用

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

何时不要使用

• 需要严格行列轨道、固定列定义、跨行跨列。使用 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。

构造参数

子节点数据

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

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

属性和方法

布局规则

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

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

动态更新

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

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

常见错误

minColumnWidth 设置过小

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

用 AdaptiveGrid 做复杂表单

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

期望自动虚拟化

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

使用建议

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

相关文档

• GridPanel 网格布局
• WrapPanel 自动换行布局
• Masonry 瀑布流布局
• Dashboard 示例