ProFormDialog 弹窗表单

ProFormDialog 弹窗表单 的基础用法、公开 API 与示例。

基础示例

在弹窗中使用 ProForm。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { ProFormDialog } from "@/components/pro/form-dialog";

const visible = ref(false);
const model = ref({ name: "IDX Web" });
const form = { columns: [{ prop: "name", label: "名称", el: "el-input" }], showFooter: false };
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <el-button type="primary" @click="visible = true">打开</el-button>
      <ProFormDialog v-model="model" v-model:visible="visible" :dialog="{ title: '弹窗表单' }" :form="form" />
    </div>
  </ClientOnly>
</template>

隐藏源代码

提交表单

展示弹窗表单的默认值和提交回调。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { ProFormDialog } from "@/components/pro/form-dialog";

const visible = ref(false);
const model = ref({ name: "材料库", owner: "采购组" });
const result = ref("确认后显示提交数据");
const form = {
  columns: [
    { prop: "name", label: "名称", el: "el-input", formItemProps: { rules: [{ required: true, message: "请输入名称" }] } },
    { prop: "owner", label: "负责人", el: "el-input" },
  ],
};

const handleConfirm = (value: Record<string, unknown>) => {
  result.value = JSON.stringify(value);
  visible.value = false;
};
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <el-button type="primary" @click="visible = true">打开提交表单</el-button>
      <ProFormDialog
        v-model="model"
        v-model:visible="visible"
        :dialog="{ title: '新增资料', height: 220 }"
        :form="form"
        @confirm="handleConfirm"
      />
      <p class="form-dialog-result">{{ result }}</p>
    </div>
  </ClientOnly>
</template>

<style scoped>
.form-dialog-result {
  margin: 12px 0 0;
  color: #667085;
}
</style>

隐藏源代码

引入方式

import { ProFormDialog } from "@/components/pro/form-dialog";

Props

参数	说明	类型	默认值	必填
dialog	ProDialog 的 Props	ProDialogProps & Partial<DialogProps>	{}	否
form	ProForm 的 Props	ProFormNamespace.Props & ProFormNamespace.OnEmits	{}	否
modelValue	组件双向绑定值。	Recordable	() => reactive({})	否
visible	控制组件显示或隐藏。	unknown	false	否

Events

事件名	说明	回调参数
change	表单值改变事件	value: unknown, model: Recordable, column: FormItemColumnProps, oldValue: unknown
confirm	确认按钮点击事件	model: Recordable
cancel	取消按钮点击事件	-
update:modelValue	双向绑定值更新时触发。	value: Recordable
update:visible	显示状态更新时触发。	value: unknown

Slots

插槽名	说明	参数
dialog-footer	dialog-footer 内容插槽。	-

Expose

名称	说明	类型
proFormInstance	暴露 proFormInstance 给外部调用。	-
handleConfirm	执行确认操作。	-
handleCancel	执行取消操作。	-
open	打开组件。	-
close	关闭组件。	-

Module API

名称	说明	类型
ProFormDialog	导出 ProFormDialog 供业务侧复用。	useInstall(index)

Types

ProFormDialogProps

导出 ProFormDialogProps 供业务侧复用。

字段	说明	类型	默认值	必填
dialog	ProDialog 的 Props	ProDialogProps & Partial<DialogProps>	-	否
form	ProForm 的 Props	ProFormNamespace.Props & ProFormNamespace.OnEmits	-	否

ProDialogProps

导出 ProDialogProps 供业务侧复用。

字段	说明	类型	默认值	必填
title	顶部标题	string	''	否
fullscreen	是否默认全屏	boolean	false	否
fullscreenIcon	是否显示渲染全屏图标	boolean	true	否
height	内容高度	string | number	400	否
maxHeight	内容最大高度	string | number	-	否
heightOffsetInFullscreen	全屏时内容高度偏移量	number	0	否
showFooter	是否渲染底部	boolean	true	否
footerAlign	底部对齐方式	"left" | "right" | "center"	'right'	否
confirmLoading	确认按钮 loading	boolean	false	否
confirmText	确认按钮文字	string	'确认'	否
cancelText	关闭按钮文字	string	'关闭'	否
render	自定义内容渲染	() => RenderTypes	-	否
renderHeader	自定义头部渲染	(scope: unknown) => RenderTypes	-	否
footerTopRender	自定义底部上方渲染	() => RenderTypes	-	否
renderFooterBefore	自定义底部前方渲染	(scope: DialogRenderParams) => RenderTypes	-	否
renderFooter	自定义底部渲染	(scope: DialogRenderParams) => RenderTypes	-	否
renderFooterAfter	自定义底部前方渲染	(scope: DialogRenderParams) => RenderTypes	-	否
onConfirm	确认按钮点击事件	(closeDialog: () => void) => unknown	-	否
onCancel	关闭按钮点击事件	(closeDialog: () => void) => unknown	-	否
onFullscreen	全屏切换事件	(isFullscreen: boolean) => void	-	否

