Element-Plus-Vue3-Getting-Started

字数统计: 4k阅读时长: 18 min

 2026/07/29 

第37课：Element Plus (Vue 3) 入门——安装、按需引入、全局配置、主题定制

Element Plus 是 Vue 3 生态中最主流的企业级 UI 组件库，基于 TypeScript 编写，提供了超过 80 个高质量组件。对于从 Vue 2 + Element UI 迁移的开发者，Element Plus 保持了相似的 API 设计，同时深度整合了 Vue 3 的 Composition API。本节课将覆盖 Element Plus 的三种安装与引入方式、全局配置机制、以及主题定制的两种策略（CSS 变量和 SCSS 变量），帮助你为 Vue 3 项目构建一致、高效的 UI 基础。

1. 安装 Element Plus

Element Plus 支持包管理器和 CDN 两种安装方式。对于生产项目，推荐使用包管理器以获得 Tree Shaking 和按需加载的优势。

1.1 通过 npm / pnpm 安装

# npm
npm install element-plus

# pnpm（推荐，安装更快、磁盘占用更少）
pnpm add element-plus

# yarn
yarn add element-plus

1.2 通过 CDN 引入（仅适合原型和快速演示）

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Element Plus CDN 示例</title>
  <!-- 引入样式 -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/element-plus/dist/index.css">
  <!-- 引入 Vue 3 -->
  <script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js"></script>
  <!-- 引入 Element Plus -->
  <script src="https://cdn.jsdelivr.net/npm/element-plus"></script>
</head>
<body>
  <div id="app">
    <el-button type="primary" @click="handleClick">点击我</el-button>
    <el-message v-model:visible="visible">这是一条消息</el-message>
  </div>
  <script>
    const { createApp, ref } = Vue;
    createApp({
      setup() {
        const visible = ref(false);
        const handleClick = () => {
          ElementPlus.ElMessage.success('操作成功！');
        };
        return { visible, handleClick };
      }
    }).use(ElementPlus).mount('#app');
  </script>
</body>
</html>

注意：CDN 方式会全量引入 Element Plus，无法 Tree Shaking，打包体积较大，不应用于生产环境。

2. 引入方式：全量引入 vs 按需引入

2.1 全量引入（最简单，适合小型项目）

在入口文件 main.ts 中一次性注册所有组件：

// 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')

优点：配置简单，所有组件立即可用，无需关心导入。
缺点：打包体积大（约 1.5MB gzipped 后约 200KB），无法 Tree Shaking 未使用的组件。

2.2 手动按需引入（中等复杂，体积最优）

只引入你实际使用的组件和它们的样式：

// main.ts
import { createApp } from 'vue'
import { ElButton, ElInput, ElTable, ElTableColumn } from 'element-plus'
import 'element-plus/es/components/button/style/css'
import 'element-plus/es/components/input/style/css'
import 'element-plus/es/components/table/style/css'
import 'element-plus/es/components/table-column/style/css'
import App from './App.vue'

const app = createApp(App)
app.component('ElButton', ElButton)
app.component('ElInput', ElInput)
app.component('ElTable', ElTable)
app.component('ElTableColumn', ElTableColumn)
app.mount('#app')

优点：打包体积最小，仅包含使用到的组件。
缺点：每个组件需手动导入组件和样式，非常繁琐，组件多时维护困难。

2.3 自动按需引入（推荐方案）

使用 unplugin-vue-components 和 unplugin-auto-import 插件，自动分析模板中使用的组件并按需导入，无需任何手动导入。

安装插件：

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

配置 Vite（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()],
    }),
  ],
})

配置完成后，你可以在 .vue 文件中直接使用 Element Plus 组件，无需任何显式导入：

<template>
  <el-button type="primary" @click="handleClick">提交</el-button>
  <el-input v-model="username" placeholder="请输入用户名" />
</template>

<script setup>
import { ref } from 'vue'
const username = ref('')
const handleClick = () => {
  ElMessage.success(`欢迎，${username.value}！`)
}
</script>

工作原理：

unplugin-vue-components 扫描模板中使用的 <el-*> 标签，自动生成按需导入语句。
unplugin-auto-import 扫描 Composition API 调用（如 ElMessage），自动导入对应的 API。
样式也会按需加载，无需手动引入任何 CSS 文件。

注意：首次启动时插件需要扫描和解析依赖，编译速度会略慢，但生产构建和 HMR 性能几乎无影响。

