零基础吃透 ElementUI：Vue 开发者必备组件库手册

ElementUI 全面入门指南：从零开始到精通

一、ElementUI 简介

ElementUI 是什么？

• 一个基于 Vue.js 2.0 的桌面端组件库
• 由饿了么前端团队开发和维护
• 提供了丰富的、美观的 UI 组件

为什么选择 ElementUI？

• 文档详细，上手容易
• 与 Vue.js 生态无缝集成
• 组件丰富，满足大多数开发需求
• 社区活跃，问题容易解决

💡 小白提示：想象 ElementUI 就像乐高积木，你不需要从头造轮子，只需要选择合适的积木块，就能快速搭建出漂亮的网页。

二、前置准备（小白必看）

1. 安装 Node.js（必须的！）

1. 访问 Node.js 官网 下载安装包
2. 选择 LTS 版本（长期支持版）下载安装
3. 安装完成后，打开命令行（Windows：Win+R 输入 cmd；Mac：终端）
4. 输入 node -v 和 npm -v 验证安装

💡 小白提示：Node.js 是开发 Vue 项目的必备环境，就像做菜需要锅一样。

2. 安装 Vue CLI（项目脚手架）

# 全局安装 Vue CLI
npm install -g @vue/cli

💡 小白提示：Vue CLI 就像一个"项目生成器"，帮你快速搭建 Vue 项目。

3. 创建 Vue 项目

# 创建新项目
vue create elementui-demo

# 选择默认配置（按回车键选择）
# 或手动选择（按方向键选择）
# 选择 "Manually select features"，然后选择需要的特性（Babel、Router、Vuex等）

💡 小白提示：这个过程就像在点餐，选择你想要的配置。

4. 设置 npm 镜像（加速安装）

npm config set registry https://registry.npm.taobao.org

💡 小白提示：淘宝镜像就像快递的"本地仓库"，下载包更快。

5. 运行项目

# 进入项目目录
cd elementui-demo

# 启动项目
npm run serve

💡 小白提示：运行后，浏览器会自动打开，看到"Welcome to Your Vue.js App"就是成功了！

三、安装 ElementUI

1. 安装 ElementUI

在项目目录下执行：

npm install element-ui -S

💡 小白提示：-S 表示将依赖添加到 package.json 的 dependencies 中。

2. 在项目中引入 ElementUI

打开 src/main.js 文件，添加以下代码：

import Vue from 'vue'
import App from './App.vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css' // 引入样式

Vue.use(ElementUI, { size: "small" }) // 全局注册

Vue.config.productionTip = false

new Vue({
  render: h => h(App)
}).$mount('#app')

💡 小白提示：Vue.use(ElementUI) 就是告诉 Vue："我需要 ElementUI 这个组件库"。

四、ElementUI 基础使用

1. 栅格系统布局（最常用）

ElementUI 的栅格系统就像Excel表格一样，将页面分成24列。

基本用法

<el-row>
  <el-col :span="6">列1（占6/24）</el-col>
  <el-col :span="6">列2（占6/24）</el-col>
  <el-col :span="6">列3（占6/24）</el-col>
  <el-col :span="6">列4（占6/24）</el-col>
</el-row>

💡 小白提示：span="6" 表示这列占总宽度的 6/24，也就是 1/4。

带间距的布局

<el-row :gutter="20"> <!-- 20px 间距 -->
  <el-col :span="6">
    <div style="background: #409EFF; height: 100px">列1</div>
  </el-col>
  <el-col :span="6">
    <div style="background: #67C23A; height: 100px">列2</div>
  </el-col>
  <el-col :span="6">
    <div style="background: #E6A23C; height: 100px">列3</div>
  </el-col>
  <el-col :span="6">
    <div style="background: #F56C6C; height: 100px">列4</div>
  </el-col>
</el-row>

💡 小白提示：:gutter="20" 让列之间有 20px 的间距，就像在表格单元格之间留空。

2. 布局容器（Container）

ElementUI 提供了更高级的布局方式，适合创建完整页面。

基本用法

