Element Plus表单校验与表格选择器组件实践

脚本专家

Element Plus 是 Vue 3 生态中常用的 UI 组件库。原文围绕按钮、图标、消息提示、单选、选择器、开关、表单、表格等常用组件，整理了 Props、事件、方法调用和示例代码。下面按实际开发中的使用路径重组这些信息，重点放在参数含义、调用方式、表单校验流程和表格配置上，便于在项目里对照排查。

一、按钮与图标组件
el-button 的常用 Props 包括 size（large/default/small）、type（primary/success/warning/danger/info/text）、plain、round、circle、loading、disabled、icon、autofocus、native-type（button/submit/reset）。点击事件为 click。图标组件可使用 @element-plus/icons-vue 中的图标。原文示例把按钮类型、朴素按钮、圆角按钮、圆形图标按钮、加载和禁用状态放在同一模板中，核心写法如下：

2. <template>
3.   <el-button>默认按钮</el-button>
4.   <el-button type='primary'>主要按钮</el-button>
5.   <el-button plain>朴素按钮</el-button>
6.   <el-button type='primary' round>圆角主要按钮</el-button>
7.   <el-button type='primary' icon='Edit' circle />
8.   <el-button type='primary' :loading='true'>加载中</el-button>
9.   <el-button type='primary' disabled>禁用按钮</el-button>
10. </template>
11. <script setup>
12. import { Edit, Check, Delete } from '@element-plus/icons-vue'
13. </script>

复制代码

el-icon 是图标容器，Props 有 size、color、class，图标本身通过默认插槽传入，例如 <el-icon :size='20' color='#409eff'><Edit /></el-icon>。class 可用于自定义颜色和字号。

二、消息提示与选择类组件
ElMessage 通过方法调用，不依赖模板中的组件标签。常用调用包括 ElMessage('这是一条消息')、ElMessage.success('操作成功')、ElMessage.warning('警告内容')、ElMessage.error('错误信息')、ElMessage.info('提示信息')。配置项包括 message、type（success/warning/error/info）、icon、dangerouslyUseHTMLString、duration（默认3000毫秒）、showClose、center、offset（默认20）、onClose。如果 message 作为 HTML 片段处理，需要显式设置 dangerouslyUseHTMLString，原文也把该配置列为可选能力。
el-radio 的 Props 包括 model-value/v-model、label、disabled、border、size、name；el-radio-group 支持 model-value/v-model、size、disabled、text-color、fill。按钮样式可使用 el-radio-button，示例通过 v-model 绑定 ref('上海') 等值。
el-select 支持 multiple、disabled、clearable、filterable、allow-create、loading、remote、remote-method、placeholder、size、collapse-tags、collapse-tags-tooltip；el-option 使用 value、label、disabled。远程搜索时通常配合 filterable、remote、reserve-keyword、remote-method 和 loading。原文示例在 query 非空时把 loading 置为 true，用 setTimeout 模拟请求，过滤 options 后写入 remoteOptions；query 为空时清空 remoteOptions。这个逻辑适合替换为真实接口请求，但要注意 loading 的收尾和空查询处理。

2. <template>
3.   <el-select v-model='remoteValue' multiple filterable remote reserve-keyword
4.     placeholder='请输入关键词' :remote-method='remoteMethod' :loading='loading'>
5.     <el-option v-for='item in remoteOptions' :key='item.value'
6.       :label='item.label' :value='item.value' />
7.   </el-select>
8. </template>
9. <script setup>
10. import { ref } from 'vue'
11. const remoteValue = ref([])
12. const loading = ref(false)
13. const remoteOptions = ref([])
14. const options = [
15.   { value: 'option1', label: '黄金糕' },
16.   { value: 'option2', label: '双皮奶' },
17.   { value: 'option3', label: '蚵仔煎' },
18. ]
19. const remoteMethod = (query) => {
20.   if (query !== '') {
21.     loading.value = true
22.     setTimeout(() => {
23.       loading.value = false
24.       remoteOptions.value = options.filter(item =>
25.         item.label.toLowerCase().includes(query.toLowerCase())
26.       )
27.     }, 200)
28.   } else {
29.     remoteOptions.value = []
30.   }
31. }
32. </script>

复制代码

el-switch 的常用 Props 包括 model-value/v-model、disabled、width、inline-prompt、active-icon、inactive-icon、active-text、inactive-text、active-value、inactive-value、active-color、inactive-color、name。原文还展示了通过 style 设置 --el-switch-on-color 和 --el-switch-off-color 两个 CSS 变量来改变开关颜色，这种方式比重写组件样式更直接。

三、表单校验流程
el-form 的 Props 包括 model、rules、inline、label-position（top/left/right）、label-width、label-suffix、hide-required-asterisk、require-asterisk-position、show-message、inline-message、status-icon、disabled、scroll-to-error。el-form-item 的 Props 包括 label、label-width、prop、required、rules、error、show-message、inline-message、size。原文特别指出：el-form-item 必须设置 prop 属性才能进行校验；这个 prop 要对应 model 中的字段名，否则规则不会按预期落到具体表单项上。
原文示例中，rules 为 username 设置 required、min/max 和 trigger:'blur'，为 email 设置 required、type:'email' 和 trigger:['blur','change']，为 age 设置 required、type:'number'。提交时使用 formEl.validate()，成功提示，失败进入 catch；重置时调用 formEl.resetFields()。常见错误原因可以从这段逻辑反推：没有给 el-form 绑定 model 或 rules、el-form-item 缺少 prop、字段名与 model 不一致、trigger 设置不匹配、validate 返回 Promise 但未用 async/await 或 catch 处理。排查时先检查 model、prop、rules 三者是否对齐，再看校验触发时机和错误信息展示配置。