3. 全局配置：统一组件的默认行为

Element Plus 提供了全局配置机制，允许你在应用级别修改所有组件的默认属性。

3.1 通过 `el-config-provider` 组件配置

在根组件中使用 <el-config-provider> 包裹应用，设置全局属性：

<!-- App.vue -->
<template>
  <el-config-provider :size="size" :locale="locale" :button="{ autoInsertSpace: true }">
    <router-view />
  </el-config-provider>
</template>

<script setup>
import { reactive } from 'vue'
import zhCn from 'element-plus/es/locale/lang/zh-cn'

const size = 'default' // 'large' | 'default' | 'small'
const locale = zhCn
</script>

可配置的全局属性：

配置项	类型	说明	默认值
`size`	string	全局组件尺寸：`'large'`、`'default'`、`'small'`	`'default'`
`locale`	object	国际化语言包，Element Plus 提供了 50+ 语言	英语
`zIndex`	number	全局弹窗的初始 `z-index`，后续弹窗递增 1	`2000`
`button`	object	按钮全局配置，如 `{ autoInsertSpace: true }`（中文自动加空格）	`{}`
`message`	object	`ElMessage` 的全局配置，如 `{ max: 3 }`（最多显示 3 条）	`{}`

3.2 国际化配置

Element Plus 内置了 50+ 种语言包。切换语言只需替换 locale 对象：

import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'

// 在 el-config-provider 中动态切换
const locale = ref(zhCn)

日期相关的组件（el-date-picker、el-time-picker）依赖 dayjs，如需国际化日期需额外配置：

1
2
3

import 'dayjs/locale/zh-cn'
import dayjs from 'dayjs'
dayjs.locale('zh-cn')

3.3 通过应用实例全局配置

你也可以在创建 Vue 应用时传入全局配置：

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, {
  size: 'small',
  zIndex: 3000,
})
app.mount('#app')

4. 主题定制：打造品牌专属的视觉风格

Element Plus 使用 CSS 变量（自定义属性）作为其设计令牌系统。通过覆盖这些变量，你可以系统性地修改主题色、圆角、边框等全局样式，无需修改组件源码或写大量覆盖 CSS。

4.1 通过 CSS 变量覆盖（推荐，无需构建工具）

Element Plus 的所有颜色、圆角、阴影等视觉参数都通过 CSS 变量定义在 :root 上。你只需在全局样式文件中覆盖这些变量即可定制主题。

/* styles/theme.css */
:root {
  /* 主色 */
  --el-color-primary: #4f46e5;
  --el-color-primary-light-3: #818cf8;
  --el-color-primary-light-5: #a5b4fc;
  --el-color-primary-light-7: #c7d2fe;
  --el-color-primary-light-8: #e0e7ff;
  --el-color-primary-light-9: #eef2ff;
  --el-color-primary-dark-2: #3730a3;

  /* 成功色 */
  --el-color-success: #059669;

  /* 警告色 */
  --el-color-warning: #d97706;

  /* 危险色 */
  --el-color-danger: #dc2626;

  /* 信息色 */
  --el-color-info: #6b7280;

  /* 字体 */
  --el-font-family: 'Inter', system-ui, -apple-system, sans-serif;

  /* 圆角 */
  --el-border-radius-base: 0.375rem;
  --el-border-radius-small: 0.25rem;
  --el-border-radius-round: 9999px;

  /* 边框 */
  --el-border-color-base: #d1d5db;
  --el-border-color-light: #e5e7eb;
}

覆盖主色时的重要规则：--el-color-primary 是基础主色，Element Plus 会自动生成 9 级渐变色（primary-light-1 到 primary-light-9 以及 primary-dark-1）。但自动生成的渐变色可能与你的设计预期不符。为了精确控制，你可以手动覆盖 light-3、light-5、light-7、light-8、light-9 和 dark-2 这些关键变量（Element Plus 主要使用这几个）。其他渐变值（如 light-1、light-2 等）由算法生成，通常不需手动覆盖。

如何得到精确的渐变色值：可以使用 Element Plus 官方提供的主题编辑器在线生成 9 级调色板，然后将生成的 CSS 变量粘贴到你的项目中。

引入主题文件：在 main.ts 中引入主题样式，确保它在 Element Plus 默认样式之后加载：

1
2
3

// main.ts
import 'element-plus/dist/index.css'
import './styles/theme.css' // 你的自定义主题变量，必须在 element-plus 之后

