Element Plus 基础组件完全指南（12个核心组件）

yume_sibai2026-08-11 15:34

摘要：本文详细介绍 Element Plus 组件库中的 12 个基础组件，包含 Button、Icon、Layout 等高频使用组件。每个组件提供完整代码示例、核心 API 表格、实战场景及常见问题解答，帮助开发者快速上手并掌握最佳实践。

关键词：Vue3、Element Plus、UI组件库、基础组件、前端开发

适合人群：Vue3 初学者、Element Plus 入门开发者

阅读时间：约 15 分钟

📖 目录导航

  • [1. Button 按钮](#1. Button 按钮)
  • [2. Icon 图标](#2. Icon 图标)
  • [3. Link 链接](#3. Link 链接)
  • [4. Text 文本](#4. Text 文本)
  • [5. Container 布局容器](#5. Container 布局容器)
  • [6. Layout 布局](#6. Layout 布局)
  • [7. Border 边框](#7. Border 边框)
  • [8. Color 颜色](#8. Color 颜色)
  • [9. Scrollbar 滚动条](#9. Scrollbar 滚动条)
  • [10. Space 间距](#10. Space 间距)
  • [11. Typography 排版](#11. Typography 排版)
  • [12. ConfigProvider 全局配置](#12. ConfigProvider 全局配置)
  • [💡 综合实战案例](#💡 综合实战案例)
  • [❓ 常见问题 FAQ](#❓ 常见问题 FAQ)
  • [📝 总结](#📝 总结)

1. Button 按钮

1.1 组件简介

Button 是用户交互中最基础的组件，用于触发操作、提交表单、打开对话框等场景。Element Plus 的 Button 组件支持多种类型、尺寸、状态，并能与图标无缝配合。

1.2 基础用法

Element Plus 提供 6 种按钮类型，通过 type 属性切换：

vue 复制代码 
<template>
  <el-button>默认按钮</el-button>
  <el-button type="primary">主要按钮</el-button>
  <el-button type="success">成功按钮</el-button>
  <el-button type="info">信息按钮</el-button>
  <el-button type="warning">警告按钮</el-button>
  <el-button type="danger">危险按钮</el-button>
</template>

效果说明：

  • 默认：灰色背景，适用于次要操作
  • primary：蓝色背景，适用于主要操作（如提交、确认）
  • success：绿色背景，适用于成功状态操作
  • warning：橙色背景，适用于警告操作
  • danger：红色背景，适用于删除等危险操作

1.3 常用场景

场景一：带图标按钮

图标能增强按钮的语义表达，提升用户体验：

vue 复制代码 
<script setup lang="ts">
import { Search, Edit, Delete, Plus } from '@element-plus/icons-vue'
</script>

<template>
  <!-- 文字+图标 -->
  <el-button type="primary" :icon="Search">搜索</el-button>
  <el-button type="success" :icon="Plus">新增</el-button>
  
  <!-- 纯图标圆形按钮 -->
  <el-button type="primary" :icon="Edit" circle />
  <el-button type="danger" :icon="Delete" circle />
</template>
场景二：按钮状态
vue 复制代码 
<template>
  <!-- 禁用状态 -->
  <el-button disabled>禁用按钮</el-button>
  
  <!-- 加载状态 -->
  <el-button type="primary" loading>加载中...</el-button>
  
  <!-- 朴素按钮（白底+边框） -->
  <el-button type="primary" plain>朴素按钮</el-button>
  
  <!-- 圆角按钮 -->
  <el-button type="success" round>圆角按钮</el-button>
</template>
场景三：按钮组

将相关操作组合在一起，保持视觉统一：

vue 复制代码 
<script setup lang="ts">
import { ArrowLeft, ArrowRight } from '@element-plus/icons-vue'
</script>

<template>
  <el-button-group>
    <el-button type="primary" :icon="ArrowLeft">上一页</el-button>
    <el-button type="primary">
      下一页
      <el-icon class="el-icon--right"><ArrowRight /></el-icon>
    </el-button>
  </el-button-group>
</template>
场景四：不同尺寸
vue 复制代码 
<template>
  <el-button size="large" type="primary">大号按钮</el-button>
  <el-button size="default" type="primary">默认按钮</el-button>
  <el-button size="small" type="primary">小型按钮</el-button>
</template>

1.4 核心 API

属性
属性名 说明 类型 可选值 默认值
type 按钮类型 string primary / success / warning / danger / info ''
size 按钮尺寸 string large / default / small default
plain 是否为朴素按钮 boolean - false
round 是否为圆角按钮 boolean - false
circle 是否为圆形按钮 boolean - false
disabled 是否禁用 boolean - false
loading 是否加载中 boolean - false
loading-icon 自定义加载图标 Component - Loading
icon 图标组件 Component - -
link 是否为链接按钮 boolean - false
autofocus 是否默认聚焦 boolean - false
native-type 原生 type 属性 string button / submit / reset button
事件
事件名 说明 回调参数
click 点击按钮时触发 (event: MouseEvent)

1.5 注意事项

  1. 圆形按钮 circle 通常与 icon 配合使用，单独使用会显示为椭圆
  2. 加载状态 会自动禁用按钮，防止重复提交
  3. link 类型 按钮无背景色，适合内联操作或表格中的操作列
  4. 按钮组 el-button-group 内的按钮会自动去除中间圆角

2. Icon 图标

2.1 组件简介

Element Plus 提供了一套基于 SVG 的图标库 @element-plus/icons-vue，包含 200+ 常用图标，支持按需引入、自定义颜色和尺寸。

2.2 安装与引入

bash 复制代码 
npm install @element-plus/icons-vue
vue 复制代码 
<script setup lang="ts">
// 按需引入（推荐）
import { Edit, Share, Delete, Search } from '@element-plus/icons-vue'
</script>

2.3 基础用法

vue 复制代码 
<template>
  <el-icon><Edit /></el-icon>
  <el-icon color="#409eff"><Share /></el-icon>
  <el-icon :size="20"><Delete /></el-icon>
  <el-icon :size="30" color="#e6a23c"><Search /></el-icon>
</template>

2.4 常用场景

场景一：与按钮配合
vue 复制代码 
<script setup lang="ts">
import { Search, Download, Upload } from '@element-plus/icons-vue'
</script>

<template>
  <el-button type="primary" :icon="Search">搜索</el-button>
  <el-button type="success" :icon="Download">下载</el-button>
  <el-button type="warning" :icon="Upload">上传</el-button>
</template>
场景二：自定义图标尺寸和颜色
vue 复制代码 
<template>
  <el-icon :size="40" color="#409eff">
    <Search />
  </el-icon>
</template>

2.5 核心 API

属性名 说明 类型 默认值
color 图标颜色 string inherit
size 图标尺寸（px） number / string -

2.6 注意事项

  1. 图标包需要单独安装 ：npm install @element-plus/icons-vue
  2. 推荐按需引入，可有效减小打包体积
  3. 完整图标列表见 官方图标页面
  4. SVG 图标支持通过 CSS color 属性修改颜色

3.1 组件简介

Link 是文字超链接组件，支持多种主题类型、下划线控制和禁用状态，比原生 <a> 标签更灵活。

3.2 基础用法

vue 复制代码 
<template>
  <el-link href="https://example.com" target="_blank">默认链接</el-link>
  <el-link type="primary">主要链接</el-link>
  <el-link type="success">成功链接</el-link>
  <el-link type="warning">警告链接</el-link>
  <el-link type="danger">危险链接</el-link>
  <el-link type="info">信息链接</el-link>
</template>

3.3 常用场景

场景一：下划线控制
vue 复制代码 
<template>
  <el-link :underline="true">显示下划线</el-link>
  <el-link :underline="false">隐藏下划线</el-link>
</template>
场景二：禁用状态
vue 复制代码 
<template>
  <el-link disabled>禁用链接</el-link>
</template>
场景三：带图标链接
vue 复制代码 
<script setup lang="ts">
import { Link } from '@element-plus/icons-vue'
</script>

<template>
  <el-link type="primary" :icon="Link">外部链接</el-link>
</template>

3.4 核心 API

属性名 说明 类型 可选值 默认值
type 链接类型 string primary / success / warning / danger / info default
underline 是否显示下划线 boolean - true
disabled 是否禁用 boolean - false
href 链接地址 string - -
icon 图标组件 Component - -
target 原生 target 属性 string - -

3.5 注意事项

  1. 默认带下划线 ，可通过 :underline="false" 隐藏
  2. 禁用状态下不可点击且无 hover 效果
  3. 需要跳转外部链接时，务必设置 target="_blank"

4. Text 文本

4.1 组件简介

Text 组件用于文本展示，支持类型化样式、尺寸控制和溢出省略，适合列表项、描述信息等场景。

4.2 基础用法

vue 复制代码 
<template>
  <el-text>这是一段普通文本</el-text>
  <el-text type="primary">主要文本</el-text>
  <el-text type="success">成功文本</el-text>
  <el-text type="warning">警告文本</el-text>
  <el-text type="danger">危险文本</el-text>
</template>

4.3 常用场景

场景一：溢出省略

当文本内容过长时，自动显示省略号：

vue 复制代码 
<template>
  <div style="width: 200px;">
    <el-text truncated>这是一段很长的文本，超出部分会被省略号代替</el-text>
  </div>
</template>

注意 ：truncated 需要父容器有固定宽度才能生效。

场景二：不同尺寸
vue 复制代码 
<template>
  <el-text size="large">大号文本</el-text>
  <el-text size="default">默认文本</el-text>
  <el-text size="small">小号文本</el-text>
</template>

4.4 核心 API

属性名 说明 类型 可选值 默认值
type 文本类型 string primary / success / warning / danger / info default
size 文本尺寸 string large / default / small default
truncated 是否溢出省略 boolean - false
tag 自定义 HTML 标签 string - span

4.5 注意事项

  1. truncated 属性需要父容器有固定宽度才能生效
  2. 适合用于列表项中的文本展示，避免内容溢出破坏布局
  3. 可通过 tag 属性渲染为 p、div 等语义化标签

5. Container 布局容器

5.1 组件简介

Container 是页面整体布局的容器组件，包含 el-header、el-aside、el-main、el-footer 四个子组件，可快速搭建经典后台管理页面布局。

5.2 基础用法

vue 复制代码 
<template>
  <el-container>
    <el-header>Header</el-header>
    <el-container>
      <el-aside width="200px">Aside</el-aside>
      <el-container>
        <el-main>Main</el-main>
        <el-footer>Footer</el-footer>
      </el-container>
    </el-container>
  </el-container>
</template>

5.3 常用场景

场景一：经典后台布局

最常见的后台管理系统布局：

vue 复制代码 
<template>
  <el-container style="height: 100vh">
    <!-- 左侧导航 -->
    <el-aside width="200px" style="background-color: #304156;">
      <el-menu
        default-active="1"
        background-color="#304156"
        text-color="#fff"
        active-text-color="#409eff"
      >
        <el-menu-item index="1">首页</el-menu-item>
        <el-menu-item index="2">用户管理</el-menu-item>
        <el-menu-item index="3">系统设置</el-menu-item>
      </el-menu>
    </el-aside>
    
    <!-- 右侧内容区 -->
    <el-container>
      <!-- 顶部导航 -->
      <el-header height="60px" style="background-color: #fff; border-bottom: 1px solid #e6e6e6;">
        顶部导航栏
      </el-header>
      
      <!-- 主内容区 -->
      <el-main style="background-color: #f0f2f5;">
        内容区域
      </el-main>
    </el-container>
  </el-container>
</template>
场景二：上下布局
vue 复制代码 
<template>
  <el-container direction="vertical">
    <el-header>顶部</el-header>
    <el-main>内容</el-main>
    <el-footer>底部</el-footer>
  </el-container>
</template>

5.4 核心 API

el-container
属性名 说明 类型 可选值 默认值
direction 子元素排列方向 string horizontal / vertical 自动判断
el-header
属性名 说明 类型 默认值
height 高度 string 60px
el-aside
属性名 说明 类型 默认值
width 宽度 string 300px
属性名 说明 类型 默认值
height 高度 string 60px

5.5 注意事项

  1. 嵌套使用时，外层 el-container 的 direction 会根据子元素自动判断
  2. 建议配合 el-menu 使用侧边栏导航
  3. 全屏布局时建议设置 height: 100vh

6. Layout 布局

6.1 组件简介

Layout 基于 24 栅格系统 ，提供灵活的响应式布局方案。通过 el-row 和 el-col 组合，可实现各种复杂布局。

6.2 基础用法

vue 复制代码 
<template>
  <!-- 两列布局 -->
  <el-row>
    <el-col :span="12">占 12 格</el-col>
    <el-col :span="12">占 12 格</el-col>
  </el-row>

  <!-- 三列布局 -->
  <el-row>
    <el-col :span="8">占 8 格</el-col>
    <el-col :span="8">占 8 格</el-col>
    <el-col :span="8">占 8 格</el-col>
  </el-row>
</template>

6.3 常用场景

场景一：带间距的布局
vue 复制代码 
<template>
  <el-row :gutter="20">
    <el-col :span="6">
      <div class="grid-content">内容 1</div>
    </el-col>
    <el-col :span="6">
      <div class="grid-content">内容 2</div>
    </el-col>
    <el-col :span="6">
      <div class="grid-content">内容 3</div>
    </el-col>
    <el-col :span="6">
      <div class="grid-content">内容 4</div>
    </el-col>
  </el-row>
</template>

<style scoped>
.grid-content {
  background-color: #f5f7fa;
  padding: 10px;
  border-radius: 4px;
  text-align: center;
}
</style>
场景二：响应式布局

根据不同屏幕尺寸自动调整列数：

vue 复制代码 
<template>
  <el-row :gutter="10">
    <el-col :xs="24" :sm="12" :md="8" :lg="6" :xl="4">
      <div class="grid-content">响应式列</div>
    </el-col>
    <el-col :xs="24" :sm="12" :md="8" :lg="6" :xl="4">
      <div class="grid-content">响应式列</div>
    </el-col>
    <el-col :xs="24" :sm="12" :md="8" :lg="6" :xl="4">
      <div class="grid-content">响应式列</div>
    </el-col>
  </el-row>
</template>

响应式断点说明：

断点 屏幕宽度 说明
xs < 768px 超小屏幕（手机）
sm ≥ 768px 小屏幕（平板竖屏）
md ≥ 992px 中等屏幕（平板横屏/小显示器）
lg ≥ 1200px 大屏幕（桌面显示器）
xl ≥ 1920px 超大屏幕（高分辨率显示器）
场景三：列偏移
vue 复制代码 
<template>
  <el-row>
    <el-col :span="8" :offset="8">居中显示（占8格，偏移8格）</el-col>
  </el-row>
</template>

6.4 核心 API

el-row
属性名 说明 类型 可选值 默认值
gutter 栅格间距（px） number - 0
justify 水平对齐方式 string start / end / center / space-around / space-between / space-evenly start
align 垂直对齐方式 string top / middle / bottom top
tag 自定义元素标签 string - div
el-col
属性名 说明 类型 默认值
span 栅格占据的列数 number 24
offset 左侧间隔格数 number 0
push 右移格数 number 0
pull 左移格数 number 0
xs < 768px 响应式栅格 number / object -
sm ≥ 768px 响应式栅格 number / object -
md ≥ 992px 响应式栅格 number / object -
lg ≥ 1200px 响应式栅格 number / object -
xl ≥ 1920px 响应式栅格 number / object -

6.5 注意事项

  1. span 值总和不应超过 24
  2. 响应式断点：xs(<768), sm(≥768), md(≥992), lg(≥1200), xl(≥1920)
  3. gutter 建议使用 10/16/20 等偶数，配合子元素的 padding 使用
  4. push 和 pull 可用于实现列的左右移动

7. Border 边框

7.1 组件简介

Border 提供统一的边框样式规范和圆角变量，用于保持项目视觉风格一致。

7.2 基础用法

Border 主要通过 CSS 类名和 CSS 变量实现：

vue 复制代码 
<template>
  <div class="border-demo">
    <div class="border-box border-top">上边框</div>
    <div class="border-box border-right">右边框</div>
    <div class="border-box border-bottom">下边框</div>
    <div class="border-box border-left">左边框</div>
    <div class="border-box border-all">全边框</div>
  </div>
</template>

7.3 核心样式类

样式类 说明
border-top 上边框
border-right 右边框
border-bottom 下边框
border-left 左边框
border-all 全边框

7.4 圆角规范

Element Plus 提供以下 CSS 变量用于圆角控制：

CSS 变量 值 说明
--el-border-radius-base 4px 基础圆角
--el-border-radius-small 2px 小圆角
--el-border-radius-round 20px 大圆角
--el-border-radius-circle 100% 圆形

7.5 自定义边框

css 复制代码 
.my-card {
  border: 1px solid var(--el-border-color-light);
  border-radius: var(--el-border-radius-base);
}

7.6 注意事项

  1. Border 主要是样式规范，非独立组件
  2. 可通过 CSS 变量自定义边框样式
  3. 建议统一使用 Element Plus 提供的边框变量，保持项目一致性

8. Color 颜色

8.1 组件简介

Element Plus 内置了一套完整的色板系统，包含主色、辅助色及其色阶变化，通过 CSS 变量实现主题定制。

8.2 基础色板

颜色名称 色值 用途
Primary #409EFF 主要操作、链接
Success #67C23A 成功状态、通过
Warning #E6A23C 警告状态、注意
Danger #F56C6C 危险状态、错误、删除
Info #909399 信息状态、提示

8.3 使用方式

方式一：组件内置
vue 复制代码 
<template>
  <el-button type="primary">主要</el-button>
  <el-tag type="success">成功</el-tag>
  <el-alert type="warning" title="警告" />
</template>
方式二：CSS 变量
css 复制代码 
.my-button {
  background-color: var(--el-color-primary);
  color: var(--el-color-white);
}

.my-text {
  color: var(--el-color-success);
}
方式三：色阶变化

每种颜色提供 9 个色阶，可用于背景渐变、hover 状态等：

css 复制代码 
.light-bg {
  background-color: var(--el-color-primary-light-7);
}

.dark-hover:hover {
  background-color: var(--el-color-primary-dark-2);
}

8.4 色阶说明

色阶变量 说明
--el-color-primary-light-3 较浅（+30% 亮度）
--el-color-primary-light-5 浅色（+50% 亮度）
--el-color-primary-light-7 很浅（+70% 亮度），适合背景
--el-color-primary-light-8 极浅（+80% 亮度）
--el-color-primary-light-9 最浅（+90% 亮度）
--el-color-primary-dark-2 较深（-20% 亮度），适合 hover

8.5 注意事项

  1. 支持通过主题定制修改色板
  2. 每种颜色有 9 个色阶，满足各种场景需求
  3. 修改主题色后，所有色阶会自动更新

9. Scrollbar 滚动条

9.1 组件简介

Scrollbar 用于自定义滚动条样式，替代浏览器默认滚动条，提供更美观、统一的视觉体验。

9.2 基础用法

vue 复制代码 
<template>
  <el-scrollbar height="400px">
    <div v-for="item in 50" :key="item" class="scroll-item">
      内容 {{ item }}
    </div>
  </el-scrollbar>
</template>

<style scoped>
.scroll-item {
  padding: 10px;
  border-bottom: 1px solid #eee;
}
</style>

9.3 常用场景

场景一：横向滚动
vue 复制代码 
<template>
  <el-scrollbar>
    <div style="display: flex; width: max-content;">
      <div 
        v-for="item in 20" 
        :key="item" 
        style="width: 200px; margin-right: 10px; padding: 20px; background: #f5f7fa;"
      >
        横向内容 {{ item }}
      </div>
    </div>
  </el-scrollbar>
</template>
场景二：监听滚动事件
vue 复制代码 
<script setup lang="ts">
const handleScroll = ({ scrollTop, scrollLeft }) => {
  console.log('scrollTop:', scrollTop)
  console.log('scrollLeft:', scrollLeft)
  
  // 可实现吸顶、懒加载等功能
  if (scrollTop > 100) {
    console.log('滚动超过100px')
  }
}
</script>

<template>
  <el-scrollbar height="400px" @scroll="handleScroll">
    <div v-for="item in 100" :key="item">内容 {{ item }}</div>
  </el-scrollbar>
</template>
场景三：编程式控制滚动
vue 复制代码 
<script setup lang="ts">
const scrollbarRef = ref()

const scrollToTop = () => {
  scrollbarRef.value?.setScrollTop(0)
}

const scrollToBottom = () => {
  const { scrollHeight } = scrollbarRef.value?.wrapRef || {}
  scrollbarRef.value?.setScrollTop(scrollHeight)
}
</script>

<template>
  <div>
    <el-button @click="scrollToTop">回到顶部</el-button>
    <el-button @click="scrollToBottom">滚动到底部</el-button>
    
    <el-scrollbar ref="scrollbarRef" height="400px">
      <div v-for="item in 100" :key="item">内容 {{ item }}</div>
    </el-scrollbar>
  </div>
</template>

9.4 核心 API

属性
属性名 说明 类型 默认值
height 高度 string / number -
max-height 最大高度 string / number -
width 宽度 string / number -
max-width 最大宽度 string / number -
native 是否使用原生滚动 boolean false
wrap-style 包裹容器样式 CSSProperties -
wrap-class 包裹容器类名 string -
view-style 视图容器样式 CSSProperties -
view-class 视图容器类名 string -
noresize 不处理容器尺寸变化 boolean false
tag 包裹容器元素标签 string div
事件
事件名 说明 回调参数
scroll 滚动时触发 ({ scrollTop, scrollLeft })
方法
方法名 说明 参数
setScrollTop 设置纵向滚动位置 number
setScrollLeft 设置横向滚动位置 number
update 更新滚动条状态 -

9.5 注意事项

  1. 必须设置 height 或 max-height 才能生效
  2. 动态内容变化后可调用 update() 方法更新滚动条
  3. 移动端建议使用原生滚动（native 属性）
  4. 嵌套滚动条时需注意事件冒泡问题

10. Space 间距

10.1 组件简介

Space 组件用于统一控制组件之间的间距，替代手动设置 margin 的方式，使布局更规范、更易维护。

10.2 基础用法

vue 复制代码 
<template>
  <el-space>
    <el-button>按钮1</el-button>
    <el-button>按钮2</el-button>
    <el-button>按钮3</el-button>
  </el-space>
</template>

10.3 常用场景

场景一：自定义间距
vue 复制代码 
<template>
  <el-space :size="20">
    <el-tag>标签1</el-tag>
    <el-tag>标签2</el-tag>
    <el-tag>标签3</el-tag>
  </el-space>
</template>
场景二：垂直排列
vue 复制代码 
<template>
  <el-space direction="vertical">
    <el-button>按钮1</el-button>
    <el-button>按钮2</el-button>
    <el-button>按钮3</el-button>
  </el-space>
</template>
场景三：包裹换行
vue 复制代码 
<template>
  <el-space wrap>
    <el-tag v-for="i in 20" :key="i">标签 {{ i }}</el-tag>
  </el-space>
</template>
场景四：自定义分隔符
vue 复制代码 
<template>
  <el-space :spacer="'|'">
    <el-link>首页</el-link>
    <el-link>产品</el-link>
    <el-link>关于</el-link>
  </el-space>
</template>

10.4 核心 API

属性名 说明 类型 可选值 默认值
alignment 对齐方式 string center / end / baseline / stretch center
direction 排列方向 string horizontal / vertical horizontal
size 间距大小 number / string small / default / large small
wrap 是否换行 boolean - false
spacer 自定义间隔 VNode / string - -

10.5 注意事项

  1. wrap 配合 direction="horizontal" 使用可实现弹性布局
  2. spacer 可用于自定义分隔符（如 |、/、•）
  3. size 支持预设值和自定义数值

11. Typography 排版

11.1 组件简介

Typography 组件用于文本排版展示，支持通过 tag 属性渲染不同的 HTML 标签，实现语义化的文本结构。

11.2 基础用法

vue 复制代码 
<template>
  <el-text tag="h1">一级标题</el-text>
  <el-text tag="h2">二级标题</el-text>
  <el-text tag="h3">三级标题</el-text>
  <el-text tag="p">这是一段正文内容</el-text>
</template>

11.3 常用场景

场景一：引用文本
vue 复制代码 
<template>
  <el-text tag="blockquote">
    这是一段引用文本，通常用于引用他人的话语或重要信息。
  </el-text>
</template>
场景二：代码展示
vue 复制代码 
<template>
  <el-text tag="code">const msg = 'Hello World'</el-text>
</template>

11.4 核心 API

属性名 说明 类型 可选值 默认值
tag HTML 标签 string h1 / h2 / h3 / h4 / h5 / p / blockquote / code span
type 文本类型 string primary / success / warning / danger / info default
size 文本尺寸 string large / default / small default
truncated 是否溢出省略 boolean - false

11.5 注意事项

  1. 通过 tag 属性可渲染不同的 HTML 标签，实现语义化
  2. 配合 truncated 可实现长文本省略
  3. 标题标签 h1-h6 会自动应用对应的字体大小

12. ConfigProvider 全局配置

12.1 组件简介

ConfigProvider 为 Element Plus 组件提供统一的全局配置，支持国际化、主题定制、组件尺寸等全局设置。

12.2 基础用法

国际化配置
vue 复制代码 
<script setup lang="ts">
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
</script>

<template>
  <el-config-provider :locale="zhCn">
    <App />
  </el-config-provider>
</template>

12.3 常用场景

场景一：自定义空状态
vue 复制代码 
<script setup lang="ts">
import { Empty } from 'element-plus'
</script>

<template>
  <el-config-provider>
    <template #empty>
      <div style="text-align: center; padding: 20px;">
        <el-empty description="暂无数据" />
      </div>
    </template>
    <el-table :data="[]" />
  </el-config-provider>
</template>
场景二：全局组件尺寸
vue 复制代码 
<template>
  <el-config-provider :size="'small'">
    <el-button>小按钮</el-button>
    <el-input placeholder="小输入框" />
  </el-config-provider>
</template>
场景三：局部配置覆盖
vue 复制代码 
<template>
  <!-- 全局大尺寸 -->
  <el-config-provider :size="'large'">
    <el-button>大按钮</el-button>
    
    <!-- 局部小尺寸 -->
    <el-config-provider :size="'small'">
      <el-button>小按钮</el-button>
    </el-config-provider>
  </el-config-provider>
</template>

12.4 核心 API

属性名 说明 类型 默认值
locale 国际化语言包 object en
size 组件全局尺寸 string default
zIndex 起始 z-index number 2000
namespace CSS 类名前缀 string el
button 按钮全局配置 object -
message Message 全局配置 object -

12.5 注意事项

  1. 建议在应用最外层使用
  2. 子组件的配置会覆盖全局配置
  3. 支持嵌套使用实现局部配置
  4. 国际化语言包需要单独引入

💡 综合实战案例

案例：后台管理系统基础布局

结合本篇多个组件，实现一个经典的后台管理系统基础布局：

vue 复制代码 
<script setup lang="ts">
import { ref } from 'vue'
import { 
  HomeFilled, 
  User, 
  Setting, 
  Search,
  Plus,
  Edit,
  Delete
} from '@element-plus/icons-vue'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

const activeMenu = ref('1')
const loading = ref(false)

const handleSearch = () => {
  loading.value = true
  setTimeout(() => {
    loading.value = false
  }, 1000)
}
</script>

<template>
  <el-config-provider :locale="zhCn">
    <el-container style="height: 100vh;">
      <!-- 左侧导航 -->
      <el-aside width="220px" style="background-color: #304156;">
        <div style="height: 60px; line-height: 60px; text-align: center; color: #fff; font-size: 18px;">
          后台管理系统
        </div>
        <el-menu
          v-model="activeMenu"
          background-color="#304156"
          text-color="#bfcbd9"
          active-text-color="#409eff"
        >
          <el-menu-item index="1">
            <el-icon><HomeFilled /></el-icon>
            <span>首页</span>
          </el-menu-item>
          <el-menu-item index="2">
            <el-icon><User /></el-icon>
            <span>用户管理</span>
          </el-menu-item>
          <el-menu-item index="3">
            <el-icon><Setting /></el-icon>
            <span>系统设置</span>
          </el-menu-item>
        </el-menu>
      </el-aside>

      <!-- 右侧内容区 -->
      <el-container>
        <!-- 顶部操作栏 -->
        <el-header style="background-color: #fff; border-bottom: 1px solid #e6e6e6; display: flex; align-items: center; justify-content: space-between;">
          <el-space>
            <el-input 
              v-model="searchText" 
              placeholder="搜索..." 
              style="width: 200px;"
              :prefix-icon="Search"
              @keyup.enter="handleSearch"
            />
            <el-button type="primary" :icon="Search" :loading="loading" @click="handleSearch">
              搜索
            </el-button>
          </el-space>
          
          <el-space>
            <el-button type="success" :icon="Plus">新增</el-button>
            <el-button type="warning" :icon="Edit">编辑</el-button>
            <el-button type="danger" :icon="Delete">删除</el-button>
          </el-space>
        </el-header>

        <!-- 主内容区 -->
        <el-main style="background-color: #f0f2f5;">
          <el-scrollbar height="calc(100vh - 60px)">
            <el-card>
              <template #header>
                <el-space>
                  <el-text tag="h3" type="primary">数据概览</el-text>
                  <el-tag type="success">实时</el-tag>
                </el-space>
              </template>
              
              <el-row :gutter="20">
                <el-col :span="6">
                  <el-card shadow="hover">
                    <el-text type="primary" size="large">用户数</el-text>
                    <el-text tag="h2">1,234</el-text>
                  </el-card>
                </el-col>
                <el-col :span="6">
                  <el-card shadow="hover">
                    <el-text type="success" size="large">订单数</el-text>
                    <el-text tag="h2">5,678</el-text>
                  </el-card>
                </el-col>
                <el-col :span="6">
                  <el-card shadow="hover">
                    <el-text type="warning" size="large">待处理</el-text>
                    <el-text tag="h2">89</el-text>
                  </el-card>
                </el-col>
                <el-col :span="6">
                  <el-card shadow="hover">
                    <el-text type="danger" size="large">异常数</el-text>
                    <el-text tag="h2">12</el-text>
                  </el-card>
                </el-col>
              </el-row>
            </el-card>
          </el-scrollbar>
        </el-main>
      </el-container>
    </el-container>
  </el-config-provider>
</template>

案例说明：

  • 使用 Container 实现整体布局
  • 使用 Menu 实现左侧导航
  • 使用 Space 控制按钮间距
  • 使用 Button + Icon 实现操作按钮
  • 使用 Scrollbar 实现内容区滚动
  • 使用 Card + Layout 实现数据卡片
  • 使用 ConfigProvider 配置国际化

❓ 常见问题 FAQ

Q1：按钮点击后如何防止重复提交？

A ：使用 loading 属性：

vue 复制代码 
<script setup lang="ts">
const loading = ref(false)

const handleSubmit = async () => {
  loading.value = true
  try {
    await api.submit()
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <el-button type="primary" :loading="loading" @click="handleSubmit">
    提交
  </el-button>
</template>

Q2：Layout 布局在小屏幕上错乱怎么办？

A：使用响应式栅格：

vue 复制代码 
<el-col :xs="24" :sm="12" :md="8" :lg="6">
  内容
</el-col>

Q3：Scrollbar 滚动条不显示？

A ：检查是否设置了 height 或 max-height：

vue 复制代码 
<!-- 错误：未设置高度 -->
<el-scrollbar>
  <div>内容</div>
</el-scrollbar>

<!-- 正确：设置高度 -->
<el-scrollbar height="400px">
  <div>内容</div>
</el-scrollbar>

Q4：如何修改 Element Plus 的主题色？

A：通过 CSS 变量覆盖：

css 复制代码 
:root {
  --el-color-primary: #722ed1;
}

Q5：图标不显示怎么办？

A：检查是否正确安装并引入：

bash 复制代码 
npm install @element-plus/icons-vue
vue 复制代码 
<script setup lang="ts">
import { Search } from '@element-plus/icons-vue'
</script>

📝 总结

本篇介绍了 Element Plus 的 12 个基础组件，涵盖了日常开发中最常用的场景：

组件 核心用途 使用频率
Button 触发操作 ⭐⭐⭐⭐⭐
Icon 图标展示 ⭐⭐⭐⭐⭐
Layout 页面布局 ⭐⭐⭐⭐⭐
Container 整体布局 ⭐⭐⭐⭐
Scrollbar 自定义滚动条 ⭐⭐⭐⭐
Space 间距控制 ⭐⭐⭐⭐
Link 超链接 ⭐⭐⭐
Text 文本展示 ⭐⭐⭐
ConfigProvider 全局配置 ⭐⭐⭐
Border 边框样式 ⭐⭐
Color 颜色系统 ⭐⭐
Typography 文本排版 ⭐⭐

学习建议：

  1. 优先掌握 Button、Icon、Layout 三个高频组件
  2. 布局类组件（Container、Layout）建议多练习
  3. 实际项目中结合使用效果更佳

📌 下一篇预告 ：表单组件（上） - 包含 Input、Select、Cascader、Checkbox 等 10 个表单相关组件的详细使用指南。

📚 系列导航 ：基础组件 | 表单组件上 | 表单组件下 | 数据展示组件 | 导航与反馈组件 | 其他实用组件

相关推荐
恋猫de小郭4 小时前
Jetpack Compose 8 月版正式发布，核心模块 1.12
android·前端·flutter
纵道软件4 小时前
使用 Docker 构建自定义 SeaTunnel Web 服务镜像
前端·docker·容器
山荷枝4 小时前
05-Vue
前端·javascript·vue.js
可爱的秋秋啊5 小时前
vue调用腾讯人脸组件封装+接口请求后端调用
前端·javascript·vue.js
程序员爱钓鱼5 小时前
Rust 生命周期常见错误详解：看懂编译器报错并正确修复
前端·后端·rust
zhanghaha13145 小时前
Python进阶教程：5_XML 解析 —— 新手完全指南
java·前端·数据库
绝世唐门三哥5 小时前
CSS 虚线下划线用法指南：text-decoration 完整解析
前端·javascript·css
程序员爱钓鱼5 小时前
Go if 判断详解
前端·后端·go
程序员黑豆5 小时前
Java字符串拼接全解析：6种方式性能对比与实战指南
java·前端·ai编程
万少10 小时前
DeepSeek 昨晚刚开源了 Harness：附万少的2 万字保姆级教程
前端·后端·架构
热门推荐
01GitHub 镜像站点02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03VSCode+CodeX扩展，无法启动042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路07Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费08历年考研数学一、数学二、数学三真题试卷及答案PDF09如何新建文件夹？ 电脑新建文件夹的4种方法102026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片