Descriptions 描述列表
成对的标签与值，按列排开。
用法
标签与取值的配对依靠 dl / dt / dd 表达，组件只提供身份与排版；不传 columns 即每行一组
- 订单号
- XH-20260810-0042
- 下单时间
- 2026-08-10 09:31
- 支付方式
- 余额支付
组件结构
加粗的是必需部件。
data-scope="descriptions"：root · item · label · value
示例
列数
columns 决定每行排几组，一到六列；排版使用 CSS Grid，不使用表格
- 姓名
- 张三
- 工号
- A-1024
- 部门
- 技术部
- 岗位
- 前端工程师
- 入职
- 2024-03-01
- 座机
- 8021
标签位置
placement 决定标签在上还是在左，不传即在上
标签在上（默认）
- 订单号
- XH-20260810-0042
- 下单时间
- 2026-08-10 09:31
标签在左
- 订单号
- XH-20260810-0042
- 下单时间
- 2026-08-10 09:31
外框
variant="outline" 绘制一圈描边，并在格与格之间补上网格线
- 商品
- 机械键盘
- 单价
- ￥499.00
- 数量
- 2
- 小计
- ￥998.00
尺寸
size 改变每格的内边距、组与组的间距与整体字号，不传 size 即默认档
- 小 · 状态
- 已发货
- 小 · 承运商
- 顺丰速运
- 默认 · 状态
- 已发货
- 默认 · 承运商
- 顺丰速运
- 大 · 状态
- 已发货
- 大 · 承运商
- 顺丰速运
跨列
一格写 span 横跨几列，上限是当前列数；长文本字段因此不必另开一份描述列表
- 订单号
- XH-20260810-0042
- 下单时间
- 2026-08-10 09:31
- 支付方式
- 余额支付
- 收货地址
- 浙江省杭州市余杭区文一西路 969 号
- 联系电话
- 138 0000 0000
- 备注
- 工作日 09:00–18:00 送达，到前电联。
设计指引
何时使用
- 详情页的属性列表：订单信息、设备参数、用户资料。
何时不用
- 数据是多行同构的记录时，使用表格。
- 只有一两对时，直接书写。
特性
- 语义是
dt/dd，组件只提供身份与排版。 columns决定每行几组，不传时每行一组。- 标签位置可以在值的上方或左侧；
variant="outline"提供外框与网格线。 - 每一格可以通过
span横跨多列，上限是当前列数；窄档一行只放一组时忽略该值。
组合
最佳实践
- 值为空时写“—”，不留空白，避免用户无法区分没有值与未加载。
- 标签左置时给它们统一宽度，值才能对齐。
- 长文本字段用
span占满整行，不为它另开一份描述列表。
反模式
- 用它排版表格。
- 标签比值更长。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-descriptions> |
| Vue 组件 | XhDescriptionsItem XhDescriptionsLabel XhDescriptionsRoot XhDescriptionsValue |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/descriptions.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
columns | DescriptionsColumns | 每行放置几组，一到六列；未提供时每行一组。 | |
placement | DescriptionsPlacement | 标签的位置：top / left；未提供时标签在上。 | |
size | Size | 尺寸：sm / md / lg。 | |
variant | ControlVariant | 形态：ghost 不画壳（默认），outline 绘制外框并在格与格之间补网格线，subtle 淡底。默认 ghost。 |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhDescriptionsItem | as | ElementType | 每一格渲染为哪个标签，默认 div。 | |
XhDescriptionsItem | span | number | 该格横跨几列，未写即占一列；上限是根上的 columns。 | |
XhDescriptionsLabel | as | ElementType | 标签渲染为哪个标签，默认 dt。 | |
XhDescriptionsRoot | as | ElementType | 根渲染为哪个标签，默认 dl。 | |
XhDescriptionsValue | as | ElementType | 取值渲染为哪个标签，默认 dd。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
getRootProps | () => T['element'] | |
getItemProps | (props?: DescriptionsItemProps) => T['element'] | |
getLabelProps | () => T['element'] | |
getValueProps | () => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
样式参考
皮肤
@xihan-ui/styles/descriptions.css 使用 [data-scope="descriptions"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-descriptions-bg | root | background | variant=outlinevariant=subtle | --xh-bg-subtle--xh-bg-surface | descriptions 的 root 部件 background 覆盖槽。 |
--xh-descriptions-border | root | border | variant=outline | --xh-border-default | descriptions 的 root 部件 border 覆盖槽。 |
--xh-descriptions-divider | itemroot | border-block-startborder-inline-start | variant=outline | --xh-border-subtle | descriptions 的 item、root 部件 border-block-start、border-inline-start 覆盖槽。 |
--xh-descriptions-fg | root | color | default | --xh-fg-default | descriptions 的 root 部件 color 覆盖槽。 |
--xh-descriptions-font-size | root | font-size | default | --xh-_descriptions-font-size | descriptions 的 root 部件 font-size 覆盖槽。 |
--xh-descriptions-gap | root | gap | default | --xh-_descriptions-gap | descriptions 的 root 部件 gap 覆盖槽。 |
--xh-descriptions-item-px | itemroot | padding-inline | variant=outline | --xh-_descriptions-px | descriptions 的 item、root 部件 padding-inline 覆盖槽。 |
--xh-descriptions-item-py | itemroot | padding-block | variant=outline | --xh-_descriptions-py | descriptions 的 item、root 部件 padding-block 覆盖槽。 |
--xh-descriptions-label-fg | label | color | default | --xh-fg-muted | descriptions 的 label 部件 color 覆盖槽。 |
--xh-descriptions-label-font-weight | label | font-weight | default | --xh-text-label-weight | descriptions 的 label 部件 font-weight 覆盖槽。 |
--xh-descriptions-label-gap | itemroot | column-gap | @media (min-width: 768px)placement=left | --xh-_descriptions-label-gap | descriptions 的 item、root 部件 column-gap 覆盖槽。 |
--xh-descriptions-label-w | itemroot | grid-template-columns | @media (min-width: 768px)placement=left | --xh-_descriptions-label-w | descriptions 的 item、root 部件 grid-template-columns 覆盖槽。 |
--xh-descriptions-pair-gap | item | gap | default | --xh-_descriptions-pair-gap | descriptions 的 item 部件 gap 覆盖槽。 |
--xh-descriptions-radius | root | border-radius | variant=outlinevariant=subtle | --xh-shape-surface | descriptions 的 root 部件 border-radius 覆盖槽。 |
--xh-descriptions-value-fg | value | color | default | --xh-fg-default | descriptions 的 value 部件 color 覆盖槽。 |
动效
本组件皮肤不含过渡与关键帧，也没有脚本驱动的动效：状态一变，外观立即到位。
响应式
皮肤按视口分档：min-width: 1024px · min-width: 768px。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。