BizDescriptions 详情描述

config 驱动的 label-value 详情列表：items + data 声明式渲染，替代手写一堆 el-descriptions-item。空值统一占位、数组 / 布尔语义化、字段级插槽与 formatter。

基础用法

姓名	张三	手机号	13800138000	所属部门	安全管理部
角色	系统管理员、审计员	是否启用	是	备注	—

数组自动「、」连接，布尔自动「是/否」，空值（备注）统一占位「—」。

items 声明字段，data 提供数据；column / border 等 el-descriptions 属性经 $attrs 透传。

<script setup lang="ts">
/** 基础用法：items + data 声明式渲染，column/border 等 el-descriptions 属性经 $attrs 透传 */
import { BizDescriptions } from 'vue3-ep-biz-lib'
import type { BizDescriptionsItem } from 'vue3-ep-biz-lib'

const detail: Record<string, unknown> = {
  name: '张三',
  mobile: '13800138000',
  dept: '安全管理部',
  roles: ['系统管理员', '审计员'],
  enabled: true,
  remark: '',
}

const items: BizDescriptionsItem[] = [
  { label: '姓名', prop: 'name' },
  { label: '手机号', prop: 'mobile' },
  { label: '所属部门', prop: 'dept' },
  { label: '角色', prop: 'roles' },
  { label: '是否启用', prop: 'enabled' },
  { label: '备注', prop: 'remark' },
]
</script>

<template>
  <div>
    <BizDescriptions :data="detail" :items="items" :column="3" border />
    <div class="tip">数组自动「、」连接，布尔自动「是/否」，空值（备注）统一占位「—」。</div>
  </div>
</template>

<style scoped>
.tip {
  margin-top: 8px;
  font-size: 13px;
  color: var(--el-text-color-secondary);
}
</style>

显示代码

其他用法

订单编号	SO20260901001234			订单状态	已完成
订单金额	¥ 1,280,000	下单时间	2026-09-01 10:30:00	收货地址	江苏省南京市雨花台区软件大道 100 号 A 栋 8 层

金额/时间用 formatter；订单状态用 #status 插槽渲染 ElTag。

formatter 格式化（金额 / 时间）、与字段同名的作用域插槽接管单元格（状态 Tag）、span 跨列。

<script setup lang="ts">
/** 其他用法：formatter 格式化 / 同名作用域插槽接管 / span 跨列 / label-width */
import { BizDescriptions } from 'vue3-ep-biz-lib'
import type { BizDescriptionsItem } from 'vue3-ep-biz-lib'

/** 状态字典：value → tag 类型与文案（业务字典由业务侧维护） */
const STATUS_MAP: Record<number, { type: 'success' | 'warning' | 'info'; text: string }> = {
  0: { type: 'info', text: '待支付' },
  1: { type: 'warning', text: '待发货' },
  2: { type: 'success', text: '已完成' },
}

const detail: Record<string, unknown> = {
  orderNo: 'SO20260901001234',
  amount: 1280000,
  status: 2,
  created: '2026-09-01T10:30:00',
  address: '江苏省南京市雨花台区软件大道 100 号 A 栋 8 层',
}

const items: BizDescriptionsItem[] = [
  { label: '订单编号', prop: 'orderNo', span: 2 },
  { label: '订单状态', prop: 'status' },
  {
    label: '订单金额',
    prop: 'amount',
    formatter: (value) => `¥ ${Number(value).toLocaleString('zh-CN')}`,
  },
  {
    label: '下单时间',
    prop: 'created',
    formatter: (value) => String(value).replace('T', ' ').slice(0, 19),
  },
  { label: '收货地址', prop: 'address', span: 3 },
]
</script>

<template>
  <div>
    <BizDescriptions :data="detail" :items="items" :column="3" border label-width="90px">
      <!-- 与字段同名的插槽：{ item, value, data } 完全接管该单元格 -->
      <template #status="{ value }">
        <ElTag :type="STATUS_MAP[Number(value)]?.type ?? 'info'" size="small">
          {{ STATUS_MAP[Number(value)]?.text ?? '未知' }}
        </ElTag>
      </template>
    </BizDescriptions>
    <div class="tip">金额/时间用 formatter；订单状态用 #status 插槽渲染 ElTag。</div>
  </div>
</template>

<style scoped>
.tip {
  margin-top: 8px;
  font-size: 13px;
  color: var(--el-text-color-secondary);
}
</style>

显示代码

订单详情页

订单详情

订单编号	SO20260923000666			订单状态	已发货
下单渠道	小程序商城	买家	张三（138****8000）	实付金额	¥ 886.50
运费	包邮	下单时间	2026-09-23 09:41:20	支付时间	2026-09-23 09:42:05
发票抬头	—	备注	—	收货地址	江苏省南京市雨花台区软件大道 100 号 A 栋 8 层

空值占位 发票抬头为空串、备注为 undefined，均显示默认「—」；金额为分单位经 formatter 转元