4.2 通过 SCSS 变量覆盖（需要构建工具，更深层定制）

如果你需要修改 Element Plus 组件的内部结构样式（如修改表格行的 hover 背景色、对话框头部的内边距等），仅靠 CSS 变量可能不够。此时需要覆盖 Element Plus 的 SCSS 变量。

1	pnpm add -D sass

在 Vite 中配置 SCSS 的 additionalData，注入变量覆盖：

// vite.config.ts
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `
          @use '~/styles/element-variables.scss' as *;
        `,
      },
    },
  },
})

**styles/element-variables.scss**：

// 覆盖 Element Plus 的 SCSS 变量（必须在导入 Element Plus 样式前）
$colors: (
  'primary': (
    'base': #4f46e5,
  ),
  'success': (
    'base': #059669,
  ),
);

// 生成完整的 CSS 变量和类名
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: $colors,
  $button-padding-horizontal: ('default': 24px),
  $table-row-hover-bg-color: #f0f5ff,
);

注意：SCSS 变量覆盖需要较深的 Element Plus 源码知识，且 Element Plus 升级时变量名可能变化。优先使用 CSS 变量方案，仅在必要时使用 SCSS 覆盖。

4.3 暗色模式

Element Plus 内置了暗色模式支持，通过给 <html> 添加 dark 类即可切换：

1	<html class="dark">

配合 CSS 变量的暗色覆盖：

html.dark {
  --el-bg-color: #1a1a2e;
  --el-bg-color-overlay: #16213e;
  --el-text-color-primary: #e4e4e4;
  --el-text-color-regular: #d1d5db;
  --el-border-color-base: #374151;
  --el-border-color-light: #4b5563;
}

Element Plus 组件内部的暗色切换会自动响应 html.dark 状态，你只需确保根元素正确设置该类。

5. 综合实战：创建一个定制主题的 Vue 3 + Element Plus 应用

# 初始化项目（使用 Vite）
pnpm create vite my-element-app --template vue-ts
cd my-element-app
pnpm add element-plus
pnpm add -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()] }),
  ],
})

**src/styles/theme.css**：

:root {
  --el-color-primary: #4f46e5;
  --el-color-primary-light-3: #818cf8;
  --el-color-primary-light-5: #a5b4fc;
  --el-color-primary-light-7: #c7d2fe;
  --el-color-primary-light-8: #e0e7ff;
  --el-color-primary-light-9: #eef2ff;
  --el-color-primary-dark-2: #3730a3;
  --el-color-success: #059669;
  --el-color-danger: #dc2626;
  --el-font-family: 'Segoe UI', system-ui, sans-serif;
  --el-border-radius-base: 0.5rem;
}

**src/main.ts**：

import { createApp } from 'vue'
import App from './App.vue'
import 'element-plus/dist/index.css'
import './styles/theme.css'

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

**src/App.vue**：

<template>
  <el-config-provider :locale="zhCn" size="default">
    <div class="app-container">
      <h1 class="app-title">Element Plus 主题定制示例</h1>
      <div class="button-group">
        <el-button type="primary">主要按钮</el-button>
        <el-button type="success">成功按钮</el-button>
        <el-button type="danger">危险按钮</el-button>
      </div>
      <el-card class="info-card">
        <template #header>系统状态</template>
        <p>所有组件已自动按需引入。</p>
        <p>主题色已通过 CSS 变量定制。</p>
      </el-card>
    </div>
  </el-config-provider>
</template>

<script setup>
import zhCn from 'element-plus/es/locale/lang/zh-cn'
</script>

<style>
.app-container {
  max-width: 600px;
  margin: 40px auto;
  padding: 0 20px;
}
.app-title {
  font-size: 1.5rem;
  margin-bottom: 24px;
  color: var(--el-text-color-primary);
}
.button-group {
  display: flex;
  gap: 12px;
  margin-bottom: 24px;
}
</style>

运行效果：

按钮的颜色、圆角、字体均使用定制后的主题变量。
所有 Element Plus 组件（包括消息提示、对话框等）会自动应用统一的主题色。
无需手动导入任何组件，按需引入插件自动处理。

课后练习

一、概念自测（选择题 / 填空题）

