DataDescriptions 描述列表

基于 flex 布局的详情展示组件，适合详情页信息块、配置化信息展示、订单/用户详情等场景。

在线演示

tsx

import { defineComponent, reactive, h } from 'vue'
import { ElTag, ElRate, ElAvatar } from 'element-plus'
import DataDescriptions from '@/components/DataDescriptions'

export default defineComponent({
  name: 'DemoDataDescriptionsFull',
  setup() {
    const data = reactive({
      orderNo: 'ORD20240115001',
      name: '张三',
      age: 28,
      email: 'zhangsan@example.com',
      phone: '138****8888',
      role: '管理员',
      status: 'active',
      level: 4,
      address: '北京市朝阳区建国路88号',
      createdAt: '2024-01-15 10:30',
      creator: '系统管理员',
      remark: '这是一个示例订单的描述信息，用于展示 DataDescriptions 组件的各种配置能力。',
    })

    const columns: any[] = [
      { label: '订单编号', field: 'orderNo', span: 24 },
      {
        label: '用户信息',
        span: 24,
        columns: [
          { label: '姓名', field: 'name', span: 12 },
          { label: '年龄', field: 'age', span: 12 },
          { label: '邮箱', field: 'email', span: 12 },
          { label: '电话', field: 'phone', span: 12 },
        ],
      },
      {
        label: '状态',
        field: 'status',
        span: 12,
        render: () => h(ElTag, { type: 'success', effect: 'dark' }, '启用'),
      },
      {
        label: '角色',
        field: 'role',
        span: 12,
        render: () => h(ElTag, { type: 'primary' }, '管理员'),
      },
      {
        label: '用户评分',
        field: 'level',
        span: 24,
        render: ({ value }: any) => h(ElRate, { modelValue: value, disabled: true }),
      },
      { label: '地址', field: 'address', span: 24 },
      { label: '创建时间', field: 'createdAt', span: 12 },
      { label: '创建人', field: 'creator', span: 12 },
      { label: '备注', field: 'remark', span: 24 },
    ]

    return () => (
      <div style="display:flex;flex-direction:column;gap:32px;">
        <div class="demo-block">
          <h4 style="margin:0 0 12px;font-size:15px;">📋 栅格模式 (column=24, span 控制宽度)</h4>
          <DataDescriptions data={data} columns={columns} column={24} labelWidth={80} />
        </div>
        <div class="demo-block">
          <h4 style="margin:0 0 12px;font-size:15px;">📦 边框模式 (border)</h4>
          <DataDescriptions data={data} columns={columns} column={24} labelWidth={100} border />
        </div>
        <div class="demo-block">
          <h4 style="margin:0 0 12px;font-size:15px;">↔️ 行内模式 (inline + 自定义宽度 + 响应式)</h4>
          <DataDescriptions
            data={data}
            columns={[
              { label: '姓名', field: 'name', width: 200 },
              { label: '邮箱', field: 'email', width: 300 },
              { label: '角色', field: 'role', width: 120, render: () => h(ElTag, { type: 'primary' }, '管理员') },
              { label: '状态', field: 'status', width: 120, render: () => h(ElTag, { type: 'success' }, '启用') },
              { label: '地址', field: 'address', width: '100%' },
            ]}
            labelWidth={60}
            inline
          />
        </div>
      </div>
    )
  },
})

Props

属性名	类型	默认值	说明
data	`Record<string, any>`	`{}`	数据源对象，field 通过路径取值
columns	`DataDescriptionColumn[]`	`[]`	字段配置数组
column	`number`	`24`	栅格总列数，配合 span 计算宽度（类似 24 栅格系统）
inline	`boolean`	`false`	行内模式。开启后 item 按内容宽度排列，可换行
border	`boolean`	`false`	边框模式，开启后显示表格线
labelWidth	`string \| number`	-	全局 label 宽度，可被列级 labelWidth 覆盖

