Element Plus 完全上手：配置、组件与实例详解

随着 Vue 3 的正式发布和生态的日趋成熟，基于 Vue 3 的 UI 组件库也迎来了蓬勃发展。Element Plus 作为 Element UI 的官方 Vue 3 版本，继承了其优秀的设计和丰富的组件，并针对 Vue 3 的新特性（如 Composition API、TypeScript 支持）进行了深度优化，成为了目前 Vue 3 生态中最受欢迎的 UI 框架之一。

本文旨在提供一个 Element Plus 的全面上手指南，无论你是 Element UI 的老用户迁移，还是初次接触 Vue 3 UI 框架的新手，都能通过本文快速掌握 Element Plus 的核心用法，从环境搭建、全局配置到常用组件的深入使用，并结合实例进行巩固，助你高效地构建美观、强大的前端应用。

文章目标读者：

• 了解 Vue.js 基础（特别是 Vue 3 语法）。
• 希望在 Vue 3 项目中使用 Element Plus 的开发者。
• 从 Element UI 迁移到 Element Plus 的开发者。

本文将涵盖以下主要内容：

1. 环境准备与安装：如何在 Vue 3 项目中引入 Element Plus。
2. 基础与全局配置：包括按需引入、国际化、主题定制等。
3. 核心组件详解：深入讲解布局、表单、表格、弹窗等常用组件的使用方法、属性、事件和插槽。
4. 进阶用法与最佳实践：TypeScript 集成、自定义主题、封装业务组件等。
5. 实战演练：构建一个简单的管理界面，综合运用所学知识。

第一章：环境准备与安装

在开始使用 Element Plus 之前，确保你的开发环境满足基本要求：

• Node.js: 建议使用 LTS 版本 (>= 16.x)。
• 包管理器: npm, yarn 或 pnpm。
• Vue 3 项目: 可以使用 create-vue (官方推荐) 或 Vite/Vue CLI 创建。

1. 创建 Vue 3 项目 (以 Vite 为例)

```bash

使用 npm

npm create vue@latest my-element-plus-app -- --ts # 推荐使用 TypeScript

或者使用 yarn

yarn create vue@latest my-element-plus-app -- --ts

或者使用 pnpm

pnpm create vue@latest my-element-plus-app -- --ts

cd my-element-plus-app
npm install # 或 yarn install / pnpm install
```

按照提示选择需要的配置（例如 TypeScript, Router, Pinia 等）。

2. 安装 Element Plus

```bash
npm install element-plus --save

或者

yarn add element-plus

pnpm add element-plus

```

3. 引入 Element Plus

Element Plus 支持两种引入方式：完整引入 和 按需引入。

• 完整引入 (不推荐用于生产环境)：
  这种方式简单直接，会加载所有组件和样式，但在生产环境中可能导致打包体积过大。

  修改 src/main.ts (或 main.js):

  ```typescript
  import { createApp } from 'vue'
  import App from './App.vue'
  import ElementPlus from 'element-plus'
  import 'element-plus/dist/index.css' // 引入 Element Plus 的 CSS 文件
  // 如果需要暗黑模式，可以引入暗黑主题
  // import 'element-plus/theme-chalk/dark/css-vars.css'

  const app = createApp(App)

  app.use(ElementPlus) // 全局注册 Element Plus
  app.mount('#app')
  ```

• 按需自动引入 (强烈推荐)：
  这是生产环境的最佳实践，可以显著减小打包体积。借助 unplugin-vue-components 和 unplugin-auto-import 这两个 Vite/Webpack 插件，可以实现组件和样式的自动按需加载，无需手动 import。

  首先，安装插件：

  ```bash
  npm install -D unplugin-vue-components unplugin-auto-import

  或者

  yarn add -D unplugin-vue-components unplugin-auto-import

  pnpm add -D unplugin-vue-components unplugin-auto-import

  ```

  然后，配置 vite.config.ts (如果是 Vite 项目)：

  ```typescript
  import { defineConfig } from 'vite'
  import vue from '@vitejs/plugin-vue'
  import AutoImport from 'unplugin-auto-import/vite'
  import Components from 'unplugin-vue-components/vite'
  import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

  // https://vitejs.dev/config/
  export default defineConfig({
  plugins: [
  vue(),
  AutoImport({
  resolvers: [ElementPlusResolver()],
  // 可以自动导入 Vue 和其他库的 API
  imports: ['vue', 'vue-router'], // 根据需要添加
  dts: 'src/auto-imports.d.ts', // 生成 TypeScript 声明文件
  }),
  Components({
  resolvers: [ElementPlusResolver()],
  // 指定组件位置，默认是 src/components
  dirs: ['src/components'],
  // ui库解析器
  // resolvers: [ElementPlusResolver()],
  extensions: ['vue', 'md'],
  // 配置需要将哪些后缀类型的文件进行自动按需引入
  include: [/.vue$/, /.vue\?vue/, /.md$/],
  dts: 'src/components.d.ts', // 生成 TypeScript 声明文件
  }),
  ],
  // ... 其他配置
  })
  ```

  配置完成后，你就可以在 .vue 文件中直接使用 Element Plus 组件，无需手动 import。例如：

  ```vue
  

  
  ```

  插件会自动处理组件的导入和样式的引入。这种方式极大地提升了开发体验和应用性能。

