Descriptions 描述列表
成对的标签与值，按列排开。
用法
标签与取值的配对依靠 dl / dt / dd 表达，组件只提供身份与排版；不传 columns 即每行一组
- 订单号
- XH-20260810-0042
- 下单时间
- 2026-08-10 09:31
- 支付方式
- 余额支付
组件结构
加粗的是必需部件。
data-scope="descriptions"：root · header · title · extra · 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 送达，到前电联。
标签对齐
标签在左时同一列的标签收到这一列最长的那个，竖线上下对齐；跨列的格与没摆满的最后一行照常画线
- 申请人
- 张三
- 状态
- 待审批
- 申请对象
- 财务部 · 报销审批
- 申请原因
- 季度结算期间临时代审，结算完成后收回
- 期望有效期
- 2026-10-14 至 2026-11-14
- 申请时间
- 2026-10-14 09:30
标题与附加内容
列表之前的头部放标题与作用于整份描述的操作；它排在 dl 之外，标题标签按页面层级由作者选
订单信息
- 订单号
- XH-20260810-0042
- 下单时间
- 2026-08-10 09:31
- 支付方式
- 余额支付
- 收货人
- 林一
设计指引
何时使用
- 详情页的属性列表：订单信息、设备参数、用户资料。
何时不用
- 数据是多行同构的记录时，使用表格。
- 只有一两对时，直接书写。
特性
- 语义是
dt/dd，组件只提供身份与排版。 columns决定每行几组，不传时每行一组。- 标签位置可以在值的上方或左侧；
variant="outline"提供外框与网格线。 - 标签在左时，同一列的标签宽度取这一列最长的那个，标签与值之间的竖线上下对齐；各列各取各的。依赖 CSS 子网格（Chrome 117 起），更早的引擎里每格按自己的标签定宽。
- 每一格可以通过
span横跨多列，上限是当前列数；窄档一行只放一组时忽略该值。 - 网格线与跨列、行里摆了几格无关；最后一行没摆满时，最后一格与空着的列连成一格。
组合
列表之前可放头部：标题与作用于整份描述的操作（编辑、复制）或一枚状态标签。头部排在
dl之外（dl里只能放成对的dt/dd）：Vue 写进header插槽，React 经header传入，Web Components 写成root的前一个兄弟。标题缺省是div，按页面层级用as换成h2/h3。
最佳实践
- 值为空时写“—”，不留空白，避免用户无法区分没有值与未加载。
- 标签左置时同一列自动对齐；要让各列的标签也一样宽，用
--xh-descriptions-label-w定一个宽度。 - 长文本字段用
span占满整行，不为它另开一份描述列表。
反模式
- 用它排版表格。
- 标签比值更长。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-descriptions> |
| Vue 组件 | XhDescriptionsExtra XhDescriptionsHeader XhDescriptionsItem XhDescriptionsLabel XhDescriptionsRoot XhDescriptionsTitle 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。 |
插槽
仅列出带载荷的插槽。
| Vue 组件 | 插槽 | 载荷 | 说明 |
|---|---|---|---|
XhDescriptionsRoot | default | — | |
XhDescriptionsRoot | header | — | 列表之前的头部：放 XhDescriptionsHeader（内含 Title 与 Extra）。 它渲染为根的兄弟排在列表前：根常写成 dl，dl 的子节点只能是成对的 dt / dd。 |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhDescriptionsItem | as | ElementType | 每一格渲染为哪个标签，默认 div。 | |
XhDescriptionsItem | span | number | 该格横跨几列，未写即占一列；上限是根上的 columns。 | |
XhDescriptionsLabel | as | ElementType | 标签渲染为哪个标签，默认 dt。 | |
XhDescriptionsRoot | as | ElementType | 根渲染为哪个标签，默认 dl。 | |
XhDescriptionsRoot | header | ReactNode | 列表之前的头部：放 XhDescriptionsHeader（内含 Title 与 Extra）。 它渲染为根的兄弟排在列表前：根常写成 dl，dl 的子节点只能是成对的 dt / dd。 | |
XhDescriptionsTitle | as | ElementType | 标题渲染为哪个标签，默认 div：组件不往文档大纲里插标题，作者按页面层级改写成 h2 / h3。 | |
XhDescriptionsValue | as | ElementType | 取值渲染为哪个标签，默认 dd。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
getRootProps | () => T['element'] | |
getHeaderProps | () => T['element'] | 列表之前的头部：左侧标题、右侧附加内容（操作、状态）。 它排在根之外：根常写成 dl，dl 的子节点只能是成对的 dt / dd。 |
getTitleProps | () => T['element'] | 标题。作者按页面层级选标题标签（h2 / h3…），组件不替作者定层级。 |
getExtraProps | () => 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"] 部件选择器书写，发布产物以挂载类 .xh-scope-descriptions 代替其中的 data-scope（特异性相同），位于 xihan.components 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
header | data-size | props.size |
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 | itemlabelroot | border-block-endborder-inline-end | @media (min-width: 768px)placement=leftvariant=outline | --xh-border-default | descriptions 的 item、label、root 部件 border-block-end、border-inline-end 覆盖槽。 |
--xh-descriptions-extra-gap | extra | gap | default | --xh-space-2 | descriptions 的 extra 部件 gap 覆盖槽。 |
--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-row-gap | descriptions 的 root 部件 gap 覆盖槽。 |
--xh-descriptions-header-gap | header | gap | default | --xh-space-3 | descriptions 的 header 部件 gap 覆盖槽。 |
--xh-descriptions-header-mb | header | margin-block-end | default | --xh-_descriptions-header-mb | descriptions 的 header 部件 margin-block-end 覆盖槽。 |
--xh-descriptions-item-px | itemlabelrootvalue | padding-inline | @media (min-width: 768px)is([data-scope='descriptions'][data-part='label'], [data-scope='descriptions'][data-part='value'])placement=leftvariant=outline | --xh-_descriptions-px | descriptions 的 item、label、root、value 部件 padding-inline 覆盖槽。 |
--xh-descriptions-item-py | itemlabelrootvalue | padding-block | @media (min-width: 768px)is([data-scope='descriptions'][data-part='label'], [data-scope='descriptions'][data-part='value'])placement=leftvariant=outline | --xh-_descriptions-py | descriptions 的 item、label、root、value 部件 padding-block 覆盖槽。 |
--xh-descriptions-label-bg | itemlabelroot | background | @media (min-width: 768px)placement=leftvariant=outline | --xh-bg-muted | descriptions 的 item、label、root 部件 background 覆盖槽。 |
--xh-descriptions-label-fg | label | color | default | --xh-fg-muted | descriptions 的 label 部件 color 覆盖槽。 |
--xh-descriptions-label-font-weight | label | font-weight | default | --xh-font-weight-medium | 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)@supports (grid-template-columns: subgrid)columns=2columns=3columns=4columns=5columns=6placement=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-title-fg | title | color | default | --xh-fg-default | descriptions 的 title 部件 color 覆盖槽。 |
--xh-descriptions-title-font-size | title | font-size | default | --xh-text-heading-3-size | descriptions 的 title 部件 font-size 覆盖槽。 |
--xh-descriptions-title-font-weight | title | font-weight | default | --xh-text-heading-3-weight | descriptions 的 title 部件 font-weight 覆盖槽。 |
--xh-descriptions-value-fg | value | color | default | --xh-fg-default | descriptions 的 value 部件 color 覆盖槽。 |
动效
本组件皮肤不含过渡与关键帧，也没有脚本驱动的动效：状态一变，外观立即到位。
响应式
皮肤按视口分档：min-width: 1024px · min-width: 768px。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。