详情页场景：三列 span 布局、金额分转元与时间格式化（formatter）、状态列同名插槽接管渲染 BizStatusTag、空串 / undefined 字段统一「—」占位。

<script setup lang="ts">
/** 场景：订单详情页——三列 span 布局、formatter 金额/时间、状态插槽、空值占位 */
import { ElTag } from 'element-plus'
import { BizDescriptions, BizStatusTag } from 'vue3-ep-biz-lib'
import type { BizDescriptionsItem } from 'vue3-ep-biz-lib'

const STATUS_MAP = {
  paid: { text: '已支付', type: 'success' as const },
  shipped: { text: '已发货', type: 'primary' as const },
  refunded: { text: '已退款', type: 'danger' as const },
}

const order: Record<string, unknown> = {
  orderNo: 'SO20260923000666',
  channel: '小程序商城',
  status: 'shipped',
  amount: 88650,
  freight: 0,
  buyer: '张三（138****8000）',
  createdAt: '2026-09-23T09:41:20',
  paidAt: '2026-09-23T09:42:05',
  invoiceTitle: '',
  remark: undefined,
  address: '江苏省南京市雨花台区软件大道 100 号 A 栋 8 层',
}

const items: BizDescriptionsItem[] = [
  { label: '订单编号', prop: 'orderNo', span: 2 },
  { label: '订单状态', prop: 'status' },
  { label: '下单渠道', prop: 'channel' },
  { label: '买家', prop: 'buyer' },
  {
    label: '实付金额',
    prop: 'amount',
    formatter: (value) => `¥ ${(Number(value) / 100).toFixed(2)}`,
  },
  { label: '运费', prop: 'freight', formatter: (value) => (Number(value) === 0 ? '包邮' : `¥ ${Number(value)}`) },
  {
    label: '下单时间',
    prop: 'createdAt',
    formatter: (value) => String(value).replace('T', ' ').slice(0, 19),
  },
  {
    label: '支付时间',
    prop: 'paidAt',
    formatter: (value) => String(value).replace('T', ' ').slice(0, 19),
  },
  { label: '发票抬头', prop: 'invoiceTitle' },
  { label: '备注', prop: 'remark' },
  { label: '收货地址', prop: 'address', span: 3 },
]
</script>

<template>
  <div>
    <BizDescriptions title="订单详情" :data="order" :items="items" :column="3" border label-width="90px">
      <template #status="{ value }">
        <BizStatusTag :status="String(value)" :status-map="STATUS_MAP" />
      </template>
    </BizDescriptions>
    <div style="margin-top: 8px; display: flex; gap: 8px; align-items: center">
      <ElTag size="small" type="info">空值占位</ElTag>
      <span style="font-size: 13px; color: var(--el-text-color-secondary)">
        发票抬头为空串、备注为 undefined，均显示默认「—」；金额为分单位经 formatter 转元
      </span>
    </div>
  </div>
</template>

显示代码

设备档案

设备档案

序列号	DEV-1024	型号	VS-330 温湿度变送器	厂商	威世
在线状态	在线	电量	82%	固件版本	v2.4.1
安装位置	一号车间 3 号工位	安装日期	2025-11-03	现场照片

设备场景：布尔值 formatter、在线状态插槽化 ElTag、现场照片插槽嵌 img——档案页三类渲染形态一次覆盖。

<script setup lang="ts">
/** 场景：设备档案——布尔/枚举 formatter 徽标化 + 同名插槽嵌图片 */
import { ElTag } from 'element-plus'
import { BizDescriptions } from 'vue3-ep-biz-lib'
import type { BizDescriptionsItem } from 'vue3-ep-biz-lib'

const device: Record<string, unknown> = {
  sn: 'DEV-1024',
  model: 'VS-330 温湿度变送器',
  vendor: '威世',
  online: true,
  battery: '82%',
  firmware: 'v2.4.1',
  installedAt: '2025-11-03',
  location: '一号车间 3 号工位',
  photo: 'https://images.unsplash.com/photo-1581091226825-a6a2a5aee158?w=240&h=160&fit=crop',
}

const items: BizDescriptionsItem[] = [
  { label: '序列号', prop: 'sn' },
  { label: '型号', prop: 'model' },
  { label: '厂商', prop: 'vendor' },
  { label: '在线状态', prop: 'online', formatter: (value) => (value === true ? '在线' : '离线') },
  { label: '电量', prop: 'battery' },
  { label: '固件版本', prop: 'firmware' },
  { label: '安装位置', prop: 'location' },
  { label: '安装日期', prop: 'installedAt' },
  { label: '现场照片', prop: 'photo' },
]
</script>

<template>
  <BizDescriptions title="设备档案" :data="device" :items="items" :column="3" border label-width="80px">
    <template #online="{ value }">
      <ElTag :type="value === true ? 'success' : 'info'" size="small">{{ value === true ? '在线' : '离线' }}</ElTag>
    </template>
    <template #photo="{ value }">
      <img :src="String(value)" alt="现场照片" style="width: 160px; height: 100px; object-fit: cover; border-radius: 4px" />
    </template>
  </BizDescriptions>
