组件总览

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

组件分类

基础组件

组件	说明	文档
IconSelect	图标选择器，支持搜索和分页	查看
DictSelect	字典选择器，基于 Element Plus Select 封装	查看
Upload	文件上传组件，支持图片、文件上传	查看
WangEditor	富文本编辑器，基于 WangEditor 封装	查看
InputTag	标签输入组件	查看
TextScroll	文字滚动组件	查看

表格组件

组件	说明	文档
TableSelect	表格选择器，支持单选和多选	查看
Pagination	分页组件，基于 Element Plus Pagination 封装	查看
OperationColumn	操作列组件，自动生成表格操作按钮	查看

CURD 组件

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

组件	说明	文档
CURD	CURD 快速开发方案	查看
PageSearch	搜索组件	查看
PageContent	内容组件	查看
PageModal	弹窗组件	查看

功能组件

组件	说明	文档
ECharts	图表组件，基于 ECharts 封装	查看
CopyButton	复制按钮组件	查看
AiAssistant	AI 助手组件	查看
MenuSearch	菜单搜索组件	查看
Notification	通知组件	查看

布局组件

组件	说明	文档
Breadcrumb	面包屑导航	查看
Hamburger	菜单折叠按钮	查看
Fullscreen	全屏切换组件	查看
DarkModeSwitch	暗黑模式切换	查看
SizeSelect	尺寸选择组件	查看
LangSelect	语言选择组件	查看

使用方式

自动导入

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

<template>
  <div>
    <!-- 直接使用，无需 import -->
    <IconSelect v-model="icon" />
    <DictSelect v-model="value" dict-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            # 类型定义
├── hooks/              # 组合式函数（可选）
│   └── 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>()

类型导出

// types.ts
export interface IconSelectProps {
  modelValue: string
  placeholder?: string
}

export interface IconSelectEmits {
  'update:modelValue': [value: string]
}

// 在组件中使用
import type { IconSelectProps, IconSelectEmits } from './types'

示例页面

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

views/demo/
├── icon-select.vue     # 图标选择器示例
├── dictionary.vue      # 字典组件示例
├── upload.vue          # 上传组件示例
├── wang-editor.vue     # 富文本编辑器示例
├── curd/               # CURD 组件示例
└── ...                 # 其他示例

访问示例页面：

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() 穿透样式

贡献组件

欢迎贡献新的组件！在提交 PR 之前，请确保：

1. 组件通用性：组件应该具有通用性，而不是针对特定业务
2. 文档完善：提供完整的使用文档和示例
3. 类型定义：提供完整的 TypeScript 类型定义
4. 测试覆盖：编写单元测试
5. 代码规范：符合项目的代码规范

下一步

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