useModalForm

useModalForm 是一个逻辑抽象钩子，专门用于处理 Element Plus 弹窗 + 表单 的业务场景。它封装了 Dialog 的可见性监听、表单重置、编辑数据回显以及提交加载状态。

1. 核心逻辑流程

该 Hook 通过监听 visible 的变化，自动根据 mode 执行不同的初始化逻辑：

• add: 重置表单字段。
• edit / check: 重置字段并触发 setFormData 进行数据回显。

---

2. API 定义

2.1 入参配置 (IUseModalForm)

调用 Hook 时需要传入以下参数：

参数	说明	类型	是否必传
props	包含 visible, mode, data 的响应式对象	IProp	是
emit	组件的 emit 函数，用于关闭弹窗	Function	是
handleSubmit	点击确定时的提交逻辑（需处理校验通过后的业务）	() => Promise<void>	是
add / edit	可选的自定义新增/编辑业务函数	Function	否
resetForm	自定义重置表单逻辑（不传则调用 formRef.resetFields）	() => void	否
setFormData	编辑/查看模式下回显数据的逻辑	() => void	否
successTips	提交成功后的自定义提示函数	() => void	否

2.2 返回对象

属性/方法	说明	类型
formRef	需绑定到 el-form 上的 ref 实例	Ref<FormInstance>
title	根据 mode 自动生成的标题（新增/编辑/查看）	Ref<string>
loading	提交时的加载状态	Ref<boolean>
submitForm	提交入口函数，内置了 validate 校验	() => void
close	关闭弹窗的方法	() => void
handleResSuccess	业务提交成功后的回调（含提示、关闭、触发父组件刷新）	() => void

---

3. 基础用法

3.1 在组件中使用

<script setup lang="ts">
import useModalForm, {IProp, emits} from '@sud-web/vue-hooks/useModalForm'

const props = defineProps<IProp>()
const emit = defineEmits([...emits])

// 1. 初始化 Hook
const { 
  formRef, 
  title, 
  loading, 
  submitForm, 
  handleResSuccess 
} = useModalForm({
  props,
  emit,
  // 核心逻辑：提交表单
  handleSubmit: async () => {
    const api = props.mode === 'add' ? createUser : updateUser
    await api(formData.value)
    handleResSuccess() // 提交成功后的标准处理
  },
  // 回显逻辑：edit 模式下自动触发
  setFormData: () => {
    formData.value =  {
      name: props.data.name,
      ...// 其他字段设置
    }
  }
})

const formData = ref({ name: '', age: 0 })
</script>

<template>
  <el-dialog :model-value="visible" :title="title" @close="close">
    <el-form ref="formRef" :model="formData">
      <el-form-item label="姓名" prop="name" required>
        <el-input v-model="formData.name" :disabled="mode === 'check'" />
      </el-form-item>
    </el-form>
    
    <template #footer>
      <el-button @click="close">取消</el-button>
      <el-button v-if="mode !== 'check'" type="primary" :loading="loading" @click="submitForm">
        确定
      </el-button>
    </template>
  </el-dialog>
</template>

---

4. 模式说明 (IMode)

Hook 内置了三种模式，通过 props.mode 自动切换行为：

• add (新增):

• title 变为 "新增"。

• 打开时自动调用 formRef.resetFields() 清空校验和数据。

• edit (编辑):

• title 变为 "编辑"。

• 打开时调用 setFormData() 填充数据。

• check (查看):

• title 变为 "查看"。

• 通常配合 disabled: true 使用，屏蔽提交按钮。

---

5. 注意事项

1. Form Ref 绑定: 必须将返回的 formRef 绑定到 el-form 组件上，否则自动重置和校验功能将失效。
2. 异步处理: handleSubmit 必须是一个异步函数（或返回 Promise），这样 loading 状态才能正确覆盖整个请求周期。
3. Title 自定义: Hook 使用了默认的 defaultTitle 映射，如果业务需要特殊的标题（如“分配角色”而非“编辑”），可以在外部通过 computed 重新覆盖 Hook 返回的 title。

---