Vue / 系统课时
封装弹窗表单
封装弹窗表单
新增与编辑页面常常重复处理显隐状态、数据回填、校验、提交锁定和关闭清理。本课把这些职责收拢到一个可复用弹窗组件中,让业务页面只负责准备数据和调用接口,同时避免旧数据残留、重复提交与关闭时机混乱。
学习目标
- 设计统一的打开、关闭、提交和销毁流程
- 通过暴露方法复用新增与编辑场景
- 正确处理表单回填、校验和提交锁定
先划分组件职责
弹窗组件负责界面生命周期:接收标题和表单配置,维护可见状态,执行校验,提交期间禁用按钮,并在关闭后清理内部数据。业务页面负责接口调用和列表刷新,不应把具体请求逻辑硬编码进通用组件。
新增与编辑的主要差异只有初始值和提交函数。统一入口可以定义为 open(mode, initialData):新增时传入空对象,编辑时传入当前记录;组件根据 mode 设置标题,并把数据复制到内部表单,避免直接修改表格行对象。

实现可复用弹窗组件
下面的组件使用 Vue 3 与 Element Plus。它通过 defineExpose 暴露 open 和 close,通过 submit 事件把校验后的数据交给父组件。关闭后的清理放在 closed 事件中,确保不会在退出动画尚未结束时让表单突然闪空。
<script setup lang="ts">
import { nextTick, reactive, ref } from 'vue'
import type { FormInstance, FormRules } from 'element-plus'
type DialogMode = 'create' | 'edit'
type UserForm = {
id?: number
name: string
email: string
}
const emit = defineEmits<{
submit: [payload: UserForm, done: (success: boolean) => void]
}>()
const visible = ref(false)
const submitting = ref(false)
const mode = ref<DialogMode>('create')
const formRef = ref<FormInstance>()
const emptyForm = (): UserForm => ({ name: '', email: '' })
const form = reactive<UserForm>(emptyForm())
const rules: FormRules<UserForm> = {
name: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
email: [
{ required: true, message: '请输入邮箱', trigger: 'blur' },
{ type: 'email', message: '邮箱格式不正确', trigger: 'blur' }
]
}
async function open(nextMode: DialogMode, initialData?: Partial<UserForm>) {
mode.value = nextMode
Object.assign(form, emptyForm(), initialData)
visible.value = true
await nextTick()
formRef.value?.clearValidate()
}
function close() {
if (!submitting.value) visible.value = false
}
async function handleSubmit() {
if (!formRef.value || submitting.value) return
const valid = await formRef.value.validate().catch(() => false)
if (!valid) return
submitting.value = true
emit('submit', { ...form }, (success) => {
submitting.value = false
if (success) visible.value = false
})
}
function handleClosed() {
Object.assign(form, emptyForm())
formRef.value?.resetFields()
}
defineExpose({ open, close })
</script>
<template>
<el-dialog
v-model="visible"
:title="mode === 'create' ? '新增用户' : '编辑用户'"
width="520px"
destroy-on-close
:close-on-click-modal="!submitting"
@closed="handleClosed"
>
<el-form ref="formRef" :model="form" :rules="rules" label-width="80px">
<el-form-item label="姓名" prop="name">
<el-input v-model="form.name" />
</el-form-item>
<el-form-item label="邮箱" prop="email">
<el-input v-model="form.email" />
</el-form-item>
</el-form>
<template #footer>
<el-button :disabled="submitting" @click="close">取消</el-button>
<el-button type="primary" :loading="submitting" @click="handleSubmit">
提交
</el-button>
</template>
</el-dialog>
</template>预期结果:调用 open('create') 时显示空表单;调用 open('edit', row) 时回填当前记录。校验失败不会触发提交,提交期间按钮进入加载状态,成功后关闭,失败后保留用户已填内容。
在业务页面中调用
父页面只需要持有组件引用,并在提交回调中执行新增或更新请求。done(true) 表示请求成功并允许关闭;done(false) 表示失败并继续停留在弹窗中。
<script setup lang="ts">
import { ref } from 'vue'
import FormDialog from './FormDialog.vue'
type User = { id?: number; name: string; email: string }
const dialogRef = ref<InstanceType<typeof FormDialog>>()
function createUser() {
dialogRef.value?.open('create')
}
function editUser(row: User) {
dialogRef.value?.open('edit', row)
}
async function saveUser(payload: User, done: (success: boolean) => void) {
try {
const method = payload.id ? 'PUT' : 'POST'
const url = payload.id ? `/api/users/${payload.id}` : '/api/users'
const response = await fetch(url, {
method,
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload)
})
done(response.ok)
if (response.ok) {
// 实际项目在这里重新请求列表,避免手工拼接产生状态差异。
console.log('refresh user list')
}
} catch {
done(false)
}
}
</script>
<template>
<el-button type="primary" @click="createUser">新增用户</el-button>
<FormDialog ref="dialogRef" @submit="saveUser" />
</template>预期输出
请求成功后控制台输出:
refresh user list
请求失败时弹窗保持打开,提交按钮恢复可用。实际接口地址、鉴权方式和错误提示应按项目约定替换。动态用户 ID 会出现在 /api/users/<ID> 路径中。
处理关键边界
不要在 open 时把传入对象直接赋给表单,否则编辑过程会同步修改列表中的原对象。使用 Object.assign 或深拷贝建立内部副本,再在提交成功后刷新列表。
关闭动作需要区分“开始关闭”和“关闭完成”。用户点击取消时只改变 visible;真正的 resetFields 与数据清空放在 closed 回调中。提交期间应禁止重复点击、遮罩关闭和取消操作,防止请求仍在进行时销毁表单。
当表单包含异步校验、上传或级联选择时,提交函数仍应保持同一顺序:校验全部字段、锁定提交、执行请求、根据结果关闭或恢复。不要在多个按钮事件中复制这套流程。