Vben Descriptions 描述列表

Descriptions 用于成组展示只读的字段信息，常用于详情页、信息预览等场景。组件基于 shadcn-ui 构建，API 参考 Ant Design Vue 的 Descriptions，支持响应式列数、跨列、边框、垂直布局等能力。

如果文档内没有覆盖到你需要的细节，可以结合在线示例一起查看。

写在前面

组件提供两种使用方式：通过 items 数据驱动（推荐），或通过子组件 VbenDescriptionsItem 声明列表项。两者可按需选择，items 优先级更高。:::

基础用法

通过 items 传入字段数组，每项包含 label 与 content。默认按断点自适应列数（xs 1 列、sm 2 列、md 及以上 3 列）。

<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';

const items = [
  { content: 'Vben', label: '用户名' },
  { content: '13800138000', label: '手机号' },
  { content: '中国 · 杭州', label: '居住地' },
  { content: '前端工程师', label: '职位' },
  {
    content: '这是一段较长的备注信息，用于演示跨列展示。',
    label: '备注',
    span: 3,
  },
];
</script>
<template>
  <VbenDescriptions :items="items" />
</template>

带边框

设置 bordered 展示边框样式，配合 title 标题与 #extra 插槽（位于标题右侧的操作区域）。

<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';

const items = [
  { content: 'Vben', label: '用户名' },
  { content: '13800138000', label: '手机号' },
  { content: '正常', label: '状态' },
  { content: '中国 · 杭州', label: '居住地' },
  {
    content: '浙江省杭州市西湖区某某街道某某小区 1 幢 2 单元',
    label: '地址',
    span: 3,
  },
];
</script>
<template>
  <VbenDescriptions bordered title="用户信息" :items="items">
    <template #extra>
      <span style="color: #1677ff; cursor: pointer">编辑</span>
    </template>
  </VbenDescriptions>
</template>

垂直布局

通过 layout="vertical" 让标签位于内容上方。

<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';

const items = [
  { content: 'Vben', label: '用户名' },
  { content: '13800138000', label: '手机号' },
  { content: '中国 · 杭州', label: '居住地' },
  { content: '这是一段较长的备注信息。', label: '备注', span: 3 },
];
</script>
<template>
  <VbenDescriptions bordered layout="vertical" :items="items" />
</template>

不同尺寸

通过 size 设置 small、middle、large 三种尺寸。

<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';

const items = [
  { content: 'Vben', label: '用户名' },
  { content: '13800138000', label: '手机号' },
  { content: '中国 · 杭州', label: '居住地' },
  { content: '前端工程师', label: '职位' },
];
</script>
<template>
  <div style="display: flex; flex-direction: column; gap: 16px">
    <VbenDescriptions
      size="small"
      bordered
      title="Small"
      :column="2"
      :items="items"
    />
    <VbenDescriptions
      size="middle"
      bordered
      title="Middle"
      :column="2"
      :items="items"
    />
    <VbenDescriptions
      size="large"
      bordered
      title="Large"
      :column="2"
      :items="items"
    />
  </div>
</template>

跨列与响应式

单项通过 span 设置跨列数，'filled' 表示占满当前行剩余空间；column 支持传入按断点配置的对象实现响应式列数。

<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';

const items = [
  { content: '1', label: 'A' },
  { content: '2（span: 2）', label: 'B', span: 2 },
  { content: '3', label: 'C' },
  { content: '占满当前行剩余空间', label: 'D（span: filled）', span: 'filled' },
  { content: '5', label: 'E' },
];
</script>
<template>
  <!-- 列数随断点变化：xs 1 列、sm 2 列、md 及以上 3 列 -->
  <VbenDescriptions bordered :column="{ md: 3, sm: 2, xs: 1 }" :items="items" />
</template>

子组件用法

不传 items 时，可在默认插槽中使用 VbenDescriptionsItem 声明列表项，内容支持默认插槽或 #content 插槽自定义。

<script lang="ts" setup>
import { VbenDescriptions, VbenDescriptionsItem } from '@vben/common-ui';
</script>
<template>
  <!-- 通过子组件 VbenDescriptionsItem 声明列表项 -->
  <VbenDescriptions bordered :column="2">
    <VbenDescriptionsItem label="用户名">Vben</VbenDescriptionsItem>
    <VbenDescriptionsItem label="状态">
      <span style="color: #52c41a">● 正常</span>
    </VbenDescriptionsItem>
    <VbenDescriptionsItem label="备注" :span="2">
      <template #content>
        <span style="color: #888">通过 #content 插槽自定义内容</span>
      </template>
    </VbenDescriptionsItem>
  </VbenDescriptions>
</template>

API

Descriptions Props

属性名	描述	类型	默认值
items	数据驱动的列表项；不传则读取默认插槽	DescriptionsItemType[]	-
bordered	是否展示边框	boolean	false
column	一行的列数，支持按断点配置	number | Partial<Record<Breakpoint, number>>	{ xs: 1, sm: 2, md: 3, xxxl: 4 }
layout	布局方式	'horizontal' | 'vertical'	'horizontal'
size	尺寸	'small' | 'middle' | 'large'	'middle'
colon	是否显示冒号（仅非边框的水平布局生效）	boolean	true
title	标题	string	-
extra	标题右侧的操作区域	string	-
labelStyle	统一的标签样式	CSSProperties	-
contentStyle	统一的内容样式	CSSProperties	-
class	根节点自定义类名	string	-

Descriptions Slots

插槽名	描述
title	自定义标题
extra	自定义标题右侧操作区域
default	放置 VbenDescriptionsItem 子组件

DescriptionsItem

items 数组中的每一项，或子组件 VbenDescriptionsItem 的属性。

属性名	描述	类型	默认值
label	标签	string | number | (() => VNode) | Component	-
content	内容	string | number | (() => VNode) | Component	-
span	跨列数，'filled' 占满当前行剩余	number | 'filled' | Partial<Record<Breakpoint, number>>	1
labelStyle	标签样式	CSSProperties	-
contentStyle	内容样式	CSSProperties	-
key	唯一标识	string | number	-

DescriptionsItem Slots

仅子组件用法可用。

插槽名	描述
default	内容（等价于 content）
content	自定义内容
label	自定义标签

Breakpoint

响应式断点 Breakpoint 取值为 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl'，断点像素与 Ant Design 一致（sm 576、md 768、lg 992、xl 1200、xxl 1600、xxxl 2000）。:::

贡献者

xingyu4j

页面历史

最后编辑于 5 天前

查看完整历史

04fbb7a-chore: 升级 shadcn-vue 组件到v4最新版 (#7972)