组件概览

Vben Admin 提供了 10 个开箱即用的前端组件，覆盖常见的业务场景。

组件列表

上传组件

组件	说明	特性
ImageUpload	图片上传组件	支持裁剪、预览、多图上传
FileUpload	文件上传组件	支持拖拽、多文件、进度显示

编辑器组件

组件	说明	特性
RichEditor	富文本编辑器	基于 Quill，支持图片、视频
MarkdownEditor	Markdown 编辑器	实时预览、语法高亮
CodeEditor	代码编辑器	基于 Monaco Editor，多语言支持

选择器组件

组件	说明	特性
IconPicker	图标选择器	支持搜索、分类
RegionPicker	地区选择器	省市区三级联动

可视化组件

组件	说明	特性
VbenChart	图表组件	基于 ECharts，响应式
VbenImagePreview	图片预览组件	缩放、旋转、切换
VbenPdfPreview	PDF 预览组件	翻页、缩放、下载

快速使用

安装依赖

# 编辑器组件依赖
pnpm add -w quill marked monaco-editor

# 可视化组件依赖
pnpm add -w echarts viewerjs pdfjs-dist

# 其他依赖
pnpm add -w @types/marked

全局注册

在 src/main.ts 中注册：

import { createApp } from 'vue'
import App from './app.vue'

// 导入组件
import {
  ImageUpload,
  FileUpload,
  RichEditor,
  MarkdownEditor,
  CodeEditor,
  IconPicker,
  RegionPicker,
  VbenChart,
  VbenImagePreview,
  VbenPdfPreview,
} from '@vben/common-ui'

const app = createApp(App)

// 注册组件
app.component('ImageUpload', ImageUpload)
app.component('FileUpload', FileUpload)
app.component('RichEditor', RichEditor)
app.component('MarkdownEditor', MarkdownEditor)
app.component('CodeEditor', CodeEditor)
app.component('IconPicker', IconPicker)
app.component('RegionPicker', RegionPicker)
app.component('VbenChart', VbenChart)
app.component('VbenImagePreview', VbenImagePreview)
app.component('VbenPdfPreview', VbenPdfPreview)

app.mount('#app')

按需引入

在组件中按需引入：

<script setup lang="ts">
import { ImageUpload } from '@vben/common-ui'
import { ref } from 'vue'

const imageUrl = ref('')
</script>

<template>
  <ImageUpload v-model="imageUrl" />
</template>

组件特性

🎨 统一设计

所有组件遵循统一的设计规范，保证视觉一致性。

📱 响应式

完美适配移动端和桌面端，提供一致的用户体验。

🔧 可配置

提供丰富的配置选项，满足不同场景需求。

🌍 国际化

内置国际化支持，支持多语言切换。

♿ 无障碍

遵循 WCAG 2.1 标准，提供良好的无障碍体验。

📦 TypeScript

完整的 TypeScript 类型定义，提供更好的开发体验。

组件分类

表单组件

用于数据输入和编辑：

• ImageUpload - 图片上传
• FileUpload - 文件上传
• IconPicker - 图标选择
• RegionPicker - 地区选择
• RichEditor - 富文本编辑
• MarkdownEditor - Markdown 编辑
• CodeEditor - 代码编辑

展示组件

用于数据展示和可视化：

• VbenChart - 图表展示
• VbenImagePreview - 图片预览
• VbenPdfPreview - PDF 预览

使用示例

基础示例

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload, RichEditor, VbenChart } from '@vben/common-ui'
import type { EChartsOption } from 'echarts'

const imageUrl = ref('')
const content = ref('')
const chartOption: EChartsOption = {
  xAxis: { data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'] },
  yAxis: {},
  series: [{ type: 'line', data: [150, 230, 224, 218, 135] }]
}
</script>

<template>
  <div>
    <!-- 图片上传 -->
    <ImageUpload v-model="imageUrl" :limit="1" />
    
    <!-- 富文本编辑器 -->
    <RichEditor v-model="content" height="400px" />
    
    <!-- 图表 -->
    <VbenChart :option="chartOption" height="400px" />
  </div>
</template>

表单集成

<script setup lang="ts">
import { ref } from 'vue'
import { Form, FormItem, Button } from 'ant-design-vue'
import { ImageUpload, RegionPicker } from '@vben/common-ui'

const formData = ref({
  avatar: '',
  region: '',
})

const handleSubmit = () => {
  console.log('提交数据：', formData.value)
}
</script>

<template>
  <Form :model="formData" @submit="handleSubmit">
    <FormItem label="头像">
      <ImageUpload v-model="formData.avatar" />
    </FormItem>
    
    <FormItem label="地区">
      <RegionPicker v-model="formData.region" :level="3" />
    </FormItem>
    
    <FormItem>
      <Button type="primary" html-type="submit">提交</Button>
    </FormItem>
  </Form>
</template>

主题定制

所有组件支持主题定制：

// 在 preferences.ts 中配置
export const preferences = {
  theme: {
    primaryColor: '#1890ff',
    borderRadius: '4px',
    // ...
  }
}

性能优化

按需加载

使用动态导入减少初始加载时间：

const RichEditor = defineAsyncComponent(() => 
  import('@vben/common-ui').then(m => m.RichEditor)
)

懒加载

对于大型组件，使用懒加载：

<script setup lang="ts">
import { defineAsyncComponent } from 'vue'

const CodeEditor = defineAsyncComponent(() =>
  import('@vben/common-ui').then(m => m.CodeEditor)
)
</script>

浏览器兼容性

浏览器	版本
Chrome	>= 80
Firefox	>= 78
Safari	>= 13
Edge	>= 80

下一步

• 📖 查看各组件详细文档
• 🎨 学习 主题定制
• 🔧 了解 工具类

相关链接

• 组件源码
• 在线示例
• 问题反馈