攻克 Element Plus 开发痛点：5 个高频问题解决方案

你是否在使用 Element Plus 时遇到过组件不显示、表单验证失败、表格数据加载异常等问题？本文将针对这些开发者最常遇到的痛点，提供经过验证的解决方案和代码示例，帮助你快速定位并解决问题，提升开发效率。

一、组件样式丢失或布局错乱

问题表现

引入组件后样式未生效，或组件布局与官方示例不一致。

解决方案

确保正确引入 Element Plus 样式文件，推荐使用按需导入方式以减小打包体积。

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

若使用按需导入，需安装额外插件：

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

并在 vite.config.ts 中配置：

import { defineConfig } from 'vite'
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: [
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
})

相关源码：packages/theme-chalk/src/index.scss

二、表单验证失败或不触发验证

问题表现

表单提交时未触发验证，或验证规则不生效。

解决方案

确保正确设置 model 和 rules 属性，并使用 ref 调用 validate 方法。

<template>
  <el-form
    ref="ruleFormRef"
    :model="ruleForm"
    :rules="rules"
    label-width="120px"
  >
    <el-form-item label="活动名称" prop="name">
      <el-input v-model="ruleForm.name" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(ruleFormRef)">提交</el-button>
    </el-form-item>
  </el-form>
</template>

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

const ruleFormRef = ref<FormInstance>()
const ruleForm = ref({
  name: '',
})
const rules = ref({
  name: [
    { required: true, message: '请输入活动名称', trigger: 'blur' },
    { min: 3, max: 5, message: '长度在 3 到 5 个字符', trigger: 'blur' },
  ],
})

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid) => {
    if (valid) {
      console.log('submit!')
    } else {
      console.log('error submit!')
      return false
    }
  })
}
</script>

关键注意点：

1. 为 el-form 设置 ref 属性
2. 为 el-form-item 设置 prop 属性，与 rules 中的字段对应
3. 使用 async/await 调用 validate 方法

相关源码：packages/components/form/src/form.vue

三、表格数据不显示或分页异常

问题表现

表格数据已加载但不显示，或分页控件不生效。

解决方案

确保正确绑定 data 属性，且数据格式为数组。分页功能需配合相应属性使用。

<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
  
  <el-pagination
    v-model:page="pageNum"
    v-model:page-size="pageSize"
    :total="total"
    :page-sizes="[10, 20, 30, 40]"
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
    layout="total, sizes, prev, pager, next, jumper"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const tableData = ref([
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  // 更多数据...
])
const pageNum = ref(1)
const pageSize = ref(10)
const total = ref(100)

const handleSizeChange = (val: number) => {
  console.log(`每页 ${val} 条`)
}
const handleCurrentChange = (val: number) => {
  console.log(`当前页: ${val}`)
}
</script>

相关示例：docs/examples/table/basic.vue

四、图标不显示或显示异常

问题表现

使用 el-icon 组件时图标不显示，或控制台提示图标相关错误。

解决方案

Element Plus 从 2.0 版本开始使用新的图标系统，需单独安装并导入图标。

npm install @element-plus/icons-vue

使用方式：

<template>
  <el-button type="primary" icon="Search">搜索</el-button>
  
  <!-- 或单独引入 -->
  <el-button type="primary">
    <Search />
    搜索
  </el-button>
</template>

<script lang="ts" setup>
import { Search } from '@element-plus/icons-vue'
</script>

相关源码：packages/components/icon/src/icon.vue

五、对话框关闭后数据未重置

问题表现

关闭对话框后，再次打开发现上次输入的数据仍然存在。

解决方案

在对话框关闭事件中重置表单数据或调用 resetFields 方法。

<template>
  <el-button @click="dialogVisible = true">打开对话框</el-button>
  
  <el-dialog v-model="dialogVisible" @close="handleClose">
    <el-form ref="formRef" :model="form" :rules="rules">
      <el-form-item label="名称" prop="name">
        <el-input v-model="form.name" />
      </el-form-item>
    </el-form>
  </el-dialog>
</template>

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

const dialogVisible = ref(false)
const formRef = ref<FormInstance>()
const form = ref({
  name: ''
})
const rules = ref({
  name: [
    { required: true, message: '请输入名称', trigger: 'blur' }
  ]
})

const handleClose = () => {
  formRef.value?.resetFields()
  // 或手动重置数据
  // form.value.name = ''
}
</script>

相关方法：packages/components/form/src/form.vue#L64

总结

本文介绍了 Element Plus 开发中最常见的 5 个问题及解决方案，涵盖了样式、表单、表格、图标和对话框等核心组件。遇到问题时，建议先查阅官方文档，或在 GitHub 仓库的 Issues 中搜索类似问题。

官方文档：docs/en-US/guide/quickstart.md 问题反馈：CONTRIBUTING.md

掌握这些解决方案，能够帮助你更高效地使用 Element Plus 进行开发，避免常见陷阱，提升项目质量和开发效率。