Grid

按响应式行列排列内容。中文惯用名：栅格。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.grid`
名称	Grid
二级分类	布局（`layout`）
用途	按响应式行列排列内容
描述	中文惯用名：栅格。

预览

静态结构：渲染为 <div data-slot="grid" data-columns>（class 含 grid）；列数为运行时动态值，经 inline style gridTemplateColumns: repeat(columns, minmax(0, 1fr)) 设置（columns 取下限 1）；每个子节点被包一层 <div data-slot="grid-item">（栅格子项统一承载，便于对齐 / 定位）；gap 未指定时应用默认间距令牌 gap-(--grid-gap)，数字 gap 内联、gap: 0 显式关闭；style 为布局逃逸口（与 columns / gap 生成的样式合并，同键后者优先）。

DSL 结构

DslNode

{
  "type": "Grid",
  "props": {
    "columns": 3,
    "gap": 12
  },
  "children": [
    {
      "type": "Card",
      "props": {
        "title": "活跃用户"
      },
      "children": [
        {
          "type": "Text",
          "props": {
            "text": "1,284"
          }
        }
      ]
    },
    {
      "type": "Card",
      "props": {
        "title": "订单数"
      },
      "children": [
        {
          "type": "Text",
          "props": {
            "text": "356"
          }
        }
      ]
    },
    {
      "type": "Card",
      "props": {
        "title": "转化率"
      },
      "children": [
        {
          "type": "Text",
          "props": {
            "text": "12.4%"
          }
        }
      ]
    }
  ]
}

何时用

何时使用

整页 / 区块级栅格：指标卡片墙、图库、表单双列、仪表盘分块。
需要严格等宽分列：每列宽度一致（repeat(columns, minmax(0, 1fr))），不因内容宽度抖动。
需要统一栏间距：一档 gap 管住整片区域的间距（或沿用 --grid-gap 令牌）。

何时不用

一维排列与对齐（行内两端对齐、居中、纵向堆叠）：使用 Flex。
只是一组相邻元素要一致间距：使用 Space。
需要跨列（colspan）/ 每列不等宽 / 断点切换列数：当前适配器只有等分列与固定列数，超出能力时用 Flex 组合或经 style 逃逸口表达。

变体

变体	视觉形态	适用场景
单列（缺省）	columns 缺省 1，纵向等宽堆叠	移动优先的表单 / 卡片流
等分多列	2 ~ 4 等宽列	指标卡墙、图库、仪表盘分块
自定义间距	数字 gap 内联（如 12）或 gap: 0 关闭	紧凑卡片群、需要无缝拼接的分块

API 属性

属性	类型	默认值	说明
`columns`	`number`	1	列数，每列等宽（取整下限 1）
`gap`	`number`	—（应用 --grid-gap 令牌）	栏间距（px）；gap: 0 显式关闭间距
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式（布局逃逸口，与 columns / gap 生成的样式合并，同键后者优先）
`children`	`DslNode[]`	—	栅格内容（DSL 子树；每个子节点包一层 grid-item）

使用规范

列数按内容最小可用宽度定：卡片类 2 ~ 4 列，表格 / 长文本避免多列。
同一区块只用一个 Grid，不在 Grid 内再嵌 Grid 拼「不规则」布局（用 Flex 组合更清晰）。
栏间距用同一档（或令牌），不逐格手写 margin。
需要响应式列数时，用 style / className 逃逸口声明媒体查询或容器查询，columns 保持基础列数。

正例

✓ 仪表盘：Grid columns=4 平铺指标 Card，gap 走默认令牌。
✓ 表单字典区：Grid columns=2 左右等宽字段列。

反例

✕ 用 Grid columns=2 做「左固定 200px + 右自适应」分栏（应使用 Flex + style flex 权重）。
✕ 在 Grid 内逐个子项写 margin 制造间距（应统一用 gap）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。