2. <template>
3.   <el-form ref='ruleFormRef' :model='form' :rules='rules' label-width='120px'>
4.     <el-form-item label='用户名' prop='username'>
5.       <el-input v-model='form.username' />
6.     </el-form-item>
7.     <el-form-item label='邮箱' prop='email'>
8.       <el-input v-model='form.email' />
9.     </el-form-item>
10.     <el-form-item label='年龄' prop='age'>
11.       <el-input-number v-model='form.age' :min='1' :max='150' />
12.     </el-form-item>
13.     <el-form-item>
14.       <el-button type='primary' @click='submitForm(ruleFormRef)'>提交</el-button>
15.       <el-button @click='resetForm(ruleFormRef)'>重置</el-button>
16.     </el-form-item>
17.   </el-form>
18. </template>
19. <script setup>
20. import { ref } from 'vue'
21. import { ElMessage } from 'element-plus'
22. const ruleFormRef = ref()
23. const form = ref({ username: '', email: '', age: 18 })
24. const rules = ref({
25.   username: [
26.     { required: true, message: '请输入用户名', trigger: 'blur' },
27.     { min: 3, max: 15, message: '长度在 3 到 15 个字符', trigger: 'blur' }
28.   ],
29.   email: [
30.     { required: true, message: '请输入邮箱地址', trigger: 'blur' },
31.     { type: 'email', message: '请输入正确的邮箱地址', trigger: ['blur', 'change'] }
32.   ],
33.   age: [
34.     { required: true, message: '请输入年龄', trigger: 'blur' },
35.     { type: 'number', message: '年龄必须为数字值', trigger: 'blur' }
36.   ]
37. })
38. const submitForm = async (formEl) => {
39.   if (!formEl) return
40.   try {
41.     await formEl.validate()
42.     ElMessage.success('提交成功！')
43.   } catch (error) {
44.     console.log('校验失败', error)
45.   }
46. }
47. const resetForm = (formEl) => {
48.   if (!formEl) return
49.   formEl.resetFields()
50. }
51. </script>

复制代码

四、表格组件配置
el-table 用于展示大量结构化数据。原文列出的常用 Props 包括 data、height、max-height、stripe、border、fit、show-header、highlight-current-row、current-row-key、row-class-name、row-style、cell-class-name、cell-style、header-row-class-name、header-row-style、header-cell-class-name、header-cell-style、row-key、empty-text、default-expand-all、expand-row-keys、default-sort、tooltip-effect、show-summary、sum-text、summary-method、span-method、select-on-indeterminate、indent、lazy、load、tree-props。其中 row-key 用于行数据 Key，原文说明它可用来优化渲染；树形数据场景还会涉及 default-expand-all、expand-row-keys、lazy、load 和 tree-props。
el-table-column 的常用 Props 包括 type（selection/index/expand）、index、column-key、label、prop、width、min-width、fixed、render-header、sortable、sort-method、resizable、formatter、show-overflow-tooltip、align、header-align、class-name、label-class-name、selectable、reserve-selection、filters、filter-placement。需要区分列类型和多选行为：type='selection' 时 selectable 决定某行 checkbox 是否可选，reserve-selection 可在数据更新后保留选中项；固定列使用 fixed；内容过长隐藏时可用 show-overflow-tooltip；需要格式化展示时用 formatter。原文对表格属性的说明在 filter-placement 处截断，实际使用时仍应结合所用版本文档核对其余属性。
从这些参数可以看出，Element Plus 表格的配置重点不在模板堆叠，而在数据字段、列定义和交互状态的对齐：data 提供数据源，prop 对应字段，row-key 影响渲染优化和展开状态，sortable/sort-method 处理排序，summary-method 和 span-method 处理合计与合并。表单和表格组合时，建议先明确 model、rules、prop 和 row-key 这些“契约”字段，再补充样式和交互属性。

五、实践建议
原文覆盖的是 Vue 3 生态下的 Element Plus 常用组件。按开发中的落地顺序，可以把工作拆成三步：先确认组件绑定值和字段名，再配置事件或方法调用，最后处理校验、远程请求和表格渲染的性能相关属性。图标统一从 @element-plus/icons-vue 引入；ElMessage 这类全局提示通过方法调用；远程搜索要处理空查询、loading 收尾和过滤结果；表单校验要保证 el-form 的 model、el-form-item 的 prop、rules 的字段名一致；表格则优先设置 row-key，并根据数据量考虑 height、max-height、fixed、show-overflow-tooltip 等配置。这样组织后，组件参数不再是孤立列表，而是能对应到具体调用方式、错误原因和排查路径。