<el-container style="height: 500px; border: 1px solid #eee">
  <el-aside width="200px" style="background-color: #f5f5f5">
    <el-menu :default-openeds="['1']">
      <el-submenu index="1">
        <template slot="title"><i class="el-icon-message"></i>导航一</template>
        <el-menu-item-group>
          <template slot="title">分组一</template>
          <el-menu-item index="1-1">选项1</el-menu-item>
          <el-menu-item index="1-2">选项2</el-menu-item>
        </el-menu-item-group>
      </el-submenu>
    </el-menu>
  </el-aside>
  
  <el-container>
    <el-header style="text-align: right; font-size: 12px">
      <el-dropdown>
        <i class="el-icon-setting" style="margin-right: 15px"></i>
        <el-dropdown-menu slot="dropdown">
          <el-dropdown-item>查看</el-dropdown-item>
          <el-dropdown-item>新增</el-dropdown-item>
          <el-dropdown-item>删除</el-dropdown-item>
        </el-dropdown-menu>
      </el-dropdown>
      <span>王小虎</span>
    </el-header>
    
    <el-main>
      <el-table :data="tableData">
        <el-table-column prop="date" label="日期" width="150"></el-table-column>
        <el-table-column prop="name" label="姓名" width="120"></el-table-column>
        <el-table-column prop="address" label="地址"></el-table-column>
      </el-table>
    </el-main>
  </el-container>
</el-container>

💡 小白提示：

• el-container：整个容器
• el-aside：侧边栏
• el-header：页头
• el-main：主要内容
• el-footer：页脚
• el-menu：菜单

五、常用 ElementUI 组件详解（小白友好版）

1. 表单组件

下拉选择框（最常用！）

<el-select v-model="selectedCity" placeholder="请选择城市">
  <el-option
    v-for="city in cities"
    :key="city.id"
    :label="city.name"
    :value="city.id">
  </el-option>
</el-select>

data() {
  return {
    selectedCity: '', // 默认选中
    cities: [
      { id: 1, name: '北京' },
      { id: 2, name: '上海' },
      { id: 3, name: '广州' },
      { id: 4, name: '深圳' }
    ]
  }
}

💡 小白提示：

• v-model：绑定选中的值
• v-for：遍历城市列表
• :key：唯一标识（必须的！）
• :label：显示的文本
• :value：选中后的值

单选框

<el-radio-group v-model="gender">
  <el-radio :label="1">男</el-radio>
  <el-radio :label="2">女</el-radio>
</el-radio-group>

data() {
  return {
    gender: 1 // 默认选中"男"
  }
}

表单验证（新手必学）

<el-form :model="form" :rules="rules" ref="form">
  <el-form-item label="用户名" prop="username">
    <el-input v-model="form.username"></el-input>
  </el-form-item>
  <el-form-item label="密码" prop="password">
    <el-input type="password" v-model="form.password"></el-input>
  </el-form-item>
  <el-form-item>
    <el-button type="primary" @click="submitForm">提交</el-button>
  </el-form-item>
</el-form>

data() {
  return {
    form: {
      username: '',
      password: ''
    },
    rules: {
      username: [
        { required: true, message: '请输入用户名', trigger: 'blur' },
        { min: 3, max: 10, message: '长度在 3 到 10 个字符', trigger: 'blur' }
      ],
      password: [
        { required: true, message: '请输入密码', trigger: 'blur' },
        { min: 6, max: 12, message: '长度在 6 到 12 个字符', trigger: 'blur' }
      ]
    }
  }
},
methods: {
  submitForm() {
    this.$refs.form.validate(valid => {
      if (valid) {
        alert('提交成功！');
      } else {
        console.log('验证失败！');
        return false;
      }
    });
  }
}

💡 小白提示：

• prop="username"：表单项的唯一标识
• required: true：必填项
• trigger: 'blur'：失去焦点时验证
• validate：验证方法

2. 表格组件

基本表格

<el-table :data="tableData" style="width: 100%">
  <el-table-column prop="date" label="日期" width="150"></el-table-column>
  <el-table-column prop="name" label="姓名" width="120"></el-table-column>
  <el-table-column prop="address" label="地址"></el-table-column>
</el-table>

data() {
  return {
    tableData: [
      {
        date: '2016-05-02',
        name: '王小虎',
        address: '上海市普陀区金沙江路 1518 弄'
      },
      {
        date: '2016-05-04',
        name: '王小虎',
        address: '上海市普陀区金沙江路 1518 弄'
      }
    ]
  }
}

表格行高亮（状态显示）

<el-table-column label="状态" width="100">
  <template slot-scope="scope">
    <el-tag :type="scope.row.status === '通过' ? 'success' : 'danger'">
      {{scope.row.status}}
    </el-tag>
  </template>
</el-table-column>

💡 小白提示：slot-scope="scope" 是作用域插槽，scope.row 表示当前行的数据。

3. 上传组件

图片上传

<el-upload
  action="https://jsonplaceholder.typicode.com/posts/"
  list-type="picture-card"
  :on-preview="handlePreview"
  :on-remove="handleRemove">
  <i class="el-icon-plus"></i>
</el-upload>

methods: {
  handleRemove(file, fileList) {
    console.log('移除文件', file, fileList);
  },
  handlePreview(file) {
    console.log('预览文件', file);
  }
}

💡 小白提示：