第二章：基础与全局配置

Element Plus 提供了一些全局配置项，允许你根据项目需求进行定制。

1. 国际化 (i18n)

Element Plus 默认使用中文。如果需要支持其他语言，可以进行配置。

• 完整引入时配置：

  在 main.ts 中引入对应的语言包，并在 app.use 时传入 locale 选项。

  ```typescript
  import { createApp } from 'vue'
  import App from './App.vue'
  import ElementPlus from 'element-plus'
  import 'element-plus/dist/index.css'
  import zhCn from 'element-plus/dist/locale/zh-cn.mjs' // 中文语言包
  import en from 'element-plus/dist/locale/en.mjs' // 英文语言包

  const app = createApp(App)

  // 选择需要的语言包
  const currentLocale = zhCn // 或者 en

  app.use(ElementPlus, { locale: currentLocale })
  app.mount('#app')
  ```

• 按需引入时配置：

  可以使用 ElConfigProvider 组件在应用根部或特定区域包裹内容，并通过 locale 属性传入语言包。

  ```vue
  // App.vue 或布局组件
  

  
  ```

2. 主题定制

Element Plus 使用 CSS 变量来实现主题定制，非常灵活。

• 覆盖 CSS 变量:
  最简单的方式是在你的全局 CSS 文件（例如 src/styles/index.css 或 src/styles/element-variables.css）中覆盖 Element Plus 定义的 CSS 变量。

  ```css
  / src/styles/element-variables.css /
  :root {
  / 覆盖主题色 /
  --el-color-primary: #4a90e2;
  / 覆盖字体大小 /
  --el-font-size-base: 14px;
  / 覆盖边框圆角 /
  --el-border-radius-base: 4px;

  / 暗黑模式下的变量（需要配合切换逻辑） /
  / html.dark {
  --el-color-primary: #3a7ac2;
  } /
  }
  ```

  然后在 main.ts 中引入这个 CSS 文件：

  typescript
// src/main.ts
import './styles/element-variables.css' // 确保在 Element Plus CSS 之后或能覆盖它

• 使用 SCSS 变量 (更强大):
  如果你的项目使用 SCSS，可以通过修改 SCSS 变量文件进行更深层次的定制。需要安装 sass：

  bash
npm install -D sass

  创建一个 SCSS 文件（例如 src/styles/element/index.scss）:

  ```scss
  // src/styles/element/index.scss

  / 覆盖变量，必须在导入 Element Plus 样式之前 /
  $--colors: (
  'primary': (
  'base': #007bff, // 你期望的主题色
  ),
  //可以覆盖更多颜色变量
  );

  // 如果需要覆盖其他 SCSS 变量
  // $--font-size-base: 15px;

  / 导入 Element Plus 默认主题 /
  @forward 'element-plus/theme-chalk/src/common/var.scss' with (
  // 在这里覆盖 SCSS 变量
  $colors: $--colors,
  // $font-size: ('base': 15px) // 另一种覆盖方式
  );

  // 如果只需要重置主题色，推荐使用此方法
  // @use "element-plus/theme-chalk/src/dark/css-vars.scss" as *; // 如果需要暗黑模式

  / 导入 Element Plus 的基础样式和组件样式 /
  @use "element-plus/theme-chalk/src/index.scss" as *;
  ```

  然后在 main.ts 中导入这个 SCSS 文件，取代原来的 CSS 引入：

  typescript
// src/main.ts
// import 'element-plus/dist/index.css' // 注释掉或删除原来的 CSS 引入
import './styles/element/index.scss' // 引入自定义的 SCSS 文件

3. 全局组件配置

可以通过 ElConfigProvider 组件配置一些组件的默认行为，如按钮的 autoInsertSpace（自动在两个中文字符之间插入空格）、表单的 labelPosition、size（组件尺寸）、zIndex（弹窗层级）等。

```vue
// App.vue 或布局组件

```

4. 图标使用

Element Plus 将图标库分离为 @element-plus/icons-vue。

• 安装:

  ```bash
  npm install @element-plus/icons-vue

  or

  yarn add @element-plus/icons-vue

  pnpm add @element-plus/icons-vue

  ```

