ProForm - 高级表单

ProForm 是通过配置动态生成的 el-form 组件，减少了模板语法，使表单开发更简单。

在线示例

基础用法

网格布局

API

ProForm 在 el-form 上进行了一层封装，支持了一些预设。

ProForm Attributes

参数	说明	类型	默认值
formProps	el-form attributes 的配置	FormProps	-
className	el-form 的类名	string	-
formItems	列定义	formItemsConfig[]	-
submitter	提交按钮相关配置	boolean | submitterProps	-
grid	开启栅格化模式，宽度默认百分比	boolean	-
rowProps	开启 grid 模式时传递给 el-row	RowProps	{ gutter: 8 }
initialValues	表单默认值	object	-

ProForm Events

参数	说明	类型	默认值
onFinish	提交表单且数据验证成功后回调事件	(values) => Promise<void> | void	-
onError	提交表单数据验证失败后的回调事件	(error) => void	-
onReset	点击重置按钮的回调，此时数据已重置完成	() => void	-

ProForm Methods

参数	说明	类型	默认值
getFormRef	获取 el-form 的 ref	() => ref	-
getForm	获取表单数据	(values) => Promise<void> | void	-
setFieldsValue	手动更新表单数据	(values) => void	-
setFieldValue	手动更新单个字段数据	(key, value) => void	-
submit	手动提交表单	() => void	-
reset	手动重置表单	() => void	-
resetAllFields	重置表单的拓展方法，过滤了非初始化收集的字段	() => void	-

formItemsConfig

在 el-form-item attributes (opens new window) 基础上，新增了以下 API。

参数	说明	类型	默认值
renderLabel	自定义 el-form-item 的 label，不支持 slot 写法	() => jsx	-
valueType	表单元素类型，会生成不同的渲染器。设置 slot 表示自定义，可选	valueType | slot	-
renderField	自定义表单元素，可选	({ form, formItem }) => jsx	-
fieldProps	表单元素的 attributes。如果渲染出来的是 el-input，则对应 el-input 的 attributes	object	-
fieldEvents	表单元素的 events。如果渲染出来的是 el-input，则对应 el-input 的 events	object	-
options	选择器、单选框组、多选框组 的数据	Array	-
valueEnum	选择器枚举，方便自动生成选项	valueEnum	-
optionLoader	异步生成 选择器、级联选择器 下拉数据	() => Promise<any>	-
initialValue	表单默认值，优先级高于 initialValues	any	-
colProps	开启 grid 模式时传递给 el-col	ColProps	-
hideInForm	在表单中不展示此项	boolean	-
customSlot	自定义 el-form-item，可选。true 默认取 prop 的值	boolean | string	-
renderFormItem	自定义 el-form-item，可选	(form) => jsx	-

renderField 和 renderFormItem 自定义渲染因为没有 v-model，是值的传递，所以需要进行初始化。如果 formItemConfig 配置了 prop 且是绑定字段，则默认进行了初始化。反之则需要在 initialValue 或 initialValues 进行配置。

options 参数的格式为选择器选项 (opens new window)，同时，兼容了选择器的分组，可以传递分组的选项 (opens new window)，判断依据是列表中第一条数据包含了 options 数组。

JSX 中传递组件参数通常需要用 {...{ props }} 包装，因为编译后的 VNode 结构要求参数放在 props 字段下。

// ✅ 大多数组件
<el-button {...{ props: { type: 'primary' } }}>提交</el-button>

// ✅ el-input 原生属性继承要用 attrs
<el-input attrs={{ placeholder: '请输入', clearable: true }} />

// ✅ 或者单独绑定每个属性
<el-input placeholder="请输入" clearable />

valueType slot

name	描述
[prop]	自定义表单元素，参数为 ({ form, formItem })

el-form-item slot

name	描述
customSlot	自定义 el-form-item，参数为 ({ form })

submitterProps

submitter 设置 false 会隐藏默认的提交按钮。

参数	说明	类型	默认值
resetText	重置按钮的文本	string	重置
submitText	提交按钮的文本	string	提交
resetButtonProps	el-button 的 attributes & button 的原生属性	ButtonProps	-
submitButtonProps	el-button 的 attributes & button 的原生属性	ButtonProps	-
customRender	自定义渲染	false | (form, action, doms) => jsx[]	-

/**
 * @desc 自定义渲染
 * @param {Object} form 表单数据
 * @param {Object} action 事件对象
 * @param {Function} action.submit 手动提交表单
 * @param {Function} action.reset 手动重置表单
 * @param {Function} action.resetAllFields 重置增强方法
 * @param {Array} doms 默认的提交按钮 doms 第一个是重置按钮，第二个是提交按钮
 */
customRender: (form, action, doms) => jsx[]