YsDialog 使用：新增/编辑/查看三态弹窗完整实现（表单校验、防重复提交、数据回显）

封装再好最终要在真实弹窗里用出来。本篇拿开源版里字典管理的新增/编辑弹窗当活教材讲一个能上生产的弹窗怎么写。你会发现弹窗组件本身只是个壳真正考验人的是新增、编辑、查看三种状态怎么优雅共用一个弹窗以及防重复提交、表单重置、数据回显这些躲不掉的细节。学会这一个其他弹窗照抄就行。字典管理页有两个弹窗组件mainDialog.vue字典主表新增/编辑和detailDialog.vue字典明细新增/编辑。两者结构几乎一样本篇以mainDialog.vue为主线讲透套路学会一个另一个照抄。一、整体结构一个弹窗扛三种状态 add / edit / view先看模板很朴素的一个表单弹窗YsDialog :titlestate.dialog.title !-- 标题随 type 变化新增/编辑/详情 -- v-modelstate.dialog.isShowDialog !-- 显隐双向绑定YsDialog 内部走 computed 桥 -- closecloseDialog !-- 关闭统一收敛到 closeDialog -- width50% :close-on-click-modalfalse !-- 禁点遮罩关闭防止表单填一半误触丢失 -- :close-on-press-escapefalse !-- 禁 ESC 关闭同上 -- :append-to-bodytrue !-- 嵌套弹窗标配DOM 挂 body层级不受父容器限制 -- el-form refmainFormRef :modelstate.form :rulesrules label-width90px el-row classmb15 el-col :span24 el-form-item label字典名称 propname !-- view 态下所有输入框转只读纯展示 -- el-input v-modelstate.form.name :readonlystate.dialog.type view / /el-form-item /el-col /el-row !-- 编码、描述、状态 字段结构相同略 -- /el-form template #footer el-button clickcloseDialog取 消/el-button !-- view 态隐藏提交按钮submitTxt 随 type 显示新增或更新 -- el-button typeprimary clickonSubmit v-ifstate.dialog.type ! view {{ state.dialog.submitTxt }} /el-button /template /YsDialog三态共用的核心在state.dialog.type取add/edit/view之一。靠这一个字段同一个弹窗当三种用type标题提交按钮表单可编辑add新增字典显示新增可编辑edit编辑字典显示更新可编辑view字典详情隐藏全部 readonlyview态连提交按钮都v-ifstate.dialog.type ! view藏掉输入框全:readonly纯展示。这就是为什么列表页查看往往不用单独写页面复用编辑弹窗设成只读就够了。二、配置驱动dialogConfig 把状态差异收口弹窗标题、按钮文案这些随状态变的东西用配置对象集中管不在openDialog里写一堆 if-else// 三种状态对应的标题与提交按钮文案集中配置改文案只改这一处constdialogConfig{add:{title:新增字典,submitTxt:新增},edit:{title:编辑字典,submitTxt:更新},view:{title:字典详情},// view 态没有提交按钮无需 submitTxt};// 组件状态表单数据 弹窗状态 loading 锁conststatereactive({form:{...initialForm},// 表单数据初始为空白模板dialog:{isShowDialog:false,type:,title:,submitTxt:},loading:false,// 提交防重锁isInitializing:false,// 回显期间的防抖开关});// 打开弹窗type 决定标题/按钮文案row 用于编辑/查看回显constopenDialogasync(type:string,row?:any){state.form{...initialForm};// 第一步永远是先重置表单constconfigdialogConfig[typeaskeyoftypeofdialogConfig];if(!config)return;// 未知 type 直接不弹state.dialog.typetype;state.dialog.titleconfig.title;if(submitTxtinconfig)state.dialog.submitTxtconfig.submitTxt;state.dialog.isShowDialogtrue;// 打开弹窗if((typeedit||typeview)row){state.isInitializingtrue;// 标记回显中防止 watch 误触发state.formobjectCopyForm(row,initialForm)astypeofinitialForm;awaitnextTick();// 等表单渲染/赋值完成state.isInitializingfalse;}};几个实战价值点1. 打开第一步永远是state.form { ...initialForm }彻底重置。不重置上一次编辑的残留数据会留在表单里下次打开看到旧值用户以为我没改怎么保存的是旧的。用初始对象整体覆盖最干净注意这里必须是浅拷贝新对象不能直接引用同一个initialForm。2.dialogConfig做映射避免魔法字符串散落。标题和按钮文案集中一处产品说新增字典要改成新建字典项只改这一行不用满文件找。三个状态各自的差异被配置对象收口openDialog逻辑保持一条直线。3. 编辑/查看才回显数据。objectCopyForm(row, initialForm)把行数据拷进表单。用项目自己的objectCopyForm而不是Object.assign(state.form, row)前者以initialForm字段为基准拷贝能过滤 row 上多余字段、保证类型对齐避免row 里多了临时字段污染表单的暗病。4.isInitializing是个防抖小开关。回显期间置 true、nextTick后归 false。如果表单上有字段变化自动保存草稿之类的 watch 逻辑回显赋值也会触发 watch用这个开关跳过回显引发的误触发。字典弹窗本身没用上这个开关消费方但先把标记埋好是好习惯。三、提交逻辑校验、防重复提交、区分新增/编辑提交是弹窗最容易出 bug 的地方逐行看源码怎么处理constonSubmitasync(){// 1. 先走 el-form 校验await 等 Promise 结果不通过直接返回constvalidawaitmainFormRef.value?.validate();if(!valid)return;// 2. loading 锁防重复提交用户手快连点第二次点击被这里挡住if(state.loading)return;state.loadingtrue;// 3. 按 type 选接口新增走 addPOST编辑走 updatePUTconstapiMethodstate.dialog.typeadd?useDictApi().add:useDictApi().update;try{constresawaitapiMethod(state.form);if(res.code200){ElMessage.success(state.dialog.typeadd?添加成功:更新成功);closeDialog();emit(refresh);// 通知父组件刷新列表弹窗自己不碰列表}else{ElMessage.error(res.msg||操作失败);}}finally{state.loadingfalse;// 无论成功失败锁必须复位}};逐条拆解await validate()不通过直接 return。el-form 校验返回的是 Promise必须await等它。新手常写成同步if (!valid)但忘了valid这时还是 Promise 对象判定永远为真校验形同虚设——这是弹窗提交的头号高频 bug。if (state.loading) return防重复提交。用户手快连点两下保存没这行会发两个请求后端可能插两条重复数据。配合按钮上的:loadingstate.loading双保险第一次提交期间按钮转圈且不可点JS 层再兜一道。apiMethod按 type 选接口。新增走add、编辑走updateURL 和 HTTP 方法不同后端add是 POST、update是 PUTRESTful 常规约定前端一个三元表达最直白。finally里归零 loading。不管成功失败loading 必须复位否则按钮永久转圈用户以为卡死。放finally而不是then就是为了覆盖失败分支。成功后emit(refresh)。弹窗自己不碰列表只负责我存好了。父组件dict/index.vue里MainDialog refmainDialogRef refreshrefreshMainTable() /接到事件去调 YsTable 的refresh()。职责清晰弹窗管存、列表管显。四、关闭逻辑两条关闭路径统一收敛弹窗有两处能关点取消按钮、点右上角 X或遮罩、ESC。取消按钮clickcloseDialogcloseDialog直接state.dialog.isShowDialog false。右上角 X / 遮罩触发el-dialog的close事件YsDialog监听后$emit(close)父组件closecloseDialog又调回closeDialog。所以不管从哪条路径关最终都收敛到closeDialog统一置isShowDialog false。不会出现点 X 关了但表单状态没清——因为下次openDialog开头就重置 form状态清理由打开时重置兜底。注意:close-on-click-modalfalse和:close-on-press-escapefalse——字典弹窗禁用了点遮罩和按 ESC 关闭。为什么表单可能填了一半误触遮罩就丢了体验很差。像确认删除那种二次确认弹窗反而该允许 ESC 关等于取消长表单弹窗该禁掉按场景取舍不是死的规则。五、确认类弹窗ElMessageBox 是另一种对话框列表删除用的不是 YsDialog而是ElMessageBox.confirm——本质是 el-dialog 的另一种形态专门做一句话确认// 删除字典先用 MessageBox 二次确认再调接口最后刷列表constonRowDelMain(row:any){ElMessageBox.confirm(此操作将永久删除字典${row.name}, 是否继续?,提示,{confirmButtonText:确定,cancelButtonText:取消,type:warning,// 警示图标红叹号}).then((){useDictApi().delete(row.id).then((){ElMessage.success(删除成功);mainTableRef.value?.refresh();// 列表刷新交给 YsTable 的 refresh 方法});}).catch((){});// 用户点取消空 catch 吞掉 reject避免控制台报错};这种轻量确认没必要写 YsDialog 组件一行调用最省事。什么时候用 YsDialog、什么时候用ElMessageBox经验法则要填表单/看详情 → YsDialog只确认一个动作 → ElMessageBox。别什么都上 YsDialog杀鸡用牛刀。六、完整可跑示例一个通用的三态表单弹窗把新增/编辑/查看弹窗抽成独立组件脱离字典业务粘进任意 Vue3 项目全局注册了 YsDialog、装了 element-plus就能跑!-- UserDialog.vue通用三态弹窗组件 -- template YsDialog :titletitle v-modelvisible width480px :close-on-click-modalfalse closeonClose el-form refformRef :modelform :rulesrules label-width80px el-form-item label用户名 propusername !-- view 态只读 -- el-input v-modelform.username :readonlyisView / /el-form-item el-form-item label角色 proprole !-- view 态禁用select 用 disabled 而不是 readonly -- el-select v-modelform.role :disabledisView placeholder请选择 el-option label管理员 valueadmin / el-option label普通用户 valueuser / /el-select /el-form-item /el-form template #footer el-button clickvisible false取消/el-button !-- view 态隐藏提交按钮loading 期间按钮转圈不可点 -- el-button v-if!isView typeprimary :loadingloading clicksubmit保存/el-button /template /YsDialog /template script setup langts import { ref, reactive, computed } from vue; import { ElMessage } from element-plus; const emit defineEmits([refresh]); // 提交成功后通知父组件刷新 const visible ref(false); // 弹窗显隐 const loading ref(false); // 提交防重锁 const type refadd | edit | view(add);// 三态标记 const initialForm { id: , username: , role: }; // 表单初始模板 const form reactive({ ...initialForm }); const formRef ref(); // computed 派生是否查看态、标题文案 const isView computed(() type.value view); const title computed(() ({ add: 新增用户, edit: 编辑用户, view: 用户详情 }[type.value]) ); // 校验规则 const rules { username: [{ required: true, message: 请输入用户名, trigger: blur }], role: [{ required: true, message: 请选择角色, trigger: change }], }; // 对外暴露的打开方法type 决定状态row 用于回显 const open (t: add | edit | view, row?: any) { Object.assign(form, initialForm); // 先重置再回显顺序不能反 type.value t; if ((t edit || t view) row) Object.assign(form, row); visible.value true; }; // 提交校验 → 防重锁 → 模拟接口 → 关闭通知刷新 const submit async () { if (!formRef.value) return; const ok await formRef.value.validate(); // await 等校验 Promise if (!ok) return; if (loading.value) return; // 防重复提交 loading.value true; try { await new Promise((r) setTimeout(r, 600)); // 模拟请求替换为真实 API ElMessage.success(type.value add ? 新增成功 : 更新成功); visible.value false; emit(refresh); } finally { loading.value false; // 锁复位 } }; // 关闭时重置表单下次打开是干净状态 const onClose () { Object.assign(form, initialForm); }; // 只暴露 open父组件用法dlgRef.open(edit, row) defineExpose({ open }); /script父页面这样用template div el-button typeprimary clickdlg.open(add)新增/el-button !-- 编辑把整行数据传进去回显 -- el-button clickdlg.open(edit, { id: 1, username: 张三, role: user })编辑/el-button UserDialog refdlg refreshloadList / /div /template script setup langts import { ref } from vue; import UserDialog from ./UserDialog.vue; const dlg ref(); // 模板引用拿到弹窗组件实例 const loadList () { /* 刷新列表 */ }; /script这套弹窗组件defineExpose({ open }) 父组件ref.open(type, row)写法是字典页、用户页、角色页通吃的万能套路。每写一个弹窗复制这套骨架只改表单字段和接口维护成本陡降。七、表单校验进阶跨字段校验与异步校验基础校验required、trigger只是入门两种最容易卡新手的场景要展开说1. 跨字段校验自定义 validator。确认密码要和密码一致、“结束时间晚于开始时间”。el-form 支持validator函数construles{startDate:[{required:true,message:请选择开始时间,trigger:change}],endDate:[{required:true,message:请选择结束时间,trigger:change,// 自定义校验器比较结束时间与开始时间的先后validator:(rule:any,value:any,callback:any){if(valueform.startDatenewDate(value)newDate(form.startDate)){callback(newError(结束时间不能早于开始时间));// 校验失败}else{callback();// 校验通过必须调用}},}],};validator两个分支都要调callback通过调callback()不带参失败调callback(new Error(...))。漏掉通过的callback()表单永远卡在校验中提交按钮点了没反应——这种 bug 线上见过不止一次。2. 异步校验。用户名是否已存在要查后端。validator里await接口再决定validator:async(rule:any,value:any,callback:any){if(!value)returncallback();// 空值交给 required 规则处理constresawaituseUserApi().checkName(value);// 异步查后端if(res.data)callback(newError(用户名已存在));elsecallback();}异步 validator 一定要标asynccallback放在await之后。提交时await formRef.validate()会等所有 validator含异步跑完不用自己套setTimeout去等校验结果。八、弹窗里塞列表选择类弹窗的套路不少弹窗不是填表单而是从一堆数据里选一个/几个比如选负责人、选部门、选商品。这种弹窗里直接放 YsTable 最省事YsDialog title选择用户 v-modelvisible width60% :close-on-click-modalfalse !-- 弹窗里放 YsTablerequest-fn 给数据接口options 给列配置 -- YsTable refpickRef :request-fnuseUserApi().list :optionspickOptions :eventspickEvents / template #footer el-button clickvisiblefalse取消/el-button el-button typeprimary clickconfirmPick确定/el-button /template /YsDialogconfirmPick里读pickRef.getAllSelectedData()拿勾选用户回传父页面。关键点YsTable 在弹窗里能正常算高度ResizeObserver 监听容器尺寸弹窗展开时容器从 0 变实际高度能被接住所以弹窗里的表格和在外面用没区别。这种选择弹窗中后台到处都是套路固化复制粘贴就行。九、重复打开与状态残留副作用清理比你想的重要前面提了关闭后重置表单再补一个更隐蔽的弹窗里有定时器、监听器watch 某字段做实时计算、或开了轮询拉进度关闭时这些副作用要清掉否则一直跑、甚至干扰下次打开。规范做法打开时open启动需要的 watch/定时器关闭动画结束closed时 watch 用.stop()停掉、定时器clearTimeout/clearInterval或用onUnmounted兜底清理。开源版字典弹窗逻辑轻没用到但写复杂弹窗带实时校验、带倒计时一定要记得。很多页面越用越卡、弹窗关了还在发请求的锅都是副作用没清理。顺带补一句全局服务弹窗打开期间调了ElLoading.service()显示全屏 loading关弹窗前一定要loading.close()不然 loading 盖在所有东西上面关不掉。开局const l ElLoading.service()收尾finally或onClosedl.close()。弹窗副作用管理核心就一句开的时候注册了什么关的时候或onUnmounted就一定要有对应注销。十、弹窗尺寸与窄屏适配开源版瞄准后台管理多在桌面端但弹窗尺寸处理好窄屏也不难看。窄表单两三个字段用width480px固定值最稳宽表单一排多个el-col用width60%/80%更自适应。但百分比相对视口手机上 80% 就三百多 px里面一排两列el-col :span12会被挤窄。真要支持移动端弹窗里别用固定两列改一列堆叠或窄屏让弹窗走fullscreen。YsDialog 的全屏按钮就是为这个准备的——窄屏一点全屏表单铺满比硬挤小弹窗好。还有el-form的label-width窄屏别写死 90px响应式或小屏改小。这些不是 YsDialog 职责但它给了fullscreen开关剩下布局调整在业务页做。十一、弹窗与路由要不要把弹窗状态写进 URL你会纠结弹窗开着时用户刷新页面弹窗没了或者想分享正在编辑某某给同事。要不要把状态写进 URL如?dialogeditid123建议普通增删改弹窗别写。原因有三弹窗本质是临时交互刷新没了重开不奇怪把状态塞 URL 要处理打开/关闭与路由的双向同步还要防 URL 篡改越权成本高分享编辑弹窗给别人本就没意义没上下文。只有一种值得写弹窗里是只读详情且确实需要分享链接如看这条工单这时把 id 写进 URL 合理。其余场景让弹窗就是弹窗别背路由的包袱。十二、嵌套弹窗详情弹窗里再开选择弹窗真实业务常弹窗里再开弹窗字典明细弹窗里点选择关联分类或表单里点选择负责人再弹人员列表。前面原理篇讲了嵌套弹窗要append-to-body这里给具体落地方式外层、内层 YsDialog 都加:append-to-bodytrue内层用独立visible2控制。关键点是内层弹窗确定回调拿到数据后通过emit或v-model回传给外层表单字段再关内层外层不受影响。这种弹窗选择 → 回填表单模式在中后台极常见YS 里选用户、选部门、选商品全是这套。记住内层弹窗也遵循三态/重置那套规矩打开先重置自己的查询条件。十三、表单重置的另一种做法用 key 强制重挂载前面讲打开时Object.assign(form, initialForm)重置。还有一招给弹窗内el-form绑:keydialogKey每次open时dialogKeyVue 会销毁旧表单、重建新表单所有字段、校验状态、临时输入一键归零比手动 reset 更彻底。代价是表单组件重新挂载轻微开销但换来绝对干净的初始态复杂弹窗值得用。两种做法不冲突简单弹窗用 Object.assign复杂弹窗用 key 重挂载。十四、关闭动画时序与可访问性提醒弹窗关闭有 300ms 左右的动画这期间组件还在 DOM 里。前面讲关闭后重置表单推荐在open时、而非close时根因就是closed动画结束才真正稳妥——若你在close动画开始就重置可能和用户正在看的旧数据撞一下。所以凡涉及关弹窗时取最终值/清状态挂closed比close安全。可访问性上YsDialog 默认align-center垂直居中、支持 ESC 关闭已是基本友好若做面向公众的弹窗记得焦点管理打开时焦点进弹窗、关闭时退回触发按钮这是无障碍基本功复杂弹窗值得补。踩坑清单速查open一定要先重置表单再回显。顺序反了先回显再重置数据就没了。永远reset → 赋值。编辑和查看别用两个组件。一个type控制 readonly 和按钮显隐复制一套是维护灾难。提交按钮:loading和 JSloading锁要成对。只加按钮 loading 不加 JS 锁用户狂点照样发多次请求。关闭后重置表单。要么open时重置要么close时重置二选一别都漏。推荐open时重置因为close时重置要等动画结束时序偶尔会飘。长表单禁用遮罩/ESC 关闭。别让用户误触丢半小时填的内容。emit(refresh)而不是自己刷列表。弹窗只管自己的事列表刷新交给列表页弹窗才能复用、可测试。select 的禁用用:disabled不是:readonly。readonly对el-select无效view 态漏写 disabled 就还能改。十五、弹窗里的下拉选项字典/枚举数据什么时候加载表单弹窗里十有八九有下拉框状态、类型、部门选项数据从哪来、什么时候请求是个容易含糊的细节。三种时机各有适用1. 页面加载时拉一次推荐给静态选项。枚举类选项getEnumValue和字典选项getDetailByCode基本不变父页面onMounted拉好传给弹窗或存 Pinia 全局共享。弹窗打开零等待这是最常见做法。2.openDialog时拉选项依赖上下文。比如编辑某部门时上级部门选项要排除自己及子部门——选项依赖 row只能在打开时请求。注意在openDialog的回显前拉避免选项还没到、表单值已经回显导致 select 显示原始值。3. 惰性加载el-select 的remote-method或首次 focus 拉取。选项多上千条部门、用户时一次性拉全量太重用远程搜索用户输入关键字才查。这是性能考虑中后台不常用但要知道。一个坑弹窗关闭再打开选项不会自动刷新。如果选项在别处被改了比如管理页加了新类型靠页面重新进入或提交成功后顺手重拉。字典/枚举这类配置级选项接受轻微延迟完全没问题别为了绝对实时把每次打开弹窗都变成两次请求。小结把弹窗写成可复用的套路看完字典两个弹窗你会发现能上生产的弹窗组件代码量不大但处处是为下次不踩坑留下的处理打开重置、回显用基准对象、提交防重、关闭统一、成功抛事件。YsDialog 把这些壳的事接住你只专注表单字段和接口。到这列表页两大件——YsTable 和 YsDialog——都讲透了。后面两篇换到后端聊开源版新增的字典模块和枚举模块看前后端怎么打通。