组件总览

vue3-element-admin 提供了丰富的业务组件，帮助你快速开发企业级应用。

🎯 在线体验：https://vue.youlai.tech - 大部分组件支持在线演示，文档中标注 🎯 表示有演示链接。

组件统计：24 个业务组件

推荐学习顺序

顺序	组件	为什么先学？
1	CURD 快速开发	最核心！5 分钟搭建增删改查页面
2	DictSelect 字典选择器	表单必备，下拉选择自动加载字典
3	DictTag 字典标签	表格必备，字典值自动翻译显示
4	IconSelect 图标选择器	菜单配置、表单常用
5	TableSelect 表格选择器	弹窗选择数据，关联查询场景
6	Upload 上传	图片、文件上传必用

组件分类

表单组件

组件	说明	文档
IconSelect	图标选择器，支持搜索和分页	查看
DictSelect	字典选择器，支持下拉、单选、复选	查看
DictTag	字典标签，用于展示字典值	查看
TableSelect	表格选择器，支持单选和多选	查看
InputTag	标签输入组件	查看

上传组件

组件	说明	文档
SingleImageUpload	单图上传	查看
MultiImageUpload	多图上传	查看
FileUpload	文件上传	查看
WangEditor	富文本编辑器	查看

展示组件

组件	说明	文档
ECharts	图表组件，支持柱状图、折线图、饼图	查看
TextScroll	文字滚动组件	查看
CopyButton	复制按钮组件	查看

CURD 组件

快速开发组件，帮助你快速实现增删改查功能：

组件	说明	文档
PageSearch	搜索表单组件	查看
PageContent	数据列表组件	查看
PageModal	表单弹窗组件	查看
usePage	页面逻辑组合函数	查看

布局组件

组件	说明	文档
Breadcrumb	面包屑导航	查看
Hamburger	菜单折叠按钮	查看
Fullscreen	全屏切换组件	查看
ThemeSwitch	主题切换组件	查看
SizeSelect	尺寸选择组件	查看
LangSelect	语言选择组件	查看
TenantSwitcher	租户切换组件	查看

功能组件

组件	说明	文档
CommandPalette	命令面板，快捷搜索菜单	查看
NoticeDropdown	通知下拉组件	查看
Pagination	分页组件	查看
OperationColumn	操作列组件	查看

使用方式

自动导入

项目使用 unplugin-vue-components 实现组件自动导入，无需手动注册：

<template>
  <div>
    <!-- 直接使用，无需 import -->
    <IconSelect v-model="icon" />
    <DictSelect v-model="value" code="gender" />
  </div>
</template>

<script setup lang="ts">
// 无需导入组件
const icon = ref('')
const value = ref('')
</script>

手动导入

如果需要手动导入：

<template>
  <div>
    <IconSelect v-model="icon" />
  </div>
</template>

<script setup lang="ts">
import IconSelect from '@/components/IconSelect/index.vue'

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

组件设计原则

1. 简洁易用

• 提供合理的默认值
• API 设计符合直觉
• 减少必需参数

2. 类型安全

• 完整的 TypeScript 类型定义
• Props 类型校验
• 事件类型定义

3. 可扩展性

• 支持插槽自定义
• 提供事件回调
• 支持样式覆盖

4. 性能优化

• 按需加载
• 避免不必要的重渲染
• 合理使用缓存

组件开发规范

目录结构

ComponentName/
├── index.vue           # 组件主文件
├── types.ts            # 类型定义（可选）
├── useComponent.ts     # 组合式函数（可选）
└── components/         # 子组件（可选）
    └── SubComponent.vue

命名规范

• 组件名：使用 PascalCase（如：IconSelect）
• 文件名：与组件名保持一致
• Props：使用 camelCase（如：dictCode）
• 事件：使用 kebab-case（如：update:modelValue）

Props 定义

interface Props {
  // 必需属性
  modelValue: string

  // 可选属性，提供默认值
  placeholder?: string
  disabled?: boolean
  clearable?: boolean
}

// 使用 withDefaults 设置默认值
const props = withDefaults(defineProps<Props>(), {
  placeholder: '请选择',
  disabled: false,
  clearable: true
})

事件定义

interface Emits {
  'update:modelValue': [value: string]
  'change': [value: string]
}

const emit = defineEmits<Emits>()

示例页面

所有组件都在 src/views/demo 目录下提供了完整的使用示例：

views/demo/
├── curd/               # CURD 组件示例
├── curd-single.vue     # CURD 单页示例
├── dictionary.vue      # 字典组件示例
├── dict-sync.vue       # 字典同步示例
├── drag.vue            # 拖拽示例
├── icon-select.vue     # 图标选择器示例
├── icons.vue           # 图标示例
├── internal-doc.vue    # 内嵌文档示例
├── route-param.vue     # 路由参数示例
├── vxe-table/          # VXE Table 示例
└── ...                 # 其他示例

访问示例页面：

1. 启动项目：pnpm run dev
2. 登录系统
3. 导航到「功能演示」菜单

常见问题

1. 组件没有自动导入

解决方案：

1. 检查组件路径是否在 src/components 目录下
2. 重启开发服务器
3. 检查 vite.config.ts 中的 unplugin-vue-components 配置

2. 组件类型提示不生效

解决方案：

1. 重启 VSCode
2. 检查 components.d.ts 文件是否生成
3. 确保 TypeScript 版本 >= 5.0

3. 组件样式不生效

解决方案：

1. 检查样式是否被正确导入
2. 检查样式选择器优先级
3. 使用 :deep() 穿透样式

下一步

• 查看 CURD 快速开发 学习如何快速开发增删改查功能
• 了解 Composables 学习可复用的组合式函数
• 阅读 专题 深入了解项目架构