Vue / 系统课时

封装弹窗表单

封装弹窗表单

新增与编辑页面常常重复处理显隐状态、数据回填、校验、提交锁定和关闭清理。本课把这些职责收拢到一个可复用弹窗组件中,让业务页面只负责准备数据和调用接口,同时避免旧数据残留、重复提交与关闭时机混乱。

学习目标

  • 设计统一的打开、关闭、提交和销毁流程
  • 通过暴露方法复用新增与编辑场景
  • 正确处理表单回填、校验和提交锁定

先划分组件职责

弹窗组件负责界面生命周期:接收标题和表单配置,维护可见状态,执行校验,提交期间禁用按钮,并在关闭后清理内部数据。业务页面负责接口调用和列表刷新,不应把具体请求逻辑硬编码进通用组件。

新增与编辑的主要差异只有初始值和提交函数。统一入口可以定义为 open(mode, initialData):新增时传入空对象,编辑时传入当前记录;组件根据 mode 设置标题,并把数据复制到内部表单,避免直接修改表格行对象。

弹窗表单从打开到销毁的状态流程

实现可复用弹窗组件

下面的组件使用 Vue 3 与 Element Plus。它通过 defineExpose 暴露 open 和 close,通过 submit 事件把校验后的数据交给父组件。关闭后的清理放在 closed 事件中,确保不会在退出动画尚未结束时让表单突然闪空。

vue
<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) 表示失败并继续停留在弹窗中。

vue
<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>

预期输出

text
请求成功后控制台输出:
refresh user list

请求失败时弹窗保持打开,提交按钮恢复可用。

实际接口地址、鉴权方式和错误提示应按项目约定替换。动态用户 ID 会出现在 /api/users/<ID> 路径中。

处理关键边界

不要在 open 时把传入对象直接赋给表单,否则编辑过程会同步修改列表中的原对象。使用 Object.assign 或深拷贝建立内部副本,再在提交成功后刷新列表。

关闭动作需要区分“开始关闭”和“关闭完成”。用户点击取消时只改变 visible;真正的 resetFields 与数据清空放在 closed 回调中。提交期间应禁止重复点击、遮罩关闭和取消操作,防止请求仍在进行时销毁表单。

当表单包含异步校验、上传或级联选择时,提交函数仍应保持同一顺序:校验全部字段、锁定提交、执行请求、根据结果关闭或恢复。不要在多个按钮事件中复制这套流程。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

封装弹窗表单

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通