</template>

显示代码

合同预览

合同编号	HT-2026-0918	签订日期	2026-09-18
到期日期	2027-09-17	甲方（委托方）	云联科技（南京）有限公司
乙方（受托方）	华东工业设备集团有限公司
合同金额（元）	1,280,000	已付金额（元）	640,000
联系电话	—	备注	含两次现场巡检；违约金按合同总额 0.5%/日计。

联系人为空显示占位「—」；金额经 formatter 千分位

法务场景：长标签（label-width 120px）双列、金额千分位 formatter、空联系电话占位「—」、备注跨两列。

<script setup lang="ts">
/** 场景：合同预览——长标签双列 + 金额千分位 + 空字段占位 */
import { BizDescriptions } from 'vue3-ep-biz-lib'
import type { BizDescriptionsItem } from 'vue3-ep-biz-lib'

const contract: Record<string, unknown> = {
  contractNo: 'HT-2026-0918',
  partyA: '云联科技（南京）有限公司',
  partyB: '华东工业设备集团有限公司',
  amount: 1280000,
  paidAmount: 640000,
  signDate: '2026-09-18',
  expireDate: '2027-09-17',
  contactPhone: '',
  remark: '含两次现场巡检；违约金按合同总额 0.5%/日计。',
}

const items: BizDescriptionsItem[] = [
  { label: '合同编号', prop: 'contractNo' },
  { label: '签订日期', prop: 'signDate' },
  { label: '到期日期', prop: 'expireDate' },
  { label: '甲方（委托方）', prop: 'partyA', span: 2 },
  { label: '乙方（受托方）', prop: 'partyB', span: 2 },
  { label: '合同金额（元）', prop: 'amount', formatter: (value) => Number(value).toLocaleString('zh-CN') },
  { label: '已付金额（元）', prop: 'paidAmount', formatter: (value) => Number(value).toLocaleString('zh-CN') },
  { label: '联系电话', prop: 'contactPhone' },
  { label: '备注', prop: 'remark', span: 2 },
]
</script>

<template>
  <div>
    <BizDescriptions :data="contract" :items="items" :column="2" border label-width="120px" />
    <div style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">联系人为空显示占位「—」；金额经 formatter 千分位</div>
  </div>
</template>

显示代码

个人中心

头像张	姓名张三	部门安全管理部
岗位安全工程师	邮箱zhangsan@example.cn	司龄5 年
爱好羽毛球摄影徒步

资料场景：头像插槽（ElAvatar）、爱好字段插槽渲染标签组、司龄 formatter 加单位。

<script setup lang="ts">
/** 场景：个人中心——头像插槽 + 爱好标签组渲染 */
import { ElAvatar, ElTag } from 'element-plus'
import { BizDescriptions } from 'vue3-ep-biz-lib'
import type { BizDescriptionsItem } from 'vue3-ep-biz-lib'

const user: Record<string, unknown> = {
  name: '张三',
  dept: '安全管理部',
  role: '安全工程师',
  email: 'zhangsan@example.cn',
  workYears: 5,
  hobbies: ['羽毛球', '摄影', '徒步'],
}

const items: BizDescriptionsItem[] = [
  { label: '头像', prop: 'avatar' },
  { label: '姓名', prop: 'name' },
  { label: '部门', prop: 'dept' },
  { label: '岗位', prop: 'role' },
  { label: '邮箱', prop: 'email' },
  { label: '司龄', prop: 'workYears', formatter: (value) => `${value} 年` },
  { label: '爱好', prop: 'hobbies', span: 2 },
]
</script>

<template>
  <BizDescriptions :data="user" :items="items" :column="3" label-width="70px">
    <template #avatar>
      <ElAvatar :size="48">张</ElAvatar>
    </template>
    <template #hobbies="{ value }">
      <span style="display: inline-flex; gap: 6px">
        <ElTag v-for="hobby in (value as string[])" :key="hobby" size="small" type="info">{{ hobby }}</ElTag>
      </span>
    </template>
  </BizDescriptions>
</template>

显示代码

Props

属性名	类型	默认值	说明
data	Record<string, unknown>	{}	数据对象
items	BizDescriptionsItem[]	[]	字段配置（顺序即展示顺序）
empty-text	string	'—'	空值占位（null / undefined / '' / 空数组）

BizDescriptionsItem：

属性名	类型	必填	说明
label	string	是	标签文案
prop	string	是	取值字段名（同时作为作用域插槽名）
span	number	否	跨列数（el-descriptions-item span）
label-width	string | number	否	标签宽度（border 模式生效）
formatter	(value, data) => string	否	值格式化（无插槽时生效）

其余属性（column / border / size / direction / title...）经 v-bind="$attrs" 全量透传 el-descriptions。

Events

事件名	参数	说明
—	—	无自有事件；el-descriptions 原生事件经 $attrs 透传

Slots

插槽名	说明
#字段名（动态）	作用域 { item, value, data }，完全接管该字段单元格渲染

Expose

属性/方法	说明
data	当前数据对象