useModalForm

useModalForm 用于封装 Element Plus 弹窗表单的通用状态：打开时初始化、表单校验、提交 loading、关闭弹窗与提交成功回调。

它用在弹窗子组件内部，与用在外部列表页的 useDialogOut 配对：父组件透传 visible / mode / data / disabled，子组件用 useModalForm 处理表单与提交。

引入

import useModalForm, { emits, propsData, type IProp, type IMode } from '@sud-web/vue-hooks/useModalForm'

@sud-web/vue-hooks 通过子路径导出 Hook，需使用 /useModalForm 引入。

基础用法

弹窗子组件 UserModal.vue 用 defineProps<IProp>() 接收父级状态，useModalForm 提供 formRef / title / loading / submitForm / close：add 模式重置表单，edit / check 模式回显数据，check 模式禁用所有控件并隐藏底部按钮。提交走 submitForm → 校验通过后执行 handleSubmit。下方预览即外部列表页驱动该弹窗的完整流程。

loading

模式

type IMode = 'add' | 'edit' | 'check'

模式	标题	打开时行为
add	新增	重置表单
edit	编辑	重置表单后调用 setFormData 回显
check	查看	重置表单后调用 setFormData 回显

API

Props

组件应通过 defineProps<IProp>() 接收以下 props：

interface IProp<T = any> {
  disabled?: boolean
  visible: boolean
  title?: string
  data: T
  mode: 'add' | 'edit' | 'check'
}

包内同时导出默认值 propsData 与事件名 emits：

const propsData = { disabled: false, visible: false, data: {}, mode: 'add' }
const emits = ['update:visible', 'submit']

入参

useModalForm({ props, emit, handleSubmit, add, edit, resetForm, setFormData, successTips })

参数	类型	必填	说明
props	IProp	是	组件 props，通常来自 defineProps<IProp>()
emit	(event: string, ...args: any[]) => void	是	组件 emit
handleSubmit	() => Promise<void>	是	表单校验通过后的提交逻辑
add	<T>(values: T) => void	否	新增业务方法，由 handleAdd 调用
edit	<T>(values: T) => void	否	编辑业务方法，由 handleEdit 调用
resetForm	() => void	否	自定义重置逻辑；新增模式下 setFormData 不执行，新增表单的初始化全靠它。建议内部先 formRef.resetFields() 清空 + 清校验，再 set「默认值非空」的字段
setFormData	() => void	否	编辑 / 查看打开时的数据回显逻辑
successTips	() => void	否	提交成功提示

返回值

字段	类型	说明
formRef	Ref<FormInstance | undefined>	绑定到 el-form
title	Ref<string | undefined>	根据 mode 自动设置
loading	Ref<boolean>	提交 loading
handleAdd	<T>(values: T) => Promise<void>	调用传入的 add
handleEdit	<T>(values: T) => Promise<void>	调用传入的 edit
submitForm	() => Promise<void>	调用 formRef.validate，通过后执行 handleSubmit
handleResSuccess	() => void	调用 successTips、关闭弹窗并 emit submit
close	() => void	emit update:visible = false

行为细节

场景	行为
props.visible 变为 true	下一个 tick 设置标题并重置表单
传入 resetForm	优先调用 resetForm()，hook 不再调用 resetFields；需在 resetForm 内先 formRef.resetFields() 清空字段并清掉校验残留
未传 resetForm 且存在 formRef	调用 formRef.resetFields()，同时清空字段值与校验状态
mode 为 edit / check	打开时调用 setFormData()
submitForm 校验失败	不调用 handleSubmit
handleResSuccess	先 successTips，再关闭弹窗并 emit submit

当前边界

以下行为保持当前实现，文档不承诺自动兜底：

边界	当前表现
add / edit / handleSubmit 抛错	异常向外抛出，loading 无 finally 兜底
未绑定 formRef 调用 submitForm	直接不执行提交

测试

cd packages/vue/hooks
pnpm test