• 使用:
  可以直接在模板中作为组件使用。如果配置了 unplugin-auto-import 和 unplugin-vue-components，通常图标也会被自动导入。

  ```vue
  

  
  ```

  确保 unplugin-vue-components 的配置能解析 @element-plus/icons-vue（通常默认配置即可）。

第三章：核心组件详解

Element Plus 提供了极其丰富的组件库。这里我们挑选几个最常用的进行详细讲解。

1. Layout 布局 (el-container, el-row, el-col)

• el-container 系列: 用于构建常见的页面布局，如上/下/左/右结构。

  • el-container: 外层容器。当子元素中包含 el-header 或 el-footer 时，自动为 flex-direction: column；包含 el-aside 时，自动为 flex-direction: row。
  • el-header: 顶栏容器。
  • el-aside: 侧边栏容器。
  • el-main: 主要区域容器。
  • el-footer: 底栏容器。

  vue
<template>
<el-container style="height: 100vh;">
<el-header style="background-color: #409EFF; color: white; line-height: 60px;">Header</el-header>
<el-container>
<el-aside width="200px" style="background-color: #ecf5ff;">Aside</el-aside>
<el-main style="background-color: #f0f2f5;">Main Content Area</el-main>
</el-container>
<el-footer style="background-color: #b3c0d1; color: #333; line-height: 60px;">Footer</el-footer>
</el-container>
</template>

• el-row / el-col: 基于 Flex 布局的 24 栅格系统，用于灵活地划分水平空间。

  • el-row: 行容器，可以设置 gutter 定义列间距。
  • el-col: 列容器，通过 span (1-24) 定义宽度，offset 定义左侧偏移量，push/pull 定义左右移动，还可以设置响应式属性 ( xs, sm, md, lg, xl)。

  ```vue
  

  ```

2. Form 表单 (el-form, el-form-item, 及各类输入组件)

表单是交互的核心。Element Plus 提供了强大的表单功能，包括数据绑定、校验、布局等。

• 核心组件:

  • el-form: 表单容器。重要属性：
    • model: 表单数据对象 (使用 v-model 或 :model)。
    • rules: 表单验证规则。
    • ref: 获取表单实例，用于调用 validate, resetFields 等方法。
    • label-width: 表单域标签的宽度。
    • label-position: 标签位置 (left, right, top)。
    • size: 表单内组件尺寸。
  • el-form-item: 表单项容器。重要属性：
    • label: 标签文本。
    • prop: 对应 model 中的字段名，用于校验和重置。
  • 输入组件: el-input, el-select, el-checkbox, el-radio, el-date-picker, el-switch, el-cascader, el-slider, el-time-picker, el-upload 等。

• 示例：登录表单

  ```vue
  

  
  ```

3. Table 表格 (el-table, el-table-column)

表格是展示结构化数据的关键组件。

• 核心组件:

  • el-table: 表格容器。重要属性：
    • data: 表格数据数组。
    • border: 是否带有纵向边框。
    • stripe: 是否为斑马纹表格。
    • height/max-height: 固定表头或带滚动条。
    • row-key: 行数据的 Key，用于优化渲染和某些功能（如树形数据、展开行）。
    • 事件: select, select-all, selection-change, row-click, sort-change 等。
  • el-table-column: 表格列配置。重要属性：
    • prop: 对应 data 数组中对象的属性名。
    • label: 列头显示文本。
    • width: 列宽度。
    • fixed: 列固定 (left 或 right)。
    • sortable: 是否可排序 (custom 表示服务器端排序)。
    • formatter: 格式化单元格内容函数。
    • type: 特殊列类型 (selection, index, expand)。
    • 插槽: default (自定义单元格内容), header (自定义列头)。

• 示例：简单数据表格与分页

  ```vue
  

  
  ```

4. Feedback 反馈组件 (el-dialog, el-message, el-message-box, el-notification)

这些组件用于与用户进行交互和信息提示。

• el-dialog: 对话框。用于展示需要用户交互的信息或表单。

  • v-model: 控制对话框显示/隐藏。
  • title: 对话框标题。
  • 插槽: default (内容区), footer (底部按钮区)。

• el-message: 消息提示。在页面顶部轻量级地展示操作反馈，自动消失。

  • 用法: ElMessage('消息内容'), ElMessage.success('成功'), ElMessage.warning('警告'), ElMessage.error('错误')。
  • 可以通过对象配置更多选项：ElMessage({ message: 'Hi', type: 'success', duration: 1000 })。

• el-message-box: 消息弹框。模拟系统的 alert, confirm, prompt。

  • 用法: ElMessageBox.alert('内容', '标题', { confirmButtonText: 'OK' }), ElMessageBox.confirm('确认删除?', '提示', { type: 'warning' }).then(() => {}).catch(() => {}), ElMessageBox.prompt('请输入邮箱', '提示').then(({ value }) => {}).

