ProFormPopup 弹层表单

ProFormPopup 是弹窗 / 抽屉 / 整页模式的表单容器，适用于需要手动控制打开关闭的表单场景。

独立页面表单（不需要弹层）使用 ProForm。与 ProTable 联动时由 ProTable 内部自动管理弹层，配置见表单弹层配置。

基本用法

vue

<template>
  <el-button type="primary" @click="open('dialog')">弹窗</el-button>
  <el-button type="success" @click="open('drawer')">抽屉</el-button>
  <ProFormPopup v-model:visible="visible" :config="formConfig" @submit="onSubmit" />
</template>

<script setup>
import { ref, reactive } from 'vue'
const visible = ref(false)
const formConfig = reactive({
  mode: 'dialog',
  width: '480px',
  model: { name: '', status: 1, remark: '' },
  fields: [
    { label: '姓名', key: 'name', component: 'input' },
    { label: '状态', key: 'status', component: 'select',
      options: [{ label: '启用', value: 1 }, { label: '禁用', value: 0 }] },
    { label: '备注', key: 'remark', component: 'textarea', rows: 3, span: 24 }
  ],
  rules: {
    name: [{ required: true, message: '请输入姓名', trigger: 'blur' }]
  },
  add: {
    title: '新增用户',
    api: async (data) => { /* 调用接口 */ }
  }
})
function open(mode) {
  formConfig.mode = mode
  formConfig.formType = 'add'
  visible.value = true
}
function onSubmit(res, formData) { console.log(formData) }
</script>

Props

属性	说明	类型	默认值
visible	是否显示，支持 `v-model:visible`	Boolean	false
config	表单配置对象，继承 ProForm Config，额外支持弹层属性（见下方）	Object	{}
readonly	外部控制只读，优先于 config.readonly	Boolean	undefined

在 ProForm Config 基础上，额外支持：

属性	说明	类型	默认值
mode	弹层模式：`dialog` 弹窗 / `drawer` 抽屉 / `page` 整页	String	'dialog'
title	标题，支持字符串或 `() => string`	String \| Function	-
formType	当前操作类型：`add` / `edit` / `copy` / `save`	String	'add'
width	弹窗 / 抽屉宽度	String	'500px'
formWidth	表单内容区宽度	String	-
params	传给 `fetchInitialData` 的参数；也可在未配置拉取时直接回填	Object	{}
row	原始行数据（含主键）；`copy` + `fetchInitialData` 时优先用此请求详情	Object	{}
add	新增配置，见表单弹层配置 - add	Object	-
edit	编辑配置，见表单弹层配置 - edit	Object	-
save	保存配置，见表单弹层配置 - save	Object	-
closeOnSubmit	提交成功后是否关闭弹层	Boolean	true
closeOnClickModal	是否点击遮罩关闭	Boolean	true
popupAttrs	透传给 `el-dialog` / `el-drawer` 的额外属性	Object	{}
openBefore	打开前钩子：`({ type, row, params }) => boolean \| Promise<boolean>`	Function	-
openAfter	打开后钩子：`({ type, row, params }) => void`	Function	-
beforeSubmit	提交前钩子：`({ formData, action }) => boolean \| Promise<boolean>`；返回 `false` 取消提交，抛出异常显示错误提示	Function	-
afterSubmit	提交成功后回调：`{ res, formData, action }`；`res` 为 `responseFormat` 转换后的响应	Function	-
filterEmptyParams	提交前是否过滤空值；设为 `true` 时过滤 `''`、`null`、`undefined`、空数组	Boolean	false
readonly	只读控制：`boolean` 或 `({ formType, formData }) => boolean`	Boolean \| Function	false

提交流程与钩子职责

ProFormPopup 的字段处理规则与 ProForm 提交流程保持一致：日期范围会拆分，展示字段不会提交，nestedKeys 会在提交时展平。

执行顺序：

text

表单校验 → beforeSubmit → 生成提交参数 → filterEmptyParams → add/edit/save.paramsFormat → add/edit/save.api → add/edit/save.responseFormat → afterSubmit → submit/save 事件

paramsFormat 与 beforeSubmit

beforeSubmit 用于提交前拦截、二次确认或业务校验，返回 false 会取消本次提交。
paramsFormat 用于转换最终提交参数，新增 / 编辑 / 保存分别配置在 add.paramsFormat、edit.paramsFormat、save.paramsFormat 中。

responseFormat 与 afterSubmit

responseFormat 用于转换接口响应，新增 / 编辑 / 保存分别配置在 add.responseFormat、edit.responseFormat、save.responseFormat 中。
afterSubmit 用于提交成功后的副作用，例如关闭外部页面、刷新其他数据等。

接口返回对象中包含全局 codeKey 字段时，会先根据全局 successCode 判断成功 / 失败；失败时不会关闭弹层，也不会触发 responseFormat、afterSubmit 和 submit/save 事件。

属性	说明	类型	默认值
show	是否显示底部区域	Boolean	true
showCancel	是否显示取消按钮	Boolean	true
showSubmit	是否显示提交按钮	Boolean	true
showSave	是否显示保存按钮（需配置 save.api）	Boolean	false
cancelText	取消按钮文案	String	'取消'
submitText	提交按钮文案	String	'提交'
saveText	保存按钮文案	String	'保存'
align	按钮对齐：`left` / `center` / `right`；`page` 模式默认 `left`，`dialog`/`drawer` 默认 `right`	String	见说明

Events

事件名	说明	回调参数
update:visible	弹层显示状态变化	(visible: boolean)
submit	校验通过且请求成功后触发	(response \| formData, formData)
save	点击保存且请求成功后触发	(response)
cancel	点击取消或关闭时触发	-

Ref 方法

方法	说明
`setFormData(data)`	设置整表数据
`patchFormData(patch)`	部分更新表单数据
`getFormData()`	获取当前表单数据（副本）
`validate()`	触发表单校验，返回 Promise
`clearValidate()`	清除校验状态
`close()`	仅关闭弹层（不触发 cancel 事件）
`submit()`	触发表单提交（校验 + 请求）
`setActiveTab(name)`	主动切换到指定 tab
`getActiveTab()`	获取当前激活的 tab name
`loading`	当前是否处于加载中（ref）

Slots

插槽名	说明	作用域参数
form-header	表单内容区顶部
form-footer	表单内容区底部	同上
footer-before	按钮区域左侧	同上
footer-after	按钮区域右侧	同上
[field.slot]	字段自定义控件
extra-[key]	字段下方扩展内容
prepend-[key]	控件前插槽	同上
append-[key]	控件后插槽	同上

与 ProTable 配合

当通过 ProTable 的 form-config 使用时，ProTable 内部自动管理 ProFormPopup 的打开、关闭和数据传递，无需手动使用本组件。

完整的 formConfig（add / edit / save / copy）配置说明见表单弹层配置。

ProFormPopup 弹层表单 ​

基本用法 ​

Props ​

弹层专属配置 ​

提交流程与钩子职责 ​

paramsFormat 与 beforeSubmit ​

responseFormat 与 afterSubmit ​

Footer 弹层配置 ​

Events ​

Ref 方法 ​

Slots ​

与 ProTable 配合 ​