1. 先搞明白 el-form 校验体系的三个支点el-form 的校验体系说穿了就是三个东西在互相咬合model、prop、rules。绝大多数人第一次用的时候是照着官方示例抄下来的能跑但一旦遇到动态表单、嵌套对象、弹窗复用、分步提交这些真实场景就会开始出现明明写了规则却不校验重置按钮没反应新增一行校验串到别的行去了这类问题。根本原因不是框架有 bug而是这三个支点在心里的模型是模糊的。我见过太多项目里 el-form 被当成一个包裹容器来用——只要把输入框塞进去随便写个prop规则能红一下就算完事。结果就是后期每加一个字段都要提心吊胆地试一遍。这篇文章我打算把这三个支点各自负责什么、它们之间怎么传值、校验失败时的信息是怎么一路冒到屏幕上的全部摊开讲清楚。适合正在用 Element UI 或 Element Plus 做中后台表单的同学也适合已经用了两三年但一直没系统梳理过的人。先给一个最简的因果链el-form 通过model拿到整份表单数据每个 el-form-item 通过自己的prop从这份数据里定位到属于它的那个字段点击提交时el-form 把定位到的值和绑在 form-item 上的rules一起交给 async-validatorvalidator 跑完把结果回传给 form-itemform-item 决定要不要把边框变红、要不要显示那行小字。整条链路上任何一环错了表现都是不校验或者校验错位。1.1 model 是数据源头不是装饰品model这个词很容易误导人因为它和很多其他框架里表示数据模型的概念混在一起了。在 el-form 里它的职责非常单一它是校验时取值的唯一来源。也就是说el-form-item 在准备校验前会拿着自己的prop去model这个对象上查字典查到什么值就拿什么值去比对规则。这个定位带来两个很容易被忽略的结论。第一v-model绑在 el-input 上的那个字段和 el-form 的model必须是同一个引用。很多同学会写成el-form :modelform但内部输入框绑的是el-input v-modelformInline.name两个不同的对象校验时 el-form 去form里找不到name就会静默失败——页面上什么提示都没有你也搞不清为什么规则没生效。第二model必须是个响应式对象Vue 2 里要用data()里声明的对象Vue 3 里用reactive或者ref包过的对象。如果你在created里临时拼了一个普通对象赋给this.formVue 2 会因为属性没有经过Object.defineProperty处理而丢失响应式表现为输入框能打字但校验拿到的永远是最初的空值。我在一个老项目里排查过类似问题表单里有个从模板带入的功能用户点了之后直接把接口返回的对象整体赋给了this.form结果带入的数据校验全过手动改的内容反而校验不过。原因就是整体赋值把响应式对象的引用换掉了el-form 内部持有的还是老引用。正确做法是用Object.assign(this.form, res.data)或者逐个字段赋值保持引用不变。1.2 prop 是取值路径决定校验能否命中如果把model比作一个文件柜那prop就是抽屉编号。它告诉 el-form-item你要校验的值在文件柜的第几层第几格。这个编号可以是简单的name也可以是带层级的user.address.city还可以是数组下标list.0.phone。关键在于prop 只负责定位不负责创建。如果model.user.address本身是undefined你写propuser.address.city取值链路在中途就断了。async-validator 拿不到值required规则会直接报必填哪怕用户其实填了别的层级。这也是为什么嵌套表单一定要保证中间层级对象先初始化好不能等着用户输入再动态补。另外有个高频误区很多人以为prop只是个标识符随便起个名字只要和规则里的 key 对应就行。这是错的。prop必须是model上真实存在的路径否则校验状态、错误信息、滚动到错误项这些功能都会失效或错位。我在 Code Review 里最常见的改法就是把propphone改成propcontactInfo.phone一行修复三个 bug。1.3 rules 只是声明真正干活的是 async-validatorrules写起来很像配置但它的本质是传给 async-validator 的 schema 描述。async-validator 是一个独立的校验库el-form 只是它的调度器。理解这一层很多行为就顺了为什么type: number要配合v-model.number用为什么required对数组和字符串的表现不一样为什么自定义校验函数要用callback而不是直接return false——这些都是 async-validator 的语义不是 el-form 定的。三层结构里model和prop决定校验谁rules决定怎么校验触发时机trigger决定什么时候校验提交时的validate决定全部跑一遍。下面几节我会按这个顺序把每一层单独拆开讲然后拼回完整流程。2. model 属性从绑定到重置的完整链路model看起来是三个属性里最简单的一个冒号就写完了但它埋的坑最多尤其是和resetFields配合的时候。很多人以为resetFields是把表单清空实际上它干的是把表单恢复到组件挂载那一刻的样子。这两件事在静态表单里表现一样在动态表单、编辑弹窗、条件渲染的场景里就是天壤之别。我们要先接受一个事实el-form 内部维护了一份initialValue快照。每个 el-form-item 在mounted阶段会调用addField把自己注册进 el-form 的fields列表同时通过getPropByPath从当前model上取一次值存成自己的initialValue。之后点击重置el-form 遍历所有 field把prop路径上的值改回对应的initialValue。整个链条里挂载时刻是个硬编码的时间点绕不过去。2.1 声明式初始化字段必须先存在先说一个基础但经常被违背的原则表单里会出现的字段在model初始化时就全部声明出来。不要依赖用户输入后再创建属性也不要在提交前临时挂字段。在 Vue 2 里这是硬约束。data()中没声明的属性后续通过this.form.newField xxx添加是检测不到变化的输入框能显示因为你手动赋的值本身在 DOM 上渲染了但校验、watch、computed 全部拿不到更新。Vue 3 的 Proxy 解决了这个限制但我不建议依赖它因为你的组件可能被复用到 Vue 2 项目里而且给undefined字段做required校验时async-validator 的类型推断会变得很不可控。初始化还有个细节初始值的类型要和字段语义一致。数值字段给0还是null字符串字段给还是undefined会直接影响required的判定结果。async-validator 的required判定逻辑大致是undefined、null、空字符串、空数组都算空。但0和false不算空。所以一个数字输入框如果初始值是null用户填0校验能过如果初始值是而用户填了0但没加.number修饰符拿到的会是字符串0配type: number就会报类型错误。我一般会这样起手// Vue 3 Element Plus const form reactive({ name: , age: null, tags: [], contact: { phone: , email: } })age用null而不是0是为了让未填写和填了0能区分开tags用空数组而不是null是为了让type: array的校验有确定的类型可判。2.2 resetFields 的真相重置的是挂载瞬间的快照这一段是重点。resetFields的行为可以概括成一句话它能重置的只能是它认识的那些 field而它认识的是曾经挂载过并且还在 fields 列表里的 form-item。由此派生出一串真实场景里的坑。第一个是编辑弹窗复用。表格里点编辑弹窗打开父组件把当前行数据传给子组件赋给form。如果这个弹窗组件是被v-if控制显隐的那么每次打开都是重新挂载form-item 的initialValue会记录成这次传进来的行数据用户改了一半点取消resetFields会重置回行数据而不是空表单——这通常是你想要的。但如果弹窗是v-show控制、或者弹窗一直在 DOM 里只是切换数据那initialValue记录的还是第一次打开时的数据第二次打开点重置就会串数据。第二个坑是条件渲染。表单里有个是否开具发票的开关打开后出现一组发票字段。这组字段用v-if包着用户先打开填了值再关掉开关字段销毁但 form-item 的removeField会把它从 fields 里移除所以resetFields不会再管它。等用户再次打开字段重新挂载initialValue记录成上次填的值——因为数据还在form.invoice里没清。于是重置按钮对这个分组就彻底失效了。我的处理策略是对于弹窗、抽屉、条件分组这类场景放弃 resetFields改用显式的手动重置。写一个resetForm函数把初始值抽成一个工厂函数每次重置时整体Object.assign覆盖const createForm () ({ name: , age: null, tags: [], contact: { phone: , email: } }) const form reactive(createForm()) const resetForm () { Object.assign(form, createForm()) // 如果字段被 v-if 移除过还要清掉历史校验状态 formRef.value?.clearValidate() }注意这里还有一个关键点Object.assign做的是浅合并嵌套对象contact会被整体替换成新对象。如果 el-form-item 的prop是contact.phone替换后路径依然存在校验正常。但如果你用了v-modelform.contact这种整体绑定到某个非表单组件上替换引用可能导致组件内部状态不同步这种情况就改成深拷贝或逐层赋值。顺带说一句clearValidate和resetFields的区别前者只清校验状态去掉红框和错误文案不动数据后者会动数据。很多人以为点一下重置按钮表格就干净了结果错误提示还在就是因为clearValidate没被调用——不过正常用resetFields的话它在内部也会清状态问题主要出现在手动赋值绕过resetFields的场景。2.3 嵌套对象与数组型 model 的设计取舍表单数据怎么组织是个设计问题而不是技术问题但它直接决定了prop写起来顺不顺手。我的经验是按照 UI 分组来组织嵌套层级而不是按照接口返回结构硬搬。举个典型例子。接口返回的是扁平结构{ userName, userPhone, companyName, companyAddress }。如果你直接把这份数据当model那所有prop就是一级字段写起来简单。但如果页面上有个人信息公司信息两个分组各自有标题、说明、独立的校验区域将来还可能拆成独立子组件那我建议重构成{ user: { name, phone }, company: { name, address } }提交前再拍平。重构的代价只有一个提交时要写一层映射。收益是prop变成了user.name、company.address语义一目了然而且子组件可以整体接收model.user和prop-prefix。关于子组件里 prop 怎么写这个具体问题我在第 3.3 节会展开。数组型 model 的坑更隐蔽。假设有list: [{ name: }, { name: }]prop写list.0.name。这段代码在数据不增删时完全正常。一旦有了删除中间一行问题就来了删掉 index 1 之后原来的 index 2 变成了 index 1但 Vue 的 key 如果是按索引生成的DOM 复用会让校验状态错位——第一行的红框可能跑到第二行去。根因在于 el-form-item 的注册和 prop 绑定是绑死在字符串路径上的。索引变化路径就变了但组件实例可能被复用了。所以动态数组表单必须满足两条一是列表项要有稳定唯一的 key用 id 而不是 index二是删除行之后要手动clearValidate或者用validateField重新校验受影响的行。后面第 7.1 节我会给完整代码。3. prop 属性路径解析与动态表单的写法prop的语法糖不多但每一种写法对应的场景边界很清楚。我把它们分成三类一级字段、嵌套对象、数组下标。这三类覆盖了 95% 的中后台表单剩下的 5% 是这三类的组合。有个总原则要先立住prop 字符串必须和 model 上的实际访问路径逐字对应。model.user.address.city对应的 prop 就是user.address.city中间不能少一层也不能多一层。多一层的错误特别隐蔽比如propuserInfo.name但 model 上是form.user.name校验时getPropByPath返回undefined如果规则里没有required校验会直接通过你只会觉得规则好像没生效。3.1 一级、嵌套、数组三种 prop 写法先给一个对照表这三类的写法差异和注意事项一目了然数据形态prop 写法典型用途易错点一级字段propname简单表单注意与输入框 v-model 字段一致嵌套对象propuser.phone分组、子组件中间层级必须预先初始化数组下标proplist.0.name固定几行、表格内编辑索引变动需清校验状态动态数组proplist.${index}.name可增删行必须配合唯一 key深层组合proplist.0.contact.email复杂业务保证每一层都是对象写法本身都是字符串Vue 2 的模板里用:proplist. index .name就行了Vue 3 的模板用反引号模板字符串更清爽:proplist.${index}.name。注意这里外层用的是:prop而不是prop因为要传表达式。有个小细节值得单独说Element Plus 里 form-item 的 prop 类型声明是 string但你也能看到官方在动态场景推荐用模板字符串拼。这个拼接过程在每次渲染时重新执行所以只要 index 变了传给 form-item 的 prop 就是新的form-item 内部会重新计算 fieldValue。这就是为什么删除中间行之后新位置的字段能正常取值——它按新路径重新取了。3.2 动态表格行里的 prop 拼接与 key 管理动态行的完整写法我一般会这样组织el-form refformRef :modelform :rulesrules el-form-item v-for(item, index) in form.list :keyitem.id :label联系人 ${index 1} :proplist.${index}.name :rules[{ required: true, message: 请输入姓名, trigger: blur }] el-input v-modelitem.name placeholder请输入姓名 / el-button link typedanger clickremoveRow(index)删除/el-button /el-form-item /el-form这里有三个设计选择需要解释。第一:keyitem.id而不是index。用 index 做 key 是动态列表里最经典的错误。Vue 复用了 DOM 节点但 el-form-item 内部的initialValue和校验状态是跟着组件实例走的删除一行之后原本第 3 行的组件实例可能被复用成第 2 行它记着的是第 3 行的初始值。用 id 做 key 能强制 Vue 销毁重建问题消失。第二:rules写在 form-item 上而不是统一写在 el-form 的:rules里。对于动态列表每行的规则通常是一样的写在行上更直观也避免了在 el-form 层面写list.${index}.name这种无法静态展开的 key。代价是规则对象在每次渲染时都会重建对于超长列表几百行会有性能开销。如果你真的遇到这种量级把规则对象抽成常量提到外面即可。第三删除行之后要补一次状态清理。因为removeRow里做了splice虽然 key 是 id 不会复用组件但被删行之外的字段路径都变了list.2.name变成list.1.name如果之前这些字段有校验错误错误状态是挂在组件实例上的路径变化后组件重新挂载状态其实是干净的。但如果你用了validateField做过局部校验最好在$nextTick里clearValidate一次保证没有残留。const removeRow async (index) { form.list.splice(index, 1) await nextTick() formRef.value?.clearValidate() }3.3 多层组件嵌套下的 prop 传递把表单拆成子组件是中大型项目的必然选择。问题来了子组件里的 el-form-item 要怎么拿到正确的 prop我的做法是让子组件接收一个propPrefix内部自己拼!-- 子组件 ContactForm.vue -- script setup defineProps({ model: { type: Object, required: true }, propPrefix: { type: String, default: } }) const buildProp (key) (props.propPrefix ? ${props.propPrefix}.${key} : key) /script template el-form-item label手机号 :propbuildProp(phone) el-input v-modelmodel.phone / /el-form-item /template父组件这样用el-form refformRef :modelform :rulesrules ContactForm :modelform.contact prop-prefixcontact / /el-form这个模式成立的前提是el-form 和 el-form-item 之间的 provide/inject 关系没有被打破。只要子组件是 el-form 的后代组件inject 就能拿到 elForm 实例form-item 就能正常注册和校验哪怕中间隔了好几层。所以拆组件本身不影响校验影响校验的只有 prop 路径算错。有一个反例要注意如果你在子组件里自己又套了一个el-form那内部的 form-item 会注册到内部这个 form 上外部表单统一validate()时不会校验到它们。这是有意为之的设计可以用来做表单里的子表单。但如果这不是你的意图就会出现提交时有一部分字段没校验的诡异现象。排查方法很简单看那个字段的 prop 对应路径在外部 form 的 model 里存不存在存在但没校验八成是被内层 el-form 截胡了。4. 校验规则 rules 的进阶配置规则这一层官方文档给的示例足够应付简单场景真正让人头疼的是触发时机、异步校验和类型判定。这一节我按什么时候触发和怎么判对错两条线来拆。4.1 trigger 到底什么时候触发trigger的取值最常用的是blur和change可以传数组同时生效比如trigger: [blur, change]。默认值是change——这一点很多人不知道写了规则但没写 trigger结果输入框刚敲第一个字红字就弹出来了用户体验很差。我的一般选择是文本输入类统一用blur选择类下拉、单选、日期、开关用change。文本用blur是为了不让用户在输入过程中被频繁打扰选择类必须用change因为下拉框的交互路径是先选再失焦用blur会导致用户选完了错误提示还挂着体验割裂。更省事的做法是在 el-form 上不写 trigger而是把常用规则抽成一个统一的规则工厂// rules.js export const required (message, trigger blur) ({ required: true, message, trigger }) export const requiredSelect (message) ({ required: true, message, trigger: change })然后在组件里rules: { name: [required(请输入姓名)], type: [requiredSelect(请选择类型)] }。这样既统一了风格也避免了每次都纠结 trigger 写哪个。项目大了之后规则工厂还能统一加 i18n、加最大长度限制、加统一的错误样式。还有一个容易被忽视的开关el-form 的validate-on-rule-change默认true。它的含义是当rules属性发生变化时立即对整个表单做一次校验。想象一个场景下拉框选择证件类型切换后动态给它追加一条证件号码的规则。你在watch里改rulesvalidate-on-rule-change默认开启界面上所有字段立刻被校验一遍用户还没填任何东西满屏红字。这是新手最容易踩的体验坑。解决方案是给 el-form 加上:validate-on-rule-changefalse只在用户交互或提交时校验。4.2 自定义 validator 的同步与异步写法自定义校验函数是规则体系里自由度最高的部分也是最容易写错的部分。先说一个铁律validator 必须通过callback返回结果或者返回一个 reject 的 Promise不能靠return false。同步写法const checkName (rule, value, callback) { if (!value) return callback(new Error(请输入名称)) if (/[\u4e00-\u9fa5]/.test(value)) { return callback(new Error(名称不能包含中文)) } callback() }注意callback()必须调用哪怕是成功分支。我曾经排查过一个校验永远不通过的问题最后发现是if分支里callback(new Error(...))之后没return程序继续往下走又调了一次callback()async-validator 认为结果冲突判为失败。异步写法比如查重const checkUnique async (rule, value, callback) { if (!value) return callback() try { const { data } await api.checkName(value) data.exists ? callback(new Error(名称已存在)) : callback() } catch (e) { callback() // 网络异常时不阻塞用户 } }异步校验有个经典陷阱先输入 A 再快速输入 AB两次请求返回顺序可能是反的。如果你把结果写到了组件状态里就会出现显示的是旧值的结果。async-validator 内部对同一个字段的校验做了处理但请求本身没取消。稳妥做法是给请求加个序号或者用 AbortController只认最后一次的响应。还有一点异步 validator 里的callback不要被await之后的代码绕过。上面那个 catch 里必须调 callback否则校验会一直挂着表单的validate()Promise 永远不 resolve提交按钮点下去像死机一样。这个 bug 我见过至少三次每次都卡半天。4.3 数组、数字、联动的类型陷阱required的判定和type强相关这是最反直觉的一点。同样写{ required: true, message: 必填 }作用在不同类型上结果完全不同字段类型初始值required 判定说明字符串判定为空报错符合直觉数字0判定为有值通过0 不算空数字null判定为空报错需要特殊处理数组[]判定为空报错空数组不算有值数组[a]判定为有值通过正常布尔false判定为有值通过false 不算空这里最坑的是数字字段初始值给0的情况。比如排序号字段初始 0规则写 required用户什么都不改直接提交校验通过后端收到 0。如果你希望排序号必填初始值就得给null并让用户主动填。数组字段要加上type: array否则 async-validator 会按字符串处理[]转成字符串是可能碰巧通过也可能报出奇怪的错误。完整写法是{ type: array, required: true, message: 请至少选择一个 }。联动校验有两种实现方式。一种是把依赖值放进 validator 的闭包里const validateConfirm (rule, value, callback) { value ! form.password ? callback(new Error(两次输入密码不一致)) : callback() }这个写法的前提是form在闭包作用域内可访问。另一种是监听密码字段变化手动触发确认字段的校验watch(() form.password, () { if (form.confirmPassword) { formRef.value?.validateField(confirmPassword) } })我更倾向第二种因为它只在确认框已经填过时才重新校验避免用户刚改密码、确认框还空着就弹红字。5. 校验流程编排validate、validateField 与错误定位前四节讲的是零件这一节讲装配。el-form 暴露了三个核心方法用错场景会带来很别扭的体验。5.1 三个 API 的职责边界方法作用范围触发校验时机典型场景validate(callback)整个表单立即提交前总校验validateField(props, callback)指定字段立即联动、分步、局部校验clearValidate(props)指定字段或全部清除状态不触发重置、切换、动态增删resetFields(props)指定字段或全部重置数据 清状态取消编辑、新建表单validate在 Vue 3 / Element Plus 里返回 Promise可以await校验失败会 reject 一个包含所有错误字段的对象。这个 reject 对象非常有用它的 key 就是出错的 prop 路径try { await formRef.value.validate() await submit() } catch (fields) { console.log(校验失败字段, fields) // { contact.phone: [{ message: ... }] } // 可以在这里把失败字段上报埋点 }这里有个必须处理的实际问题未捕获的 Promise rejection。如果你写formRef.value.validate()而后面没接.catch校验失败时控制台会抛一条红色警告虽然不影响功能但会干扰排查真正的问题。养成习惯validate要么await加try/catch要么.catch(() {})明示忽略。5.2 提交场景的完整编排模板我把提交场景的编排固定成一个模板几乎所有表单都能套const submitting ref(false) const handleSubmit async () { if (submitting.value) return try { await formRef.value.validate() } catch (e) { scrollToFirstError() return } submitting.value true try { await submitForm(toRaw(form)) ElMessage.success(保存成功) emit(success) } catch (e) { ElMessage.error(e.message || 保存失败请稍后重试) } finally { submitting.value false } }几个细节解释一下。submitting做防抖因为用户双击提交按钮是很常见的行为尤其表单控件多、校验慢的时候。校验失败走scrollToFirstError把用户视线拉到错误位置而不是让他在长长的表单里自己找。toRaw(form)是为了去掉响应式代理再提交给接口避免某些序列化库处理 Proxy 时出错这个坑在传 FormData 或做深拷贝时特别明显。关于scrollToFirstErrorElement Plus 2.3 之后 el-form 提供了scroll-to-error属性配合scroll-into-view-options可以直接用el-form refformRef :modelform :rulesrules scroll-to-error :scroll-into-view-options{ behavior: smooth, block: center } 老版本没有这个属性就自己实现validate的 catch 回调里拿到的错误对象取第一个 key然后document.querySelector找到对应的 form-item 滚过去。手写版本要注意的是错误对象的 key 顺序不保证和页面顺序一致真正靠谱的做法是遍历 form-item 的 DOM 顺序找到第一个带is-error类的元素。5.3 分步表单与滚动定位分步表单steps的核心思路是每一步只校验自己那几个字段。用validateField传字段数组const stepFields [ [name, phone], [company, position], [remark] ] const next async () { try { await formRef.value.validateField(stepFields[currentStep.value]) currentStep.value } catch (e) { ElMessage.warning(请先完善当前步骤的信息) } }需要注意的是validateField的失败回调形态和validate不同它 reject 的是一个错误信息字符串在 Element Plus 里是字段名数组或者错误对象版本间有差异不能依赖它的结构判断失败用try/catch就够了。另一个细节切步骤时不要 clearValidate。因为用户回到上一步之前填过的字段的错误提示应该还在让他知道哪里没改。只有在重置整个表单时才清。这点和很多人的直觉相反实际用起来会舒服很多。6. 常见问题排查速查表这一节是我这些年攒下来的问题清单按出现频率排序。遇到问题先在这里找能省掉大半调试时间。6.1 高频报错与对应原因现象最可能的原因修复方式完全没校验点提交直接过el-form 没绑 model或 form-item 没写 prop检查两者是否齐备控制台警告 model is requiredel-form 上漏写:model补上绑定规则写了但某个字段不生效prop 路径和 model 不符取值 undefined打印 model 核对路径提交时部分字段不校验字段在嵌套的 el-form 里拆掉内层 form 或用其自身 validateresetFields 没反应字段是 v-if 后挂载的或初始值不是引用同一对象改用手动重置校验状态串行动态列表用了 index 做 key换成唯一 id输入第一个字就报错默认 trigger 是 change显式写 trigger: blur改了 rules 满屏红字validate-on-rule-change 默认开启显式设为 false提交按钮点了像卡住validator 里 callback 没被调用检查所有分支都有 callback数组字段 required 不生效没写 type: array补上类型6.2 我踩过的那几个坑第一个坑动态 rules 导致的全表单重校验。一个用户类型下拉框切到企业时给税号字段加 required。我在watch里改 rules页面瞬间全部字段标红。当时以为是 async-validator 的问题翻了半天源码才想起validate-on-rule-change。加上:validate-on-rule-changefalse后清清爽爽。这个属性我现在的做法是只要表单存在动态 rules就一律加上无脑加不会错。第二个坑数字输入框的 0 被当成空。一个折扣率字段范围 0 到 100初始值 0。用户不填直接提交后端收到 0 当成没设置。排查下来是前端把 0 当默认值传了。后来的处理是把初始值改成null并且规则里加自定义校验明确区分未填写和填了 0。第三个坑弹窗表单的校验状态残留。弹窗用v-if控制第一次打开校验失败有红字关闭再打开红字还在。原因是弹窗关闭时组件销毁了但 el-form 的 fields 列表没清干净或者父组件复用了同一个 ref。解决方案是在closed事件里调clearValidate和resetForm顺序不能反先重置数据再清状态否则清的还是旧状态的字段。第四个坑deep监听数组导致校验风暴。表单里有个标签输入组件我在表单上watch(form, ..., { deep: true })做自动草稿保存结果每敲一个字就触发一次校验和一次保存请求。这个坑的教训是深度监听的粒度和校验粒度要分开自动保存应该用防抖监听校验应该交给 trigger不要混在一起。第五个坑v-model绑错层级。子组件里el-input v-modelmodel.phone父组件传的model是form.contact。看起来没问题但如果子组件里写的是v-modelmodel整体替换而 model 又是 propsVue 会警告不能直接修改 props。这个坑的表现是输入框能打字但父组件数据不更新因为子组件修改的是本地副本。正确做法是用defineModel或emit(update:modelValue)。7. 复杂业务场景实战最后一部分我把三个真实场景的完整写法放出来都是可以直接抄的。7.1 动态增删行的校验const form reactive({ list: [] }) const rules { name: [{ required: true, message: 请输入姓名, trigger: blur }] } let uid 0 const addRow () { form.list.push({ id: uid, name: }) } const removeRow async (index) { form.list.splice(index, 1) await nextTick() formRef.value?.clearValidate() } const validateAll async () { try { await formRef.value.validate() return true } catch (e) { ElMessage.warning(请检查表单中标红的项) return false } }这里uid用自增而不是Date.now()因为同一毫秒内连续添加会撞 id。如果你后端已经给了唯一的业务 id直接用后端的。有个细节值得补充删除行时如果该行的 input 还在聚焦状态直接 splice 会触发 blur而 blur 会触发校验报出一个刚被删掉的字段的错误。表现就是删掉一行后屏幕上闪过一个红字提示然后消失。避免方式是在删除前先blur当前活动元素const removeRow async (index) { document.activeElement?.blur() form.list.splice(index, 1) await nextTick() formRef.value?.clearValidate() }7.2 跨字段联动校验结束时间必须晚于开始时间是经典需求。我的实现是监听开始时间然后校验结束时间const validateEnd (rule, value, callback) { if (!value) return callback() if (!form.startTime) return callback() const start dayjs(form.startTime) const end dayjs(value) end.isAfter(start) ? callback() : callback(new Error(结束时间必须晚于开始时间)) } watch(() form.startTime, () { if (form.endTime) { formRef.value?.validateField(endTime) } })两个时间字段都要有才触发联动这样用户从后往前填也不会被误报。另外dayjs的比较要注意时区如果两个值都来自同一个日期选择器时区是统一的不用特殊处理如果一个是接口返回的 UTC 字符串一个是本地选择的值就要先统一到同一时区再比。7.3 弹窗表单的状态清理弹窗表单最容易出问题的是打开-关闭-再打开这条路径。我的模板是el-dialog v-modelvisible closedhandleClosed el-form refformRef :modelform :rulesrules !-- ... -- /el-form /el-dialogconst visible ref(false) const formRef ref() const open (row) { Object.assign(form, createForm(row)) visible.value true } const handleClosed () { formRef.value?.clearValidate() Object.assign(form, createForm()) }关键点是closed而不是close。close是关闭动画开始时触发此时表单还在 DOM 里清理操作可能被动画期间的重渲染覆盖。closed是动画结束、弹窗完全隐藏后触发这时清理最稳。这个细节官方文档提得不多但实测差别很明显——用close偶尔会出现再次打开时红字残留。另一个经验是不要在open里调clearValidate。因为open的时候弹窗可能还没渲染出 el-formformRef是 undefined调用无效。清理放在closed里数据重置放在open里各司其职。这套组合我用在十几个弹窗表单上基本没再出现过状态残留。如果哪天你发现清理还是不生效检查一下formRef是不是被拆成了多个 ref或者弹窗内部又套了一层 el-form——这两个是最常见的例外。我个人在实际项目里的体会是el-form 这套校验体系真正难的不是 API 有多少而是数据、路径、规则三者的对应关系必须时刻保持一致。我现在的习惯是定义model的时候就把prop路径在注释里写一遍改字段的时候先改 model 再改 prop最后才动 rules。顺序反了出了问题就要来回翻代码。另外一个小技巧是把规则抽成独立的rules.js文件里面标注每个规则对应的 prop 路径这样即使表单有一百个字段找错也只需要在文件里搜一次即可。
el-form 校验体系：model、prop、rules 与动态表单实战
1. 先搞明白 el-form 校验体系的三个支点el-form 的校验体系说穿了就是三个东西在互相咬合model、prop、rules。绝大多数人第一次用的时候是照着官方示例抄下来的能跑但一旦遇到动态表单、嵌套对象、弹窗复用、分步提交这些真实场景就会开始出现明明写了规则却不校验重置按钮没反应新增一行校验串到别的行去了这类问题。根本原因不是框架有 bug而是这三个支点在心里的模型是模糊的。我见过太多项目里 el-form 被当成一个包裹容器来用——只要把输入框塞进去随便写个prop规则能红一下就算完事。结果就是后期每加一个字段都要提心吊胆地试一遍。这篇文章我打算把这三个支点各自负责什么、它们之间怎么传值、校验失败时的信息是怎么一路冒到屏幕上的全部摊开讲清楚。适合正在用 Element UI 或 Element Plus 做中后台表单的同学也适合已经用了两三年但一直没系统梳理过的人。先给一个最简的因果链el-form 通过model拿到整份表单数据每个 el-form-item 通过自己的prop从这份数据里定位到属于它的那个字段点击提交时el-form 把定位到的值和绑在 form-item 上的rules一起交给 async-validatorvalidator 跑完把结果回传给 form-itemform-item 决定要不要把边框变红、要不要显示那行小字。整条链路上任何一环错了表现都是不校验或者校验错位。1.1 model 是数据源头不是装饰品model这个词很容易误导人因为它和很多其他框架里表示数据模型的概念混在一起了。在 el-form 里它的职责非常单一它是校验时取值的唯一来源。也就是说el-form-item 在准备校验前会拿着自己的prop去model这个对象上查字典查到什么值就拿什么值去比对规则。这个定位带来两个很容易被忽略的结论。第一v-model绑在 el-input 上的那个字段和 el-form 的model必须是同一个引用。很多同学会写成el-form :modelform但内部输入框绑的是el-input v-modelformInline.name两个不同的对象校验时 el-form 去form里找不到name就会静默失败——页面上什么提示都没有你也搞不清为什么规则没生效。第二model必须是个响应式对象Vue 2 里要用data()里声明的对象Vue 3 里用reactive或者ref包过的对象。如果你在created里临时拼了一个普通对象赋给this.formVue 2 会因为属性没有经过Object.defineProperty处理而丢失响应式表现为输入框能打字但校验拿到的永远是最初的空值。我在一个老项目里排查过类似问题表单里有个从模板带入的功能用户点了之后直接把接口返回的对象整体赋给了this.form结果带入的数据校验全过手动改的内容反而校验不过。原因就是整体赋值把响应式对象的引用换掉了el-form 内部持有的还是老引用。正确做法是用Object.assign(this.form, res.data)或者逐个字段赋值保持引用不变。1.2 prop 是取值路径决定校验能否命中如果把model比作一个文件柜那prop就是抽屉编号。它告诉 el-form-item你要校验的值在文件柜的第几层第几格。这个编号可以是简单的name也可以是带层级的user.address.city还可以是数组下标list.0.phone。关键在于prop 只负责定位不负责创建。如果model.user.address本身是undefined你写propuser.address.city取值链路在中途就断了。async-validator 拿不到值required规则会直接报必填哪怕用户其实填了别的层级。这也是为什么嵌套表单一定要保证中间层级对象先初始化好不能等着用户输入再动态补。另外有个高频误区很多人以为prop只是个标识符随便起个名字只要和规则里的 key 对应就行。这是错的。prop必须是model上真实存在的路径否则校验状态、错误信息、滚动到错误项这些功能都会失效或错位。我在 Code Review 里最常见的改法就是把propphone改成propcontactInfo.phone一行修复三个 bug。1.3 rules 只是声明真正干活的是 async-validatorrules写起来很像配置但它的本质是传给 async-validator 的 schema 描述。async-validator 是一个独立的校验库el-form 只是它的调度器。理解这一层很多行为就顺了为什么type: number要配合v-model.number用为什么required对数组和字符串的表现不一样为什么自定义校验函数要用callback而不是直接return false——这些都是 async-validator 的语义不是 el-form 定的。三层结构里model和prop决定校验谁rules决定怎么校验触发时机trigger决定什么时候校验提交时的validate决定全部跑一遍。下面几节我会按这个顺序把每一层单独拆开讲然后拼回完整流程。2. model 属性从绑定到重置的完整链路model看起来是三个属性里最简单的一个冒号就写完了但它埋的坑最多尤其是和resetFields配合的时候。很多人以为resetFields是把表单清空实际上它干的是把表单恢复到组件挂载那一刻的样子。这两件事在静态表单里表现一样在动态表单、编辑弹窗、条件渲染的场景里就是天壤之别。我们要先接受一个事实el-form 内部维护了一份initialValue快照。每个 el-form-item 在mounted阶段会调用addField把自己注册进 el-form 的fields列表同时通过getPropByPath从当前model上取一次值存成自己的initialValue。之后点击重置el-form 遍历所有 field把prop路径上的值改回对应的initialValue。整个链条里挂载时刻是个硬编码的时间点绕不过去。2.1 声明式初始化字段必须先存在先说一个基础但经常被违背的原则表单里会出现的字段在model初始化时就全部声明出来。不要依赖用户输入后再创建属性也不要在提交前临时挂字段。在 Vue 2 里这是硬约束。data()中没声明的属性后续通过this.form.newField xxx添加是检测不到变化的输入框能显示因为你手动赋的值本身在 DOM 上渲染了但校验、watch、computed 全部拿不到更新。Vue 3 的 Proxy 解决了这个限制但我不建议依赖它因为你的组件可能被复用到 Vue 2 项目里而且给undefined字段做required校验时async-validator 的类型推断会变得很不可控。初始化还有个细节初始值的类型要和字段语义一致。数值字段给0还是null字符串字段给还是undefined会直接影响required的判定结果。async-validator 的required判定逻辑大致是undefined、null、空字符串、空数组都算空。但0和false不算空。所以一个数字输入框如果初始值是null用户填0校验能过如果初始值是而用户填了0但没加.number修饰符拿到的会是字符串0配type: number就会报类型错误。我一般会这样起手// Vue 3 Element Plus const form reactive({ name: , age: null, tags: [], contact: { phone: , email: } })age用null而不是0是为了让未填写和填了0能区分开tags用空数组而不是null是为了让type: array的校验有确定的类型可判。2.2 resetFields 的真相重置的是挂载瞬间的快照这一段是重点。resetFields的行为可以概括成一句话它能重置的只能是它认识的那些 field而它认识的是曾经挂载过并且还在 fields 列表里的 form-item。由此派生出一串真实场景里的坑。第一个是编辑弹窗复用。表格里点编辑弹窗打开父组件把当前行数据传给子组件赋给form。如果这个弹窗组件是被v-if控制显隐的那么每次打开都是重新挂载form-item 的initialValue会记录成这次传进来的行数据用户改了一半点取消resetFields会重置回行数据而不是空表单——这通常是你想要的。但如果弹窗是v-show控制、或者弹窗一直在 DOM 里只是切换数据那initialValue记录的还是第一次打开时的数据第二次打开点重置就会串数据。第二个坑是条件渲染。表单里有个是否开具发票的开关打开后出现一组发票字段。这组字段用v-if包着用户先打开填了值再关掉开关字段销毁但 form-item 的removeField会把它从 fields 里移除所以resetFields不会再管它。等用户再次打开字段重新挂载initialValue记录成上次填的值——因为数据还在form.invoice里没清。于是重置按钮对这个分组就彻底失效了。我的处理策略是对于弹窗、抽屉、条件分组这类场景放弃 resetFields改用显式的手动重置。写一个resetForm函数把初始值抽成一个工厂函数每次重置时整体Object.assign覆盖const createForm () ({ name: , age: null, tags: [], contact: { phone: , email: } }) const form reactive(createForm()) const resetForm () { Object.assign(form, createForm()) // 如果字段被 v-if 移除过还要清掉历史校验状态 formRef.value?.clearValidate() }注意这里还有一个关键点Object.assign做的是浅合并嵌套对象contact会被整体替换成新对象。如果 el-form-item 的prop是contact.phone替换后路径依然存在校验正常。但如果你用了v-modelform.contact这种整体绑定到某个非表单组件上替换引用可能导致组件内部状态不同步这种情况就改成深拷贝或逐层赋值。顺带说一句clearValidate和resetFields的区别前者只清校验状态去掉红框和错误文案不动数据后者会动数据。很多人以为点一下重置按钮表格就干净了结果错误提示还在就是因为clearValidate没被调用——不过正常用resetFields的话它在内部也会清状态问题主要出现在手动赋值绕过resetFields的场景。2.3 嵌套对象与数组型 model 的设计取舍表单数据怎么组织是个设计问题而不是技术问题但它直接决定了prop写起来顺不顺手。我的经验是按照 UI 分组来组织嵌套层级而不是按照接口返回结构硬搬。举个典型例子。接口返回的是扁平结构{ userName, userPhone, companyName, companyAddress }。如果你直接把这份数据当model那所有prop就是一级字段写起来简单。但如果页面上有个人信息公司信息两个分组各自有标题、说明、独立的校验区域将来还可能拆成独立子组件那我建议重构成{ user: { name, phone }, company: { name, address } }提交前再拍平。重构的代价只有一个提交时要写一层映射。收益是prop变成了user.name、company.address语义一目了然而且子组件可以整体接收model.user和prop-prefix。关于子组件里 prop 怎么写这个具体问题我在第 3.3 节会展开。数组型 model 的坑更隐蔽。假设有list: [{ name: }, { name: }]prop写list.0.name。这段代码在数据不增删时完全正常。一旦有了删除中间一行问题就来了删掉 index 1 之后原来的 index 2 变成了 index 1但 Vue 的 key 如果是按索引生成的DOM 复用会让校验状态错位——第一行的红框可能跑到第二行去。根因在于 el-form-item 的注册和 prop 绑定是绑死在字符串路径上的。索引变化路径就变了但组件实例可能被复用了。所以动态数组表单必须满足两条一是列表项要有稳定唯一的 key用 id 而不是 index二是删除行之后要手动clearValidate或者用validateField重新校验受影响的行。后面第 7.1 节我会给完整代码。3. prop 属性路径解析与动态表单的写法prop的语法糖不多但每一种写法对应的场景边界很清楚。我把它们分成三类一级字段、嵌套对象、数组下标。这三类覆盖了 95% 的中后台表单剩下的 5% 是这三类的组合。有个总原则要先立住prop 字符串必须和 model 上的实际访问路径逐字对应。model.user.address.city对应的 prop 就是user.address.city中间不能少一层也不能多一层。多一层的错误特别隐蔽比如propuserInfo.name但 model 上是form.user.name校验时getPropByPath返回undefined如果规则里没有required校验会直接通过你只会觉得规则好像没生效。3.1 一级、嵌套、数组三种 prop 写法先给一个对照表这三类的写法差异和注意事项一目了然数据形态prop 写法典型用途易错点一级字段propname简单表单注意与输入框 v-model 字段一致嵌套对象propuser.phone分组、子组件中间层级必须预先初始化数组下标proplist.0.name固定几行、表格内编辑索引变动需清校验状态动态数组proplist.${index}.name可增删行必须配合唯一 key深层组合proplist.0.contact.email复杂业务保证每一层都是对象写法本身都是字符串Vue 2 的模板里用:proplist. index .name就行了Vue 3 的模板用反引号模板字符串更清爽:proplist.${index}.name。注意这里外层用的是:prop而不是prop因为要传表达式。有个小细节值得单独说Element Plus 里 form-item 的 prop 类型声明是 string但你也能看到官方在动态场景推荐用模板字符串拼。这个拼接过程在每次渲染时重新执行所以只要 index 变了传给 form-item 的 prop 就是新的form-item 内部会重新计算 fieldValue。这就是为什么删除中间行之后新位置的字段能正常取值——它按新路径重新取了。3.2 动态表格行里的 prop 拼接与 key 管理动态行的完整写法我一般会这样组织el-form refformRef :modelform :rulesrules el-form-item v-for(item, index) in form.list :keyitem.id :label联系人 ${index 1} :proplist.${index}.name :rules[{ required: true, message: 请输入姓名, trigger: blur }] el-input v-modelitem.name placeholder请输入姓名 / el-button link typedanger clickremoveRow(index)删除/el-button /el-form-item /el-form这里有三个设计选择需要解释。第一:keyitem.id而不是index。用 index 做 key 是动态列表里最经典的错误。Vue 复用了 DOM 节点但 el-form-item 内部的initialValue和校验状态是跟着组件实例走的删除一行之后原本第 3 行的组件实例可能被复用成第 2 行它记着的是第 3 行的初始值。用 id 做 key 能强制 Vue 销毁重建问题消失。第二:rules写在 form-item 上而不是统一写在 el-form 的:rules里。对于动态列表每行的规则通常是一样的写在行上更直观也避免了在 el-form 层面写list.${index}.name这种无法静态展开的 key。代价是规则对象在每次渲染时都会重建对于超长列表几百行会有性能开销。如果你真的遇到这种量级把规则对象抽成常量提到外面即可。第三删除行之后要补一次状态清理。因为removeRow里做了splice虽然 key 是 id 不会复用组件但被删行之外的字段路径都变了list.2.name变成list.1.name如果之前这些字段有校验错误错误状态是挂在组件实例上的路径变化后组件重新挂载状态其实是干净的。但如果你用了validateField做过局部校验最好在$nextTick里clearValidate一次保证没有残留。const removeRow async (index) { form.list.splice(index, 1) await nextTick() formRef.value?.clearValidate() }3.3 多层组件嵌套下的 prop 传递把表单拆成子组件是中大型项目的必然选择。问题来了子组件里的 el-form-item 要怎么拿到正确的 prop我的做法是让子组件接收一个propPrefix内部自己拼!-- 子组件 ContactForm.vue -- script setup defineProps({ model: { type: Object, required: true }, propPrefix: { type: String, default: } }) const buildProp (key) (props.propPrefix ? ${props.propPrefix}.${key} : key) /script template el-form-item label手机号 :propbuildProp(phone) el-input v-modelmodel.phone / /el-form-item /template父组件这样用el-form refformRef :modelform :rulesrules ContactForm :modelform.contact prop-prefixcontact / /el-form这个模式成立的前提是el-form 和 el-form-item 之间的 provide/inject 关系没有被打破。只要子组件是 el-form 的后代组件inject 就能拿到 elForm 实例form-item 就能正常注册和校验哪怕中间隔了好几层。所以拆组件本身不影响校验影响校验的只有 prop 路径算错。有一个反例要注意如果你在子组件里自己又套了一个el-form那内部的 form-item 会注册到内部这个 form 上外部表单统一validate()时不会校验到它们。这是有意为之的设计可以用来做表单里的子表单。但如果这不是你的意图就会出现提交时有一部分字段没校验的诡异现象。排查方法很简单看那个字段的 prop 对应路径在外部 form 的 model 里存不存在存在但没校验八成是被内层 el-form 截胡了。4. 校验规则 rules 的进阶配置规则这一层官方文档给的示例足够应付简单场景真正让人头疼的是触发时机、异步校验和类型判定。这一节我按什么时候触发和怎么判对错两条线来拆。4.1 trigger 到底什么时候触发trigger的取值最常用的是blur和change可以传数组同时生效比如trigger: [blur, change]。默认值是change——这一点很多人不知道写了规则但没写 trigger结果输入框刚敲第一个字红字就弹出来了用户体验很差。我的一般选择是文本输入类统一用blur选择类下拉、单选、日期、开关用change。文本用blur是为了不让用户在输入过程中被频繁打扰选择类必须用change因为下拉框的交互路径是先选再失焦用blur会导致用户选完了错误提示还挂着体验割裂。更省事的做法是在 el-form 上不写 trigger而是把常用规则抽成一个统一的规则工厂// rules.js export const required (message, trigger blur) ({ required: true, message, trigger }) export const requiredSelect (message) ({ required: true, message, trigger: change })然后在组件里rules: { name: [required(请输入姓名)], type: [requiredSelect(请选择类型)] }。这样既统一了风格也避免了每次都纠结 trigger 写哪个。项目大了之后规则工厂还能统一加 i18n、加最大长度限制、加统一的错误样式。还有一个容易被忽视的开关el-form 的validate-on-rule-change默认true。它的含义是当rules属性发生变化时立即对整个表单做一次校验。想象一个场景下拉框选择证件类型切换后动态给它追加一条证件号码的规则。你在watch里改rulesvalidate-on-rule-change默认开启界面上所有字段立刻被校验一遍用户还没填任何东西满屏红字。这是新手最容易踩的体验坑。解决方案是给 el-form 加上:validate-on-rule-changefalse只在用户交互或提交时校验。4.2 自定义 validator 的同步与异步写法自定义校验函数是规则体系里自由度最高的部分也是最容易写错的部分。先说一个铁律validator 必须通过callback返回结果或者返回一个 reject 的 Promise不能靠return false。同步写法const checkName (rule, value, callback) { if (!value) return callback(new Error(请输入名称)) if (/[\u4e00-\u9fa5]/.test(value)) { return callback(new Error(名称不能包含中文)) } callback() }注意callback()必须调用哪怕是成功分支。我曾经排查过一个校验永远不通过的问题最后发现是if分支里callback(new Error(...))之后没return程序继续往下走又调了一次callback()async-validator 认为结果冲突判为失败。异步写法比如查重const checkUnique async (rule, value, callback) { if (!value) return callback() try { const { data } await api.checkName(value) data.exists ? callback(new Error(名称已存在)) : callback() } catch (e) { callback() // 网络异常时不阻塞用户 } }异步校验有个经典陷阱先输入 A 再快速输入 AB两次请求返回顺序可能是反的。如果你把结果写到了组件状态里就会出现显示的是旧值的结果。async-validator 内部对同一个字段的校验做了处理但请求本身没取消。稳妥做法是给请求加个序号或者用 AbortController只认最后一次的响应。还有一点异步 validator 里的callback不要被await之后的代码绕过。上面那个 catch 里必须调 callback否则校验会一直挂着表单的validate()Promise 永远不 resolve提交按钮点下去像死机一样。这个 bug 我见过至少三次每次都卡半天。4.3 数组、数字、联动的类型陷阱required的判定和type强相关这是最反直觉的一点。同样写{ required: true, message: 必填 }作用在不同类型上结果完全不同字段类型初始值required 判定说明字符串判定为空报错符合直觉数字0判定为有值通过0 不算空数字null判定为空报错需要特殊处理数组[]判定为空报错空数组不算有值数组[a]判定为有值通过正常布尔false判定为有值通过false 不算空这里最坑的是数字字段初始值给0的情况。比如排序号字段初始 0规则写 required用户什么都不改直接提交校验通过后端收到 0。如果你希望排序号必填初始值就得给null并让用户主动填。数组字段要加上type: array否则 async-validator 会按字符串处理[]转成字符串是可能碰巧通过也可能报出奇怪的错误。完整写法是{ type: array, required: true, message: 请至少选择一个 }。联动校验有两种实现方式。一种是把依赖值放进 validator 的闭包里const validateConfirm (rule, value, callback) { value ! form.password ? callback(new Error(两次输入密码不一致)) : callback() }这个写法的前提是form在闭包作用域内可访问。另一种是监听密码字段变化手动触发确认字段的校验watch(() form.password, () { if (form.confirmPassword) { formRef.value?.validateField(confirmPassword) } })我更倾向第二种因为它只在确认框已经填过时才重新校验避免用户刚改密码、确认框还空着就弹红字。5. 校验流程编排validate、validateField 与错误定位前四节讲的是零件这一节讲装配。el-form 暴露了三个核心方法用错场景会带来很别扭的体验。5.1 三个 API 的职责边界方法作用范围触发校验时机典型场景validate(callback)整个表单立即提交前总校验validateField(props, callback)指定字段立即联动、分步、局部校验clearValidate(props)指定字段或全部清除状态不触发重置、切换、动态增删resetFields(props)指定字段或全部重置数据 清状态取消编辑、新建表单validate在 Vue 3 / Element Plus 里返回 Promise可以await校验失败会 reject 一个包含所有错误字段的对象。这个 reject 对象非常有用它的 key 就是出错的 prop 路径try { await formRef.value.validate() await submit() } catch (fields) { console.log(校验失败字段, fields) // { contact.phone: [{ message: ... }] } // 可以在这里把失败字段上报埋点 }这里有个必须处理的实际问题未捕获的 Promise rejection。如果你写formRef.value.validate()而后面没接.catch校验失败时控制台会抛一条红色警告虽然不影响功能但会干扰排查真正的问题。养成习惯validate要么await加try/catch要么.catch(() {})明示忽略。5.2 提交场景的完整编排模板我把提交场景的编排固定成一个模板几乎所有表单都能套const submitting ref(false) const handleSubmit async () { if (submitting.value) return try { await formRef.value.validate() } catch (e) { scrollToFirstError() return } submitting.value true try { await submitForm(toRaw(form)) ElMessage.success(保存成功) emit(success) } catch (e) { ElMessage.error(e.message || 保存失败请稍后重试) } finally { submitting.value false } }几个细节解释一下。submitting做防抖因为用户双击提交按钮是很常见的行为尤其表单控件多、校验慢的时候。校验失败走scrollToFirstError把用户视线拉到错误位置而不是让他在长长的表单里自己找。toRaw(form)是为了去掉响应式代理再提交给接口避免某些序列化库处理 Proxy 时出错这个坑在传 FormData 或做深拷贝时特别明显。关于scrollToFirstErrorElement Plus 2.3 之后 el-form 提供了scroll-to-error属性配合scroll-into-view-options可以直接用el-form refformRef :modelform :rulesrules scroll-to-error :scroll-into-view-options{ behavior: smooth, block: center } 老版本没有这个属性就自己实现validate的 catch 回调里拿到的错误对象取第一个 key然后document.querySelector找到对应的 form-item 滚过去。手写版本要注意的是错误对象的 key 顺序不保证和页面顺序一致真正靠谱的做法是遍历 form-item 的 DOM 顺序找到第一个带is-error类的元素。5.3 分步表单与滚动定位分步表单steps的核心思路是每一步只校验自己那几个字段。用validateField传字段数组const stepFields [ [name, phone], [company, position], [remark] ] const next async () { try { await formRef.value.validateField(stepFields[currentStep.value]) currentStep.value } catch (e) { ElMessage.warning(请先完善当前步骤的信息) } }需要注意的是validateField的失败回调形态和validate不同它 reject 的是一个错误信息字符串在 Element Plus 里是字段名数组或者错误对象版本间有差异不能依赖它的结构判断失败用try/catch就够了。另一个细节切步骤时不要 clearValidate。因为用户回到上一步之前填过的字段的错误提示应该还在让他知道哪里没改。只有在重置整个表单时才清。这点和很多人的直觉相反实际用起来会舒服很多。6. 常见问题排查速查表这一节是我这些年攒下来的问题清单按出现频率排序。遇到问题先在这里找能省掉大半调试时间。6.1 高频报错与对应原因现象最可能的原因修复方式完全没校验点提交直接过el-form 没绑 model或 form-item 没写 prop检查两者是否齐备控制台警告 model is requiredel-form 上漏写:model补上绑定规则写了但某个字段不生效prop 路径和 model 不符取值 undefined打印 model 核对路径提交时部分字段不校验字段在嵌套的 el-form 里拆掉内层 form 或用其自身 validateresetFields 没反应字段是 v-if 后挂载的或初始值不是引用同一对象改用手动重置校验状态串行动态列表用了 index 做 key换成唯一 id输入第一个字就报错默认 trigger 是 change显式写 trigger: blur改了 rules 满屏红字validate-on-rule-change 默认开启显式设为 false提交按钮点了像卡住validator 里 callback 没被调用检查所有分支都有 callback数组字段 required 不生效没写 type: array补上类型6.2 我踩过的那几个坑第一个坑动态 rules 导致的全表单重校验。一个用户类型下拉框切到企业时给税号字段加 required。我在watch里改 rules页面瞬间全部字段标红。当时以为是 async-validator 的问题翻了半天源码才想起validate-on-rule-change。加上:validate-on-rule-changefalse后清清爽爽。这个属性我现在的做法是只要表单存在动态 rules就一律加上无脑加不会错。第二个坑数字输入框的 0 被当成空。一个折扣率字段范围 0 到 100初始值 0。用户不填直接提交后端收到 0 当成没设置。排查下来是前端把 0 当默认值传了。后来的处理是把初始值改成null并且规则里加自定义校验明确区分未填写和填了 0。第三个坑弹窗表单的校验状态残留。弹窗用v-if控制第一次打开校验失败有红字关闭再打开红字还在。原因是弹窗关闭时组件销毁了但 el-form 的 fields 列表没清干净或者父组件复用了同一个 ref。解决方案是在closed事件里调clearValidate和resetForm顺序不能反先重置数据再清状态否则清的还是旧状态的字段。第四个坑deep监听数组导致校验风暴。表单里有个标签输入组件我在表单上watch(form, ..., { deep: true })做自动草稿保存结果每敲一个字就触发一次校验和一次保存请求。这个坑的教训是深度监听的粒度和校验粒度要分开自动保存应该用防抖监听校验应该交给 trigger不要混在一起。第五个坑v-model绑错层级。子组件里el-input v-modelmodel.phone父组件传的model是form.contact。看起来没问题但如果子组件里写的是v-modelmodel整体替换而 model 又是 propsVue 会警告不能直接修改 props。这个坑的表现是输入框能打字但父组件数据不更新因为子组件修改的是本地副本。正确做法是用defineModel或emit(update:modelValue)。7. 复杂业务场景实战最后一部分我把三个真实场景的完整写法放出来都是可以直接抄的。7.1 动态增删行的校验const form reactive({ list: [] }) const rules { name: [{ required: true, message: 请输入姓名, trigger: blur }] } let uid 0 const addRow () { form.list.push({ id: uid, name: }) } const removeRow async (index) { form.list.splice(index, 1) await nextTick() formRef.value?.clearValidate() } const validateAll async () { try { await formRef.value.validate() return true } catch (e) { ElMessage.warning(请检查表单中标红的项) return false } }这里uid用自增而不是Date.now()因为同一毫秒内连续添加会撞 id。如果你后端已经给了唯一的业务 id直接用后端的。有个细节值得补充删除行时如果该行的 input 还在聚焦状态直接 splice 会触发 blur而 blur 会触发校验报出一个刚被删掉的字段的错误。表现就是删掉一行后屏幕上闪过一个红字提示然后消失。避免方式是在删除前先blur当前活动元素const removeRow async (index) { document.activeElement?.blur() form.list.splice(index, 1) await nextTick() formRef.value?.clearValidate() }7.2 跨字段联动校验结束时间必须晚于开始时间是经典需求。我的实现是监听开始时间然后校验结束时间const validateEnd (rule, value, callback) { if (!value) return callback() if (!form.startTime) return callback() const start dayjs(form.startTime) const end dayjs(value) end.isAfter(start) ? callback() : callback(new Error(结束时间必须晚于开始时间)) } watch(() form.startTime, () { if (form.endTime) { formRef.value?.validateField(endTime) } })两个时间字段都要有才触发联动这样用户从后往前填也不会被误报。另外dayjs的比较要注意时区如果两个值都来自同一个日期选择器时区是统一的不用特殊处理如果一个是接口返回的 UTC 字符串一个是本地选择的值就要先统一到同一时区再比。7.3 弹窗表单的状态清理弹窗表单最容易出问题的是打开-关闭-再打开这条路径。我的模板是el-dialog v-modelvisible closedhandleClosed el-form refformRef :modelform :rulesrules !-- ... -- /el-form /el-dialogconst visible ref(false) const formRef ref() const open (row) { Object.assign(form, createForm(row)) visible.value true } const handleClosed () { formRef.value?.clearValidate() Object.assign(form, createForm()) }关键点是closed而不是close。close是关闭动画开始时触发此时表单还在 DOM 里清理操作可能被动画期间的重渲染覆盖。closed是动画结束、弹窗完全隐藏后触发这时清理最稳。这个细节官方文档提得不多但实测差别很明显——用close偶尔会出现再次打开时红字残留。另一个经验是不要在open里调clearValidate。因为open的时候弹窗可能还没渲染出 el-formformRef是 undefined调用无效。清理放在closed里数据重置放在open里各司其职。这套组合我用在十几个弹窗表单上基本没再出现过状态残留。如果哪天你发现清理还是不生效检查一下formRef是不是被拆成了多个 ref或者弹窗内部又套了一层 el-form——这两个是最常见的例外。我个人在实际项目里的体会是el-form 这套校验体系真正难的不是 API 有多少而是数据、路径、规则三者的对应关系必须时刻保持一致。我现在的习惯是定义model的时候就把prop路径在注释里写一遍改字段的时候先改 model 再改 prop最后才动 rules。顺序反了出了问题就要来回翻代码。另外一个小技巧是把规则抽成独立的rules.js文件里面标注每个规则对应的 prop 路径这样即使表单有一百个字段找错也只需要在文件里搜一次即可。