ProFormDialogEmits

导出 ProFormDialogEmits 供业务侧复用。

字段	说明	类型	默认值	必填
change	表单值改变事件	[value: unknown, model: Recordable, column: FormItemColumnProps, oldValue: unknown]	-	是
confirm	确认按钮点击事件	[model: Recordable]	-	是
cancel	取消按钮点击事件	[]	-	是

FormItemColumnProps

ProFormItem 的 props

字段	说明	类型	默认值	必填
prop	ElFormItem 的 prop 属性，当表单数据 model 为对象时，prop 也是 model 的 key	string	-	否
label	标签，ElFormItem 的 label 属性	MaybeRef<string | number> | BivariantCallback<[model: T], string | number>	-	否
showLabel	是否显示 label	MaybeRefOrGetter<boolean>	true	否
width	表单组件宽度	MaybeRefOrGetter<string | number>	-	否
el	使用的表单组件名	MaybeRefOrGetter<FormElType>	'ElInput'	否
elProps	表单组件的 Props，即会透传到表单组件	MaybeRefOrGetter<FormElProps> | BivariantCallback<[model: T], FormElProps>	-	否
elSlots	表单组件的插槽	{<br> [slotName: string]: BivariantCallback<[data: FormItemRenderParams<T> & Recordable], RenderTypes>;<br> }	-	否
options	字典枚举数据	| string[]<br> | MaybeRef<ElOption[] | object[]><br> | Promise<ElOption[] | object[]><br> | BivariantCallback<<br> [optionsParams: OptionsParams<T>],<br> | ElOption[]<br> | object[]<br> | Record<string, ElOption[] | object[]><br> | Promise<ElOption[] | object[] | Record<string, ElOption[] | object[]>><br> >	-	否
optionField	字典指定 label && value && children 的 key 值	ElOptionField	'{ label: "label", value: "value", children: "children", disabled: "disabled" }'	否
formItemProps	ElFormItem props	MaybeRefOrGetter<ElFormItemProps>	-	否
clearable	是否显示清除按钮	boolean	true	否
tooltip	Label 右侧 ElToolTip 提示	| MaybeRefOrGetter<string><br> | ({<br> icon?: Component; // ElTooTip 绑定的元素图标<br> render?: () => RenderTypes; // 自定义 ElTooTip 绑定的元素，将会覆盖图标，传入 ElTooTip 的 default 插槽里<br> contentRender?: () => RenderTypes; // 自定义 ElTooTip 的内容，传入 ElTooTip 的 content 插槽里<br> } & Partial<ElTooltipProps>)	-	否
valueFormat	表单绑定的值格式，场景：select 下拉 value 为 "1"，而 value 值是 1 导致无法匹配，可以设置为 valueFormat: "string" 解决	"string" | "number" | "boolean" | ((value: unknown) => unknown)	-	否
returnFullPath	对于 el-tree-select 组件，是否返回完整路径 当设置为 true 时，选择子节点会返回从根节点到选中节点的完整路径数组 例如：选择 "马来一期" 会返回 ["马来项目", "马来一期"]	boolean	false	否
editable	是否为编辑态	MaybeRefOrGetter<boolean>	true	否
renderLabel	自定义 label 标题	BivariantCallback<[scope: FormItemRenderParams<T>], RenderTypes>	-	否
renderLabelHTML	自定义 Label 内容渲染（返回 HTML），优先级低于 render，高于插槽	BivariantCallback<[scope: FormItemRenderParams<T>], string>	-	否
render	自定义渲染 el-form-item 下的表单组件	BivariantCallback<[scope: FormItemRenderParams<T>], RenderTypes>	-	否
parse	解析 model 中的值为组件需要的格式（在读取时调用） 使用场景：后端返回逗号分隔的字符串 "1,2,3"，需要解析为数组 ['1','2','3'] 供 el-select 多选使用 示例：parse: (value) => typeof value === 'string' ? value.split(',') : value	(value: unknown) => unknown	-	否
format	格式化最终表单提交的值（在设置到 model 之前调用） 使用场景：el-select 多选返回数组 ['1','2','3']，需要格式化为逗号分隔的字符串 "1,2,3" 提交给后端 示例：format: (value) => Array.isArray(value) ? value.join(',') : value 注意：parse 和 format 通常配对使用，形成双向转换	(value: unknown) => unknown	-	否

API 根据当前组件源码生成；同步版本与验证记录见维护说明。