Element Plus

[!info] related notes

• 所属 MOC: Element Plus MOC, Vue MOC
• 表格实践: element-table-merge-cells-guide

基础概念

Element Plus 是面向 Vue 3 的 UI 组件库，延续 Element 的组件设计。Element UI 面向 Vue 2，包名和 API 有差异，不能只替换依赖名就假定迁移完成。

与 Element UI 的主要区别

对比项	Element UI	Element Plus
Vue 版本	Vue 2	Vue 3
包名	element-ui	element-plus
按需导入	常见 babel-plugin-import，也可手动配置	可手动导入或使用 unplugin resolvers
类型支持	有 TypeScript 声明文件	提供 Vue 3 / TypeScript 类型
主题定制	主要使用 theme-chalk 的 Sass 变量	支持 CSS Variables 与 Sass 主题
组件运行时	Vue 2	Vue 3；可与 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：

<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
</script>

<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;
}

CSS 覆盖文件应在默认 CSS 之后加载；仅修改 —el-color-primary 不会自动重算全部 light/dark 派生变量，需要完整主题时一起处理。

SCSS 变量覆盖（全量样式方案）

构建项目需有 Sass 编译器，例如 npm install -D sass。此方案替换预编译 CSS；按需 Sass 方案另需 resolver 的 importStyle 与 additionalData 配置，见官方主题文档。

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

// main.ts
import './styles/element-variables.scss'
// 此方案不要再导入 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 { reactive, ref } from 'vue'
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>

表格与分页

以下仅为模板片段；tableData/currentPage/total 与两个处理函数需由页面定义。分页组件不会自动切分数据或请求后端。

<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

实战经验

• destroy-on-close 控制 Dialog 关闭时销毁内容，不会禁用打开时自动聚焦；焦点策略应按所用版本的公开 API 与键盘交互要求验证
• el-select 远程搜索时注意防抖，避免频繁请求
• 大量表格数据考虑使用虚拟滚动（el-table-v2）
• el-form 的 resetFields() 会重置为初始值，不是清空

经验总结

• 按需导入有助于减少未使用组件代码，实际效果取决于样式导入与构建结果
• 运行时切换可用 CSS 变量；需要重算完整派生色时可使用 Sass 主题构建
• Element Plus 的 TypeScript 支持很好，善用类型提示提高开发效率

信息参考

• Element Plus 官方文档
• GitHub 仓库
• 主题定制
• Dialog API