Element Plus

基础概念

Element Plus 是饿了么团队开发的 Vue 3 UI 组件库，是 Element UI（Vue 2 版本）的升级替代品。

与 Element UI 的主要区别

对比项	Element UI	Element Plus
Vue 版本	Vue 2	Vue 3
包名	element-ui	element-plus
按需导入	需要 babel-plugin	使用 unplugin-vue-components（更简单）
类型支持	无	完整 TypeScript 类型
CSS 变量	不支持	支持 CSS Variables 主题
Composition API	不支持	完全支持

使用指南

安装

npm install element-plus
# 或
pnpm add element-plus

全量引入（快速开发）

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')

按需导入（推荐，减小包体积）

使用 unplugin-vue-components 和 unplugin-auto-import：

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

// vite.config.ts
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'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
})

配置后可以直接在模板中使用组件，无需手动 import：

<template>
  <el-button type="primary">按钮</el-button>
  <el-input v-model="value" placeholder="请输入" />
</template>

主题定制

CSS 变量覆盖（推荐）

/* styles/element-overrides.css */
:root {
  --el-color-primary: #409eff;
  --el-color-success: #67c23a;
  --el-border-radius-base: 4px;
  --el-font-size-base: 14px;
}

SCSS 变量覆盖

// styles/element-variables.scss
@forward "element-plus/theme-chalk/src/common/var.scss" with (
  $colors: (
    "primary": (
      "base": #409eff,
    ),
  ),
);

// main.ts
import './styles/element-variables.scss'
import 'element-plus/dist/index.css'

常用组件模式

表单验证

<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="100px">
    <el-form-item label="用户名" prop="username">
      <el-input v-model="form.username" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(formRef)">提交</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import type { FormInstance, FormRules } from 'element-plus'

const formRef = ref<FormInstance>()
const form = reactive({ username: '' })
const rules: FormRules = {
  username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
}

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid) => {
    if (valid) console.log('提交成功')
  })
}
</script>

表格与分页

<template>
  <el-table :data="tableData" stripe>
    <el-table-column prop="name" label="名称" />
    <el-table-column prop="date" label="日期" />
    <el-table-column label="操作">
      <template #default="{ row }">
        <el-button size="small" @click="handleEdit(row)">编辑</el-button>
      </template>
    </el-table-column>
  </el-table>
  <el-pagination
    v-model:current-page="currentPage"
    :page-size="10"
    :total="total"
    layout="total, prev, pager, next"
    @current-change="handlePageChange"
  />
</template>

Table 组件

element-table-merge-cells-guide

实战经验

• el-dialog 打开时默认会 focus 第一个可聚焦元素，可能导致意外行为，可用 :destroy-on-close="true" 避免
• el-select 远程搜索时注意防抖，避免频繁请求
• 大量表格数据考虑使用虚拟滚动（el-table-v2）
• el-form 的 resetFields() 会重置为初始值，不是清空

经验总结

• 新项目推荐按需导入，显著减小打包体积
• 主题定制优先用 CSS 变量方案，维护成本最低
• Element Plus 的 TypeScript 支持很好，善用类型提示提高开发效率

信息参考

• Element Plus 官方文档
• GitHub 仓库

Related notes

• Vue MOC