• action：上传地址
• list-type="picture-card"：显示为图片卡片
• :on-preview：预览时触发
• :on-remove：移除时触发

4. 日期时间选择器

<el-date-picker
  v-model="date"
  type="date"
  placeholder="选择日期">
</el-date-picker>

data() {
  return {
    date: '' // 日期对象
  }
}

💡 小白提示：type="date" 选择日期，type="datetime" 选择日期时间。

六、高级组件（小白也能看懂）

1. 树形下拉选择（多级菜单）

<el-select ref="selectTree" v-model="form.departmentId" clearable style="width: 100%;">
  <el-option
      v-for="item in departmentList"
      :key="item.id"
      :value="item.id"
      :label="item.name"
      style="display: none;"/>
  <el-tree
      :data="departmentTree"
      :props="{children: 'children', label: 'name'}"
      highlight-current
      @node-click="handleNodeClick"
      default-expand-all />
</el-select>

data() {
  return {
    departmentList: [], // 扁平列表
    departmentTree: []  // 树形结构
  }
},
created() {
  // 获取扁平部门列表
  this.$request.get('/department/selectAll').then(res => {
    this.departmentList = res.data
  })
  // 获取树形部门列表
  this.$request.get('/department/selectTree').then(res => {
    this.departmentTree = res.data
  })
},
methods: {
  handleNodeClick(node) {
    this.$set(this.form, 'departmentId', node.id)
    this.$refs.selectTree.blur()
  }
}

💡 小白提示：

• ref="selectTree"：获取组件引用
• @node-click：点击节点触发
• default-expand-all：默认展开所有节点

2. 富文本编辑器（wangeditor）

安装

npm install wangeditor --save

使用

<div id="editor"></div>

import E from "wangeditor"

export default {
  data() {
    return {
      editor: null
    }
  },
  mounted() {
    this.setRichText('')
  },
  methods: {
    setRichText(html) {
      this.$nextTick(() => {
        this.editor = new E(`#editor`)
        this.editor.config.uploadImgServer = '/api/files/upload' // 上传地址
        this.editor.create() // 创建
        this.editor.txt.html(html) // 设置内容
      })
    }
  }
}

💡 小白提示：

• this.$nextTick：确保 DOM 已渲染
• this.editor.txt.html(html)：设置编辑器内容
• this.editor.create()：创建编辑器

七、常见问题与解决方案（小白必看）

1. 组件样式不生效

原因：没有正确引入 ElementUI 样式

解决方案：

// 在 main.js 中
import 'element-ui/lib/theme-chalk/index.css' // 确保已引入

2. 表单验证不生效

原因 ：没有正确设置 prop 和 rules

解决方案：

<el-form-item label="用户名" prop="username">
  <el-input v-model="form.username"></el-input>
</el-form-item>

rules: {
  username: [
    { required: true, message: '请输入用户名', trigger: 'blur' }
  ]
}

3. 上传图片不显示

原因：没有正确设置上传地址和响应格式

解决方案：

this.editor.config.uploadImgServer = '/api/files/upload'
this.editor.config.uploadImgParams = { type: 'img' }

八、最佳实践（小白也能用）

1. 合理使用布局 ：
   • 简单页面用栅格系统
   • 复杂页面用 Container 布局
2. 表单验证 ：
   • 必填项用 required: true
   • 长度限制用 min 和 max
3. 响应式设计 ：
   • ElementUI 本身支持响应式
   • 用 :span 代替固定宽度
4. 组件复用 ：
   • 把常用组件封装成独立组件
   • 例如：封装一个带验证的输入框
5. 样式定制 ：
   • 通过修改 ElementUI 的主题来定制颜色
   • 在 vue.config.js 中配置

九、总结

ElementUI 是一个非常适合初学者的 UI 组件库，它让前端开发变得简单而高效。通过本指南，你应该已经掌握了：

✅ 如何安装和配置 ElementUI

✅ 如何使用栅格系统和布局容器

✅ 如何使用常用组件（下拉框、表格、上传等）

✅ 如何处理常见问题

💡 小白提示：学习 ElementUI 最好的方法就是动手实践，不要怕犯错。每写一个组件，你就离精通更近一步。

十、推荐资源

1. ElementUI 官方文档------(Element------全球最受欢迎的Vue UI框架) - 必看！
2. Vue.js 官方文档 - 了解 Vue 基础(Vue.js - 渐进式 JavaScript 框架 | Vue.js)
3. ElementUI GitHub 仓库 - 查看源码和 Issues(GitHub - ElemeFE/element: A Vue.js 2.0 UI Toolkit for Web)

💡 最后，记住："不要害怕犯错，每犯一次错误，你就离成功更近一步。" 现在就开始用 ElementUI 创建你的第一个应用吧！