（单选） Element Plus 推荐的按需引入方式是什么？
A. 手动逐组件导入并手动引入样式。
B. 全量引入 ElementPlus 并使用 app.use()。
C. 使用 unplugin-vue-components 和 unplugin-auto-import 自动按需引入。
D. 通过 CDN 引入。
（单选） Element Plus 主题定制的首选方案是什么？
A. 覆盖 Element Plus 的 SCSS 变量。
B. 覆盖 Element Plus 的 CSS 变量（--el-*）。
C. 修改 Element Plus 源码。
D. 给每个组件单独写内联样式覆盖。
（填空） 在 Element Plus 中，要设置全局组件的尺寸（如按钮、输入框等统一为 small），应使用 ______ 组件包裹应用，并传入 size 属性。
（多选） 以下哪些是 el-config-provider 可配置的属性？
A. size
B. locale
C. zIndex
D. theme

二、AI 编程任务：编写面向 AI 的提示词

场景：你正在初始化一个 Vue 3 + TypeScript + Element Plus 的管理后台项目。要求如下：

使用 Vite 作为构建工具。
使用 unplugin-vue-components 和 unplugin-auto-import 实现 Element Plus 的自动按需引入。
使用 CSS 变量定制主题：主色改为 #059669（翠绿色），全局圆角改为 0.25rem，字体改为 'Inter', system-ui。
使用 el-config-provider 配置中文语言包，默认组件尺寸为 small。
页面展示一个简单的登录表单：用户名输入框、密码输入框、一个”记住我”复选框、一个登录按钮（全宽，主色）。
点击登录按钮使用 ElMessage 弹出”登录成功”的提示。

任务要求：请写出一段完整的中文提示词，发送给 AI，使其生成完整的项目文件（vite.config.ts、main.ts、theme.css、App.vue 等）。提示词中需明确指定 Vite 配置插件的方式、CSS 变量覆盖的具体值、表单布局和交互行为。

课后练习答案

一、概念自测答案

C
- 解析：unplugin-vue-components + unplugin-auto-import 是官方推荐的自动按需引入方案，无需手动导入组件和样式。
B
- 解析：Element Plus 使用 CSS 变量作为设计令牌，覆盖 --el-* 变量是官方推荐的首选主题定制方案，无需构建工具。
el-config-provider
- 解析：<el-config-provider> 是 Element Plus 提供的全局配置组件，size 属性可统一设置所有子组件的尺寸。
A、B、C
- 解析：size（组件尺寸）、locale（国际化语言）、zIndex（弹窗层级）均可通过 el-config-provider 配置。D 错误，主题变更应通过 CSS 变量或 SCSS 变量实现，不是 el-config-provider 的直接属性。

二、AI 编程任务参考答案（提示词示例）

示例提示词：
“请生成一个 Vue 3 + TypeScript + Vite + Element Plus 的登录页面项目。要求：

vite.config.ts 中配置 unplugin-vue-components 和 unplugin-auto-import，resolver 使用 ElementPlusResolver。

main.ts 引入 Element Plus 样式和一个自定义主题 CSS 文件。

自定义主题 theme.css：覆盖 --el-color-primary: #059669;、--el-color-primary-light-3/5/7/8/9 和 --el-color-primary-dark-2 的绿色系值；--el-border-radius-base: 0.25rem;；--el-font-family: 'Inter', system-ui, sans-serif;。

App.vue 使用 <el-config-provider :locale="zhCn" size="small"> 包裹，zhCn 从 element-plus/es/locale/lang/zh-cn 导入。

页面包含一个居中的登录卡片（使用 el-card），内有一个 el-form：

用户名 el-input（placeholder ‘请输入用户名’，prefix-icon 使用 User 图标）。

密码 el-input（type ‘password’，placeholder ‘请输入密码’，prefix-icon 使用 Lock 图标，show-password）。

el-checkbox ‘记住我’。

el-button type ‘primary’，class ‘w-full’，文字 ‘登录’，点击时调用 ElMessage.success('登录成功！')（ElMessage 已通过 auto-import 自动可用）。

页面整体背景色 #f5f5f5，卡片居中（使用 flex 或 grid 布局）。

直接输出所有文件的完整内容。”

原文作者：WinddSnow

原文链接：https://winddsnow.github.io/2026/07/29/Element-Plus-Vue3/

发表日期：July 29th 2026, 7:00:00 am

更新日期：July 28th 2026, 10:27:15 am

Next Post

Element-Plus-Core-Components-Table-Form-Dialog-Message-Upload
Previous Post

Tailwind-CSS-Component-Patterns-and-Framework-Integration

CATALOG

1. 第37课：Element Plus (Vue 3) 入门——安装、按需引入、全局配置、主题定制