• el-notification: 通知。在页面右上角（可配置）显示信息，通常用于系统级通知。

  • 用法: ElNotification({ title: '标题', message: '这是通知内容', type: 'success' })。

```vue

```

第四章：进阶用法与最佳实践

1. TypeScript 深度集成

Element Plus 本身就是用 TypeScript 编写的，提供了完善的类型定义。

• 类型推导: 在使用 <script setup lang="ts"> 时，组件的 Props、Events、Refs 都能获得良好的类型提示和检查。
  typescript
import type { FormInstance, TableInstance } from 'element-plus'
const formRef = ref<FormInstance>()
const tableRef = ref<TableInstance>()
• 事件类型: 事件处理函数的参数类型也通常能被正确推断。

2. 封装业务组件

在实际项目中，经常需要将 Element Plus 组件与业务逻辑结合，封装成可复用的业务组件。

• 目的: 统一风格、简化使用、逻辑复用。
• 示例: 封装一个基于 el-dialog 和 el-form 的标准编辑/新增弹窗。
  • 暴露 open(initialData) 方法。
  • 内部处理表单校验、数据提交。
  • 通过 emit 通知父组件操作结果。

3. 性能优化考量

• 坚持按需引入: 这是最重要的性能优化手段。
• 虚拟滚动: 对于超大数据量的表格 (el-table-v2) 或下拉框 (el-select-v2)，使用虚拟滚动版本可以显著提升性能。
• 合理使用 v-if vs v-show: 对于不常显示或初始化开销大的组件（如复杂弹窗），使用 v-if。对于频繁切换显示的，使用 v-show。
• 避免不必要的渲染: 使用 computed 缓存计算结果，优化 watch 的使用。

4. 无障碍访问 (Accessibility - a11y)

Element Plus 遵循 WAI-ARIA 标准，努力提高组件的可访问性。开发者在使用时也应注意：

• 为表单元素提供明确的 label。
• 确保图标按钮等有可访问的文本描述 (如 aria-label)。
• 注意键盘导航和焦点管理。

第五章：实战演练：构建简单用户管理列表

让我们结合前面的知识，构建一个简单的用户管理页面，包含列表展示、新增、编辑和删除功能。

页面结构:

• 顶部：一个“新增用户”按钮。
• 中部：el-table 展示用户列表，包含姓名、邮箱、创建日期和操作列（编辑、删除）。
• 底部：el-pagination 处理分页。
• 弹窗：一个 el-dialog 包含 el-form，用于新增或编辑用户信息。

核心逻辑:

1. 数据管理: 使用 ref 或 reactive 存储用户列表、分页信息、弹窗状态、当前编辑的用户数据。
2. API 交互 (模拟): 编写 fetchUsers, addUser, updateUser, deleteUser 函数模拟后端交互。
3. 表格操作:
   • 点击“编辑”按钮：打开弹窗，并将当前行数据填充到表单中。
   • 点击“删除”按钮：弹出 ElMessageBox.confirm，确认后调用删除接口并刷新列表。
4. 弹窗表单:
   • 区分新增/编辑状态（例如通过弹窗标题或一个标志位）。
   • 提交时，调用 formRef.value.validate() 进行校验。
   • 校验通过后，根据状态调用新增或编辑接口。
   • 成功后关闭弹窗，刷新列表，并显示 ElMessage 提示。
5. 分页: 监听 @size-change 和 @current-change 事件，更新分页参数并重新获取数据。

(由于篇幅限制，此处不提供完整的代码实现，但上述逻辑和前面章节的示例代码足以构成这个实战案例的核心框架。开发者可以基于这些思路和组件用法自行组合实现。)

总结

Element Plus 作为 Vue 3 生态下的旗舰级 UI 组件库，凭借其全面的组件、优秀的设计、强大的功能以及对 Vue 3 新特性的完美支持（特别是 TypeScript 和按需引入），极大地提升了开发者的效率和应用质量。

通过本文的详细介绍，我们从安装配置开始，了解了国际化、主题定制等全局设置，深入探讨了布局、表单、表格、反馈等核心组件的使用方法和技巧，并提及了 TypeScript 集成、组件封装等进阶话题和最佳实践。

掌握 Element Plus 不仅仅是学会使用几个组件，更重要的是理解其设计理念和配置方式，并能结合项目实际需求灵活运用。希望这篇详尽的上手指南能为你学习和使用 Element Plus 提供坚实的基础和清晰的路径。现在，就动手在你的 Vue 3 项目中实践 Element Plus 吧！不断查阅官方文档，参与社区交流，你的 Element Plus 技能将会更加精进。