Descriptions

展示对象的标签—值属性。中文惯用名：描述列表。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.descriptions`
名称	Descriptions
二级分类	数据展示（`data-display`）
用途	展示对象的标签—值属性
描述	中文惯用名：描述列表。

预览

静态结构：Descriptions 根节点 data-slot="descriptions"，可选 title（text-base font-medium，mb-3）下接 CSS Grid（gridTemplateColumns 按 column 均分，缺省 3 列）。无边框形态每项为 label（弱化色）+ value 的行内 flex 对；bordered 形态为边框栅格（gap-px 露底边线 + 圆角外框），每项 label 固定 128px 宽灰底单元格、value 为弹性单元格。value 支持 string | number。

DSL 结构

DslNode

{
  "type": "Descriptions",
  "props": {
    "title": "客户信息",
    "column": 2,
    "items": [
      {
        "label": "客户名称",
        "value": "杭州云杉科技有限公司"
      },
      {
        "label": "联系人",
        "value": "陈晨"
      },
      {
        "label": "联系电话",
        "value": "0571-8800-1234"
      },
      {
        "label": "状态",
        "value": "合作中"
      }
    ]
  }
}

何时用

何时使用

详情页展示单个对象的标签—值属性：订单信息、用户资料、配置摘要。
只读呈现成组字段，列数固定、无需行内操作。
详情区顶部需要小标题统领一组属性。

何时不用

多对象按行列对比或批量操作：使用 Table；Descriptions 只服务单对象。
需要编辑录入：使用 Form 系组件，Descriptions 为纯展示。
展示集合条目：使用 List；展示层级或时间序列：使用 Tree / Timeline。

变体

变体	视觉形态	适用场景
默认（无边框）	label + value 行内排列，列间留白栅格	轻量摘要、卡片内属性组
bordered 带边框	单元格边框栅格，label 灰底固定列宽	正式详情页，属性多且需明确边界
column 列数	grid 按 column 均分（缺省 3）	按容器宽度与字段密度调整列数
带标题	属性组上方小标题	详情页多组属性分区（如「基础信息」「支付信息」）

API 属性

属性	类型	默认值	说明
`title`	`string`	—	标题；缺省不渲染标题区
`items`	`DescriptionsItemData[]`	[]	描述项列表（可含表达式解析后的数组）；项结构 { label, value: string
`column`	`number`	3	每行列数（grid 均分）
`bordered`	`boolean`	false	带边框样式：label 固定宽灰底单元格 + 边框栅格
`className`	`string`	—	通用：根节点 class（与内置样式合并）
`style`	`CSSProperties`	—	通用：根节点内联样式

使用规范

仅承载单对象的只读属性；value 为 string | number，复杂内容（链接、图片、操作）不放进来。
column 按容器宽度与字段数量设定：宽容器 3-4 列，窄容器 1-2 列；同一详情页多组 Descriptions 保持列数一致。
label 用名词短语、不带冒号；同组 label 长度尽量接近，bordered 下 label 列宽固定 128px，超长提前精简。
属性较多时用 title 分组（基础信息 / 联系信息 / 其他），而非一组塞数十项。
值为空时显式给占位（如「—」），不省略条目造成栅格错位。

正例

✓ 订单详情：title「订单信息」，bordered + column={3} 展示订单号、金额、状态等 6-9 项。
✓ 用户资料卡：无边框 column={2}，label「邮箱」「手机」配只读值。
✓ 多组详情：两个 Descriptions 分别以「基础信息」「配置信息」为 title 顺序排布。

反例

✕ 用 Descriptions 平铺多个同类对象（应使用 Table；它只表达单对象）。
✕ 把可编辑字段塞进 Descriptions（录入场景应使用 Form）。
✕ column 设得过大导致 label/value 挤压换行，或同页各组列数不一致。

Design Token 映射

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