列配置 DataDescriptionColumn

属性名	类型	说明
label	`string`	标签名
field	`string`	字段名，支持嵌套路径（如 `user.name`）
span	`number`	栅格占位，基于 `column` 值计算百分比宽度
width	`string \| number`	指定宽度（优先级高于 span），如 `200`、`'50%'`
render	`Function`	自定义渲染：`({ data, value, row }) => VNode`
columns	`DataDescriptionColumn[]`	嵌套子列，递归渲染
value	`any`	直接指定值（优先级高于 field）
responsive	`Object`	响应式宽度：`{ xs, sm, md, lg, xl, xxl }`
labelWidth	`string \| number`	单独指定当前列的 label 宽度，覆盖全局
labelClassName	`string`	label 的自定义 class
valueClassName	`string`	value 的自定义 class
class	`any`	item 的自定义 class
style	`CSSProperties`	item 的自定义样式

渲染优先级

columns — 递归渲染子列
render — 自定义渲染函数，接收 { data, value, row }
value — 直接指定的值
field — 从 data 中取值

三种模式

栅格模式（默认）

通过 column + span 控制宽度，类似 24 栅格系统。未填 span 时默认占满一行。

const columns = [
  { label: '姓名', field: 'name', span: 12 },  // 半行
  { label: '年龄', field: 'age', span: 12 },    // 半行
  { label: '地址', field: 'address', span: 24 }, // 整行
]

<DataDescriptions data={data} columns={columns} column={24} />

边框模式

加 border 属性开启表格线样式，label 带灰底背景。

tsx

<DataDescriptions data={data} columns={columns} border labelWidth={100} />

行内模式

加 inline 属性，每个 item 按内容宽度排列，适合标签列表类展示。

tsx

<DataDescriptions
  data={data}
  columns={[
    { label: '姓名', field: 'name', width: 160 },
    { label: '邮箱', field: 'email', width: 280 },
  ]}
  inline
  labelWidth={60}
/>

自定义渲染 render

结合 Element Plus 组件渲染丰富的内容：

tsx

import { h } from 'vue'
import { ElTag, ElRate, ElAvatar } from 'element-plus'

const columns = [
  {
    label: '状态',
    field: 'status',
    render: ({ value }) => h(ElTag, { type: value === 1 ? 'success' : 'info' }, value === 1 ? '启用' : '停用'),
  },
  {
    label: '评分',
    field: 'level',
    render: ({ value }) => h(ElRate, { modelValue: value, disabled: true }),
  },
  {
    label: '头像',
    field: 'avatar',
    render: ({ value }) => h(ElAvatar, { src: value, size: 'small' }),
  },
]

嵌套子列

通过 columns 字段递归嵌套，实现分组展示：

tsx

const columns = [
  { label: '订单编号', field: 'orderNo', span: 24 },
  {
    label: '用户信息',
    span: 24,
    columns: [
      { label: '姓名', field: 'user.name', span: 12 },
      { label: '电话', field: 'user.phone', span: 12 },
    ],
  },
]

响应式宽度

通过 responsive 配置不同断点下的宽度，断点与 Bootstrap 一致：

tsx

const columns = [
  {
    label: '订单编号',
    field: 'id',
    width: 320,
    responsive: { xs: '100%', md: '50%', xl: 320 },
  },
]

<DataDescriptions data={data} columns={columns} inline labelWidth="80px" />

断点映射：

断点	窗口宽度
`xs`	< 576px
`sm`	≥ 576px
`md`	≥ 768px
`lg`	≥ 992px
`xl`	≥ 1200px
`xxl`	≥ 1600px

DataDescriptions 描述列表 ​

在线演示 ​

Props ​

列配置 DataDescriptionColumn ​

渲染优先级 ​

三种模式 ​

栅格模式（默认） ​

边框模式 ​

行内模式 ​

自定义渲染 render ​

嵌套子列 ​

响应式宽度 ​