展示组件

@vben/components/view 与 @vben/components/description 提供只读回显场景的组件，与表单组件成对使用：表单负责编辑，展示组件负责详情页与表格列的回显。

import { ApiDict, ApiView, FilePreview, Text } from '@vben/components/view';
import { Description } from '@vben/components/description';

view 的 component-map.ts 会把组件注册为 TextXxx 名称（如 TextApiDict、TextApiSelect），供详情页 schema 以字符串引用。view/types/hook.ts 还提供 formToDetailBySchema(formSchemas)：把编辑态的 form schema 批量转换为详情 schema（Input → Text、ApiSelect → TextApiSelect……），同一份字段定义同时驱动表单页与详情页，避免重复维护。

1. ApiDict（view 版）字典回显

把字典/枚举值回显为标签，支持三种模式与丰富的着色配置，是表格列和详情页里显示状态字段的标准方式。

Prop	类型	默认值	说明
`value`	`string \| number \| boolean \| Array`	-	字典值（数组为多值）
`type`	`string`	必填	字典类型或枚举类型
`mode`	`'tag' \| 'badge' \| 'text'`	`'tag'`	回显方式
`data`	`object`	-	当前行数据（需要联动时传入）
`dataType`	`'1' \| '2' \| '3'`	-	值数据类型
`colorMap`	`Record<string, ColorType>`	`{}`	值 → 颜色的映射
`colorList`	`ColorType[]`	内置 30 组预设色	预设颜色列表
`useColorList`	`boolean`	`false`	是否按预设色列表自动轮换着色
`useCss`	`boolean`	`true`	使用字典项上配置的 `cssStyle` / `cssClass`

<template>
  <!-- 状态列：彩色标签 -->
  <ApiDict type="common.state" :value="record.state" />
  <!-- 纯文本 -->
  <ApiDict type="common.gender" :value="record.gender" mode="text" />
</template>

着色优先级

字典项自身配置的 css（useCss）> colorMap 显式映射 > useColorList 预设色轮换。一般只需在控制台维护字典项颜色即可。

2. ApiView 选项回显

通用「值 → label」回显组件：传入 options（支持树形，递归查找），把 value 显示为 label，多值自动拼接。

Prop	类型	默认值	说明
`value`	`string \| number \| Array`	-	值（字符串含分隔符时自动拆分）
`options`	`Array`	`[]`	选项（支持 children 树形）
`separator`	`string`	`,`	值分隔符
`displaySeparator`	`string`	`', '`	展示分隔符

3. Text 文本

对 antdv TypographyParagraph 的透传封装，viewComponent="Typography" 时启用排版能力（省略、复制等），否则渲染为普通 <p>。

4. Description 描述列表

schema 驱动的详情页组件，底层 antdv Descriptions。schema 中每个 DescItem 可通过 component 指定 view 组件回显（如 ApiDict），也可用 render 自定义。

Prop	类型	默认值	说明
`schema`	`DescItem[]`	`[]`	描述项配置
`data`	`object`	-	数据对象（按 `field` 取值，支持 `a.b.c` 路径）
`title`	`string`	`''`	标题
`bordered`	`boolean`	`true`	边框
`column`	`number \| object`	`12`	列数
`size`	`'default' \| 'middle' \| 'small'`	`'small'`	尺寸
`labelStyle` / `contentStyle`	`object`	`width: 10% / 40%`	样式

DescItem 关键字段：

字段	说明
`field`	取值路径（支持 `a.b.c`）
`label`	标签
`span`	合并列
`component`	view 组件名（在 `componentMap` 中注册过的，如 `'ApiDict'`）
`componentProps`	传给组件的 props
`render(val, data)`	自定义渲染（优先级低于 component）
`copy`	显示点击复制按钮（基于 `VxeText`）
`show()`	条件显示

const schema: DescItem[] = [
  { field: 'name', label: '应用名称' },
  { field: 'appKey', label: 'AppKey', copy: true },
  {
    field: 'state',
    label: '状态',
    component: 'ApiDict',
    componentProps: { type: 'common.state' },
  },
];

<Description :schema="schema" :data="detail" title="应用信息" />

5. FilePreview 文件预览（Office/PDF）

基于 vue-office 的弹窗预览，支持 doc/docx/xls/xlsx/pdf。通过 ref 拿到 modalApi，setData 后打开：

<script setup lang="ts">
import { FilePreview } from '@vben/components/view';

const filePreviewRef = ref<InstanceType<typeof FilePreview>>();

function preview(row: SysFileVo) {
  filePreviewRef.value?.modalApi.setData({
    fileInfo: { fileName: row.originalName, data: fileBlob },
  }).open();
}
</script>

<template>
  <FilePreview ref="filePreviewRef" />
</template>

fileInfo.data 支持三种形式：URL 字符串、Blob、ArrayBuffer（后两者内部转 blob URL，关闭时自动释放）。

6. FileAudioModal / FileVideoModal 音视频预览

音频、视频播放弹窗，同样通过 ref 暴露 modalApi 使用：

<script setup lang="ts">
const fileAudioModalRef = ref();
function play(row: SysFileVo) {
  fileAudioModalRef.value?.modalApi
    .setState({ title: row.originalName || '音频播放' })
    .setData({ url: row.url })
    .open();
}
</script>

<template>
  <FileAudioModal ref="fileAudioModalRef" />
  <FileVideoModal ref="fileVideoModalRef" />
</template>

完整示例可参考文件管理页面 apps/web-console/src/views/console/system/file/index.vue。