ProFormGroup 分组表单

ProFormGroup 分组表单 的基础用法、公开 API 与示例。

基础示例

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

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

const model = ref({ name: "IDX Web", owner: "Doc" });
const columns = [{ title: "基础", columns: [{ prop: "name", label: "名称", el: "el-input" }] }, { title: "负责人", columns: [{ prop: "owner", label: "负责人", el: "el-input" }] }];
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ProFormGroup v-model="model" :columns="columns" :show-footer="false" />
    </div>
  </ClientOnly>
</template>

隐藏源代码

引入方式

import { ProFormGroup } from "@/components/pro/form-group";

Props

参数	说明	类型	默认值	必填
cleanModel	动态 model，如果 column 发生变化，则重新渲染 model 表单数据（将不存在 column 的 prop 从 model 中去掉）	boolean	false	否
notCleanModelKeys	清除 model 不存在的 prop 时，指定保留 prop，仅当 cleanModel 为 true 生效	string[]	[]	否
flexLayout	是否使用栅格布局	boolean	true	否
rowProps	ElRow Props	ElRowProps	{}	否
colProps	ElCol Props	ElColProps	{}	否
showLabel	是否显示 label，优先级低于 FormItemColumnProps["showLabel"]	FormItemColumnProps["showLabel"]	true	否
clearable	是否显示清除按钮，优先级低于 FormItemColumnProps["clearable"]	FormItemColumnProps["clearable"]	true	否
editable	是否允许编辑	FormItemColumnProps["editable"]	true	否
width	表单组件宽度，优先级低于 FormItemColumnProps["width"]	FormItemColumnProps["width"]	"100%"	否
elFormProps	ElForm props	MaybeRefOrGetter<ElFormProps>	{}	否
showErrorTip	表单提交时，如果校验失败，是否使用 ElMessage 提示错误信息	boolean	true	否
showFooter	是否显示 Footer（两个按钮）	boolean	true	否
showReset	是否显示重置按钮	boolean	true	否
submitText	提交按钮文字	string	"提交"	否
resetText	重置按钮文字	string	"重置"	否
submitLoading	提交按钮 loading	boolean	false	否
footerAlign	底部对齐方式	"left" | "center" | "right"	"right"	否
preventNativeSubmit	是否阻止表单提交时默认的表单提交行为（即自动校验表单）	boolean	false	否
columns	列配置项	FormGroupColumn[]	[]	否
cardProps	el-card 的 props	Partial<CardProps>	-	否
modelValue	组件双向绑定值。	Recordable	() => reactive({})	否

Events

事件名	说明	回调参数
register	注册 ProForm 组件实例和 elForm 实例	proFormInstance: unknown, elFormInstance: FormInstance | null
change	表单值改变事件	value: unknown, model: Recordable, column: FormItemColumnProps, oldValue: unknown
validate	ElForm 自带的事件	prop: FormItemProp, isValid: boolean, message: string
submit	提交按钮事件	model: Recordable
submitError	表单提交后校验失败事件	invalidFields: Parameters<FormValidateCallback>[1]
reset	重置按钮事件	model: Recordable
update:modelValue	双向绑定值更新时触发。	value: Recordable

Slots

插槽名	说明	参数
header	头部内容插槽。	title, columns, icon, index

Expose

名称	说明	类型
model	暴露 model 给外部调用。	-
setProps	动态设置组件属性。	-
setColumn	动态设置列配置。	-
setValues	暴露 setValues 给外部调用。	-
delColumn	动态删除列配置。	-
addColumn	动态新增列配置。	-
submitForm	暴露 submitForm 给外部调用。	-
resetForm	暴露 resetForm 给外部调用。	-
getOptionsMap	暴露 getOptionsMap 给外部调用。	-
getProFormInstance	暴露 getProFormInstance 给外部调用。	-
getProFormMainInstance	暴露 getProFormMainInstance 给外部调用。	-
getElFormInstance	获取查询表单实例。	-
getElFormItemInstance	获取查询表单项实例。	-
getElInstance	获取内部组件实例。	-

Module API

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

Types

ProFormGroupProps

导出 ProFormGroupProps 供业务侧复用。

字段	说明	类型	默认值	必填
cleanModel	动态 model，如果 column 发生变化，则重新渲染 model 表单数据（将不存在 column 的 prop 从 model 中去掉）	boolean	false	否
notCleanModelKeys	清除 model 不存在的 prop 时，指定保留 prop，仅当 cleanModel 为 true 生效	string[]	-	否
flexLayout	是否使用栅格布局	boolean	true	否
rowProps	ElRow Props	ElRowProps	-	否
colProps	ElCol Props	ElColProps	-	否
showLabel	是否显示 label，优先级低于 FormItemColumnProps["showLabel"]	FormItemColumnProps["showLabel"]	true	否
clearable	是否显示清除按钮，优先级低于 FormItemColumnProps["clearable"]	FormItemColumnProps["clearable"]	true	否
editable	是否允许编辑	FormItemColumnProps["editable"]	true	否
width	表单组件宽度，优先级低于 FormItemColumnProps["width"]	FormItemColumnProps["width"]	'100%'	否
elFormProps	ElForm props	MaybeRefOrGetter<ElFormProps>	-	否
showErrorTip	表单提交时，如果校验失败，是否使用 ElMessage 提示错误信息	boolean	true	否
showFooter	是否显示 Footer（两个按钮）	boolean	true	否
showReset	是否显示重置按钮	boolean	true	否
submitText	提交按钮文字	string	'提交'	否
resetText	重置按钮文字	string	'重置'	否
submitLoading	提交按钮 loading	boolean	false	否
footerAlign	底部对齐方式	"left" | "center" | "right"	'right'	否
preventNativeSubmit	是否阻止表单提交时默认的表单提交行为（即自动校验表单）	boolean	false	否
columns	列配置项	FormGroupColumn[]	-	否
cardProps	el-card 的 props	Partial<CardProps>	-	否

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

FormGroupColumn

导出 FormGroupColumn 供业务侧复用。

字段	说明	类型	默认值	必填
title	卡片标题	MaybeRefOrGetter<string>	-	是
prop	当前分组表单唯一标识，可用于插槽	string	-	否
icon	el-icon 组件的图标	Component	-	否
cardProps	el-card 的 props，优先级高于整体的 cardProps	Partial<CardProps>	-	否
hidden	是否隐藏分组	MaybeRefOrGetter<boolean>	false	否
columns	表单列配置	LooseFormColumn[]	-	是

ProFormGroupEmits

导出 ProFormGroupEmits 供业务侧复用。

字段	说明	类型	默认值	必填
register	注册 ProForm 组件实例和 elForm 实例	[proFormInstance: unknown, elFormInstance: FormInstance | null]	-	是
change	表单值改变事件	[value: unknown, model: Recordable, column: FormItemColumnProps, oldValue: unknown]	-	是
validate	ElForm 自带的事件	[prop: FormItemProp, isValid: boolean, message: string]	-	是
submit	提交按钮事件	[model: Recordable]	-	是
submitError	表单提交后校验失败事件	[invalidFields: Parameters<FormValidateCallback>[1]]	-	是
reset	重置按钮事件	[model: Recordable]	-	是

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