描述列表 descriptions

数据展示组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

根默认渲染成 dl，标签渲染成 dt、取值渲染成 dd；不传 columns 即每行一组

订单号

XH-20260810-0042

下单时间

2026-08-10 09:31

支付方式

余额支付

<script setup lang="ts">
import {
  XhDescriptionsItem,
  XhDescriptionsLabel,
  XhDescriptionsRoot,
  XhDescriptionsValue,
} from "@xihan-ui/vue";

const order = [
  { label: "订单号", value: "XH-20260810-0042" },
  { label: "下单时间", value: "2026-08-10 09:31" },
  { label: "支付方式", value: "余额支付" },
];
</script>

<template>
  <XhDescriptionsRoot style="max-inline-size: 420px">
    <XhDescriptionsItem v-for="row in order" :key="row.label">
      <XhDescriptionsLabel>{{ row.label }}</XhDescriptionsLabel>
      <XhDescriptionsValue>{{ row.value }}</XhDescriptionsValue>
    </XhDescriptionsItem>
  </XhDescriptionsRoot>
</template>

列数

columns 决定每行摆几组，一到六列；排版走 CSS Grid，不用表格

姓名

张三

工号

A-1024

部门

技术部

岗位

前端工程师

入职

2024-03-01

座机

8021

<script setup lang="ts">
import {
  XhDescriptionsItem,
  XhDescriptionsLabel,
  XhDescriptionsRoot,
  XhDescriptionsValue,
} from "@xihan-ui/vue";

const rows = [
  { label: "姓名", value: "张三" },
  { label: "工号", value: "A-1024" },
  { label: "部门", value: "技术部" },
  { label: "岗位", value: "前端工程师" },
  { label: "入职", value: "2024-03-01" },
  { label: "座机", value: "8021" },
];
</script>

<template>
  <XhDescriptionsRoot :columns="3">
    <XhDescriptionsItem v-for="row in rows" :key="row.label">
      <XhDescriptionsLabel>{{ row.label }}</XhDescriptionsLabel>
      <XhDescriptionsValue>{{ row.value }}</XhDescriptionsValue>
    </XhDescriptionsItem>
  </XhDescriptionsRoot>
</template>

标签位置

placement 决定标签在上还是在左，不传即在上

标签在上（默认）

订单号

XH-20260810-0042

下单时间

2026-08-10 09:31

标签在左

订单号

XH-20260810-0042

下单时间

2026-08-10 09:31

<script setup lang="ts">
import {
  XhDescriptionsItem,
  XhDescriptionsLabel,
  XhDescriptionsRoot,
  XhDescriptionsValue,
} from "@xihan-ui/vue";

const rows = [
  { label: "订单号", value: "XH-20260810-0042" },
  { label: "下单时间", value: "2026-08-10 09:31" },
];

// 上面那一档不写 placement，用 undefined 表达
const placements = [
  { placement: undefined, caption: "标签在上（默认）" },
  { placement: "left", caption: "标签在左" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <div v-for="p in placements" :key="p.caption" style="inline-size: 260px">
      <p>{{ p.caption }}</p>
      <XhDescriptionsRoot :placement="p.placement">
        <XhDescriptionsItem v-for="row in rows" :key="row.label">
          <XhDescriptionsLabel>{{ row.label }}</XhDescriptionsLabel>
          <XhDescriptionsValue>{{ row.value }}</XhDescriptionsValue>
        </XhDescriptionsItem>
      </XhDescriptionsRoot>
    </div>
  </div>
</template>

外框

bordered 画一圈描边，并在格与格之间补上网格线

商品

机械键盘

单价

￥499.00

数量

2

小计

￥998.00

<script setup lang="ts">
import {
  XhDescriptionsItem,
  XhDescriptionsLabel,
  XhDescriptionsRoot,
  XhDescriptionsValue,
} from "@xihan-ui/vue";

const rows = [
  { label: "商品", value: "机械键盘" },
  { label: "单价", value: "￥499.00" },
  { label: "数量", value: "2" },
  { label: "小计", value: "￥998.00" },
];
</script>

<template>
  <XhDescriptionsRoot bordered :columns="2" placement="left">
    <XhDescriptionsItem v-for="row in rows" :key="row.label">
      <XhDescriptionsLabel>{{ row.label }}</XhDescriptionsLabel>
      <XhDescriptionsValue>{{ row.value }}</XhDescriptionsValue>
    </XhDescriptionsItem>
  </XhDescriptionsRoot>
</template>

尺寸

size 换的是每格的内边距、组与组的间距与整体字号，不传 size 即默认档

小 · 状态

已发货

小 · 承运商

顺丰速运

默认 · 状态

已发货

默认 · 承运商

顺丰速运

大 · 状态

已发货

大 · 承运商

顺丰速运

<script setup lang="ts">
import {
  XhDescriptionsItem,
  XhDescriptionsLabel,
  XhDescriptionsRoot,
  XhDescriptionsValue,
} from "@xihan-ui/vue";

const rows = [
  { label: "状态", value: "已发货" },
  { label: "承运商", value: "顺丰速运" },
];

// 中间一档不写 size，用 undefined 表达
const sizes = [
  { size: "sm", label: "小" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "大" },
] as const;
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <XhDescriptionsRoot
      v-for="s in sizes"
      :key="s.label"
      :size="s.size"
      bordered
      :columns="2"
      placement="left"
    >
      <XhDescriptionsItem v-for="row in rows" :key="row.label">
        <XhDescriptionsLabel>{{ s.label }} · {{ row.label }}</XhDescriptionsLabel>
        <XhDescriptionsValue>{{ row.value }}</XhDescriptionsValue>
      </XhDescriptionsItem>
    </XhDescriptionsRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-descriptions>
Vue 组件	XhDescriptionsItem XhDescriptionsLabel XhDescriptionsRoot XhDescriptionsValue
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/descriptions.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="descriptions"：root · item · label · value

Props

属性	类型	必填	说明
bordered	boolean		外框：给整份描述画一圈描边，并在格与格之间画网格线。
columns	DescriptionsColumns		每行摆几组，一到六列；不写即每行一组。
placement	DescriptionsPlacement		标签的位置：top / left；不写即标签在上。
size	Size		尺寸：sm / md / lg。

connect API

connect 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
getRootProps	() => T['element']
getItemProps	() => T['element']
getLabelProps	() => T['element']
getValueProps	() => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。