Descriptions 描述列表
把一条记录的多个字段按“标签 + 内容”成组排列,常用在详情页。每个字段用一个 NsDescriptionsItem。
引入
import { NsDescriptions, NsDescriptionsItem } from '@ns/ui'
基础用法
NsDescriptionsItem 的 label 是标签,默认插槽是内容。默认一行放 3 个字段,标题用 title 传文字。
<script setup lang="ts">
import { NsDescriptions, NsDescriptionsItem } from '@ns/ui'
</script>
<template>
<NsDescriptions title="用户信息">
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
<NsDescriptionsItem label="备注">无</NsDescriptionsItem>
</NsDescriptions>
</template>
带边框
border 给整个列表和每个单元格加边框。一行没放满时,带边框的空位照样画出单元格(下面第二行的最后一格)。
<template>
<NsDescriptions title="用户信息" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
<NsDescriptionsItem label="备注">无</NsDescriptionsItem>
</NsDescriptions>
</template>
每行的列数
column 指定一行放几个字段,默认是 3。小于 1 或不是数字时按 1 处理。
<template>
<NsSpace direction="vertical" fill>
<NsDescriptions title="column = 1" :column="1" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions title="column = 2" :column="2" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions title="column = 4" :column="4" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
</NsDescriptions>
</NsSpace>
</template>
跨列
NsDescriptionsItem 的 span 指定这个字段占几列。一行剩下的位置放不下时,这个字段会换到下一行;span 比 column 大时按 column 算,也就是占满一行。
<template>
<NsDescriptions title="订单信息" :column="3" border>
<NsDescriptionsItem label="订单号">SO20260301001</NsDescriptionsItem>
<NsDescriptionsItem label="状态">已发货</NsDescriptionsItem>
<NsDescriptionsItem label="金额">¥ 128.00</NsDescriptionsItem>
<NsDescriptionsItem label="下单时间">2026-03-01 10:30</NsDescriptionsItem>
<NsDescriptionsItem label="收货人" :span="2">张三,13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="收货地址" :span="3">
北京市朝阳区建国路 88 号 SOHO 现代城 A 座 1001 室
</NsDescriptionsItem>
<NsDescriptionsItem label="备注" :span="10"
>span 是 10,按 column 算,占满一行</NsDescriptionsItem
>
</NsDescriptions>
</template>
尺寸
size 可选 large、default、small,影响字号和内边距。正文字号 large、default 都是 14px,small 是 12px,三档主要靠内边距区分(单元格 12px 16px、8px 12px、4px 8px);标题 large 是 16px,其余和正文一样大。不写 size 时跟随 ConfigProvider,都没有时是 default。
<template>
<NsSpace direction="vertical" fill>
<NsDescriptions title="large" size="large" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions title="default" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions title="small" size="small" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
</NsDescriptions>
</NsSpace>
</template>
标签宽度
label-width 设置所有标签的宽度,数字的单位是 px,也可以传 '20%' 这样的字符串。默认 'auto':标签列和内容列平分宽度,标签比较短时显得空,建议设一个固定宽度。
<template>
<NsSpace direction="vertical" fill>
<NsDescriptions title="不设 label-width(auto)" :column="2" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions title="label-width = 100" :column="2" :label-width="100" border>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
</NsDescriptions>
</NsSpace>
</template>
对齐方式
label-align 和 content-align 分别设置标签和内容的对齐方式,可选 left、center、right。标签默认靠右(right),内容默认靠左(left)。下面三个列表标签宽度都是 120px,标题写着用的值:
<template>
<NsSpace direction="vertical" fill>
<NsDescriptions
title="label-align = left,content-align = left"
:column="2"
:label-width="120"
label-align="left"
content-align="left"
border
>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions
title="label-align = center,content-align = center"
:column="2"
:label-width="120"
label-align="center"
content-align="center"
border
>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions
title="label-align = right,content-align = right"
:column="2"
:label-width="120"
label-align="right"
content-align="right"
border
>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="居住地">北京市</NsDescriptionsItem>
<NsDescriptionsItem label="邮箱">zhangsan@example.com</NsDescriptionsItem>
</NsDescriptions>
</NsSpace>
</template>
自定义标题
标题要放按钮等内容时用 title 插槽,标题栏是两端对齐的,按钮会靠右。title 也可以直接传一个 VNode(用 h 创建),适合标题在脚本里拼好的场景。
<script setup lang="ts">
import { h, ref } from 'vue'
import { NsButton, NsDescriptions, NsDescriptionsItem, NsMessage, NsSpace, NsTag } from '@ns/ui'
const editCount = ref(0)
const edit = () => {
editCount.value++
NsMessage.info(`点了第 ${editCount.value} 次编辑`)
}
const titleNode = h('span', [
h('strong', '订单 SO20260301001 '),
h(NsTag, { type: 'success', size: 'small' }, () => '已支付')
])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDescriptions border>
<template #title>
<strong>用户信息</strong>
<NsButton size="small" icon="edit" @click="edit">编辑</NsButton>
</template>
<NsDescriptionsItem label="用户名">张三</NsDescriptionsItem>
<NsDescriptionsItem label="手机号">13800138000</NsDescriptionsItem>
</NsDescriptions>
<NsDescriptions :title="titleNode" border>
<NsDescriptionsItem label="金额">¥ 128.00</NsDescriptionsItem>
<NsDescriptionsItem label="支付方式">微信支付</NsDescriptionsItem>
</NsDescriptions>
</NsSpace>
</template>
自定义标签和内容
标签用 NsDescriptionsItem 的 label 插槽自定义,也可以给 label 传 VNode。内容区可以放任意元素和组件。
<script setup lang="ts">
import { h } from 'vue'
import { NsDescriptions, NsDescriptionsItem, NsIcon, NsTag } from '@ns/ui'
const phoneLabel = h('span', [h(NsIcon, { name: 'phone' }), ' 手机号'])
</script>
<template>
<NsDescriptions :column="2" border>
<NsDescriptionsItem>
<template #label>
<NsIcon name="user" />
用户名
</template>
张三
</NsDescriptionsItem>
<NsDescriptionsItem :label="phoneLabel">13800138000</NsDescriptionsItem>
<NsDescriptionsItem label="状态">
<NsTag type="success" size="small">启用</NsTag>
</NsDescriptionsItem>
<NsDescriptionsItem label="主页">
<a href="https://example.com" target="_blank" rel="noopener">https://example.com</a>
</NsDescriptionsItem>
</NsDescriptions>
</template>
按数据生成
字段多的时候可以用 v-for 生成,也可以用 v-if 控制某个字段显示不显示。字段增减后会重新排行。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDescriptions, NsDescriptionsItem, NsSpace, NsSwitch } from '@ns/ui'
const fields = ref([
{ key: 'name', label: '用户名', value: '张三' },
{ key: 'phone', label: '手机号', value: '13800138000' },
{ key: 'city', label: '居住地', value: '北京市' }
])
const showRemark = ref(true)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsSwitch v-model="showRemark" active-text="显示备注" />
</NsSpace>
<NsDescriptions :column="2" border>
<NsDescriptionsItem v-for="field in fields" :key="field.key" :label="field.label">
{{ field.value }}
</NsDescriptionsItem>
<NsDescriptionsItem v-if="showRemark" label="备注">无</NsDescriptionsItem>
</NsDescriptions>
</NsSpace>
</template>
NsDescriptions Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| column | number | 3 | 一行放几个字段。小于 1 或不是数字时按 1 处理 |
| border | boolean | false | 是否显示边框 |
| title | string | VNode | - | 标题。写了 title 插槽时不显示 |
| labelWidth | string | number | 'auto' | 标签的宽度,数字的单位是 px |
| labelAlign | 'left' | 'center' | 'right' | 'right' | 标签的对齐方式 |
| contentAlign | 'left' | 'center' | 'right' | 'left' | 内容的对齐方式 |
| size | 'small' | 'default' | 'large' | - | 尺寸,影响字号和内边距。不写时跟随 ConfigProvider,都没有时是 'default' |
NsDescriptionsItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label | string | VNode | - | 标签。写了 label 插槽时不显示 |
| span | number | 1 | 占几列,最大是外层的 column |
NsDescriptions Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsDescriptionsItem |
| title | - | 标题区域的内容 |
NsDescriptionsItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 字段的内容 |
| label | - | 字段的标签 |
类型
import type { DescriptionsProps, DescriptionsItemProps, DescriptionsSize } from '@ns/ui'
import type { VNode } from 'vue'
type DescriptionsSize = 'small' | 'default' | 'large'
interface DescriptionsProps {
column?: number
border?: boolean
title?: string | VNode
labelWidth?: string | number
labelAlign?: 'left' | 'center' | 'right'
contentAlign?: 'left' | 'center' | 'right'
size?: DescriptionsSize
}
interface DescriptionsItemProps {
label?: string | VNode
span?: number
}
另外还导出了 DescriptionsContext、DescriptionsItemInstance 和 DESCRIPTIONS_INJECTION_KEY,组件内部现在已经不用它们了,不建议依赖。
注意事项
NsDescriptionsItem必须直接放在NsDescriptions的默认插槽里(可以隔着v-for、v-if和<template>)。外面包一层div或者包进自己写的组件里,这个字段就不会显示。默认插槽里不是NsDescriptionsItem的内容会被忽略。NsDescriptionsItem自己不渲染任何东西,标签和内容由NsDescriptions读出来放进表格的单元格。所以在它上面写class、style、事件监听不会生效,要加样式就包在内容里。- 一行没放满时,剩下的位置留空。带边框时空位照样画出单元格。
- 标签和内容太长时会自动换行。没设
labelWidth时各列平分宽度,标签比较短的话建议设一个固定的labelWidth。 labelAlign的默认值是'right'。
优化点
- [ ] 支持响应式列数配置
- [ ] 支持描述项折叠功能
- [ ] 支持空值占位显示
- [ ] 支持纵向布局(标签在上、内容在下)
- [ ] 单个字段单独设置标签宽度、对齐方式和类名