ProForm 表单

基于配置生成 Element Plus 表单，支持渲染函数、默认值和表单实例方法。

基础示例

根据 columns 配置渲染表单。

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

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

const model = ref({ name: "IDX Web", status: 1 });
const columns = [{ prop: "name", label: "名称", el: "el-input" }, { prop: "status", label: "状态", el: "el-select", options: [{ label: "启用", value: 1 }, { label: "停用", value: 0 }] }];
</script>

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

隐藏源代码

校验与提交

展示必填校验、提交回调和重置按钮。

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

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

const model = ref({ name: "", status: 1 });
const result = ref("提交后会显示表单数据");
const columns = [
  {
    prop: "name",
    label: "名称",
    el: "el-input",
    formItemProps: { rules: [{ required: true, message: "请输入名称", trigger: "blur" }] },
  },
  {
    prop: "status",
    label: "状态",
    el: "el-select",
    options: [
      { label: "启用", value: 1 },
      { label: "停用", value: 0 },
    ],
  },
];

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

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ProForm v-model="model" :columns="columns" @submit="handleSubmit">
        <template #footer="{ handleSubmit, handleReset }">
          <el-button @click="handleReset">重置</el-button>
          <el-button type="primary" @click="handleSubmit">提交</el-button>
        </template>
      </ProForm>
      <p class="form-result">{{ result }}</p>
    </div>
  </ClientOnly>
</template>

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

隐藏源代码

引入方式

import { ProForm, ProFormMain } from "@/components/pro/form";

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%"	否
columns	表单配置项	MaybeRef<LooseFormColumn[]>	[]	否
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	否
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

插槽名	说明	参数
title	标题内容插槽。	-
default	默认内容插槽。	-
动态插槽(slot)	动态转发当前组件收到的同名插槽。	-

Expose

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

Module API

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

Types

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

LooseFormColumn

组件边界使用的宽松表单列配置，擦除具体业务表单模型。

字段	说明	类型	默认值	必填
label	标签配置，组件内部按实际列配置收窄后调用。	unknown	-	否
elProps	表单组件属性，组件内部按实际列配置收窄后调用。	unknown	-	否
elSlots	表单组件插槽，组件内部按实际列配置收窄后调用。	unknown	-	否
renderLabel	标签渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
renderLabelHTML	标签 HTML 渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
render	表单项渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
destroy	是否销毁表单项，组件内部按实际列配置收窄后调用。	unknown	-	否
hidden	是否隐藏表单项，组件内部按实际列配置收窄后调用。	unknown	-	否

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