配置项

FormColumn 配置项

属性名	说明	类型	默认值
prop	ElFormItem 的 prop 属性，当表单数据 model 为对象时，prop 也是 model 的 key	string	—
label	标签，ElFormItem 的 label 属性	string / number	—
showLabel	是否显示 label	boolean	true
width	表单组件宽度	string / number	—
el	使用的表单组件名	string	ElInput
elProps	表单组件的 Props，会透传到表单组件	object	—
elSlots	表单组件的插槽	object	—
options	字典枚举数据	array	—
optionsProp	指定 Options 的 key，优先从缓存获取对应 key 的 Options 数据	string	—
optionField	指定 options 的 label、value、children、disabled 的 key	object
colProps	ElCol Props	object	—
defaultValue	表单属性的默认值	any	—
order	表单排序（从大到小）	number	—
destroy	是否销毁表单，true 销毁，false 不销毁，类似于 v-if	boolean / function	false
hidden	是否隐藏表单，true 隐藏，false 不隐藏，类似于 v-show	boolean	false
formItemProps	ElFormItem props	object	—
clearable	是否显示清除按钮	boolean	true
tooltip	label 右侧 ElToolTip 提示	string / object	—
valueFormat	表单绑定的值格式	string	—
renderLabel	自定义 label 标题	function	—
renderLabelHTML	自定义 label 内容渲染（返回 HTML），优先级低于 render，高于插槽	function	—
render	自定义渲染 ElFormItem 下的表单组件	function	—
editable	是否为编辑态	boolean	true
...	其他扩展属性，支持所有 ElFormItem Attributes	...	...

El 组件类型

el 属性除了输入大驼峰 Camel-Case 语法，也支持输入烤肉串 Kebab-Case 语法，例如：输入 ElInput，也可以输入 el-input。

El 字面量	对应 ElementPlus 组件	对应内置组件	说明
ElInput	el-input
ElInputNumber	el-inputNumber
ElSelect	el-select
ElSelectV2	el-selectV2
ElTree	el-tree
ElTreeSelect	el-treeSelect
ElCascader	el-cascader
ElDatePicker	el-datePicker		根据 type 自动设置 valueFormat 为 YYYY-MM-DD HH:mm:ss 等格式
ElTimePicker	el-timePicker		根据 type 自动设置 valueFormat 为 YYYY-MM-DD HH:mm:ss 等格式
ElTimeSelect	el-timeSelect
ElSwitch	el-switch
ElSlider	el-slider
ElRadio	el-radio
ElRadioGroup	el-radio-group
ElRadioButton	el-radio-button
ElCheckbox	el-checkbox
ElCheckboxGroup	el-checkbox-group
ElCheckboxButton	el-checkboxButton
ElAutocomplete	el-autocomplete
ElRate	el-rate
ElColorPicker	el-colorPicker
ElTransfer	el-transfer
ElDivider	el-divider
ElUpload	el-upload
ElInputTag	el-input-tag
ElMention	el-mention
ElSegmented	el-segmented
ElText	el-text
CheckBoxSelect		check-box-select	基于 ElCheckbox、ElCheckboxGroup、ElRadio 二次封装
WangEditor		wang-editor	富文本编辑器
Tinymce		tinymce	富文本编辑器
IconPicker		icon-picker	图标选择器

自定义 El 组件类型

除了上述的 El 组件类型，你可以自定义一些 El 组件，然后通过字面量快速使用。

在 pro/form-item/src/helper/components.ts 文件中添加自定义 El 组件。

在 FormElComponentEnum 新增 El 字面量，Key 要求全大写，使用 _ 连接单词，Value 要求大驼峰命名，如：

export enum FormElComponentEnum {
  MY_COMPONENT = "MyComponent",
}

在 formELComponentsMap 实现 El 组件，组件引入的命名和上方 FormElComponentEnum 新增 Value 一致。

import { MyComponent } from "@/components/core/point-tag";

const formELComponentsMap: Record<FormPascalCaseComponentName, Component> = {
  MyComponent, // 和 FormElComponentEnum 的 Value 命名一致
};

超级组件会给自定义 El 组件传入一些 Props 属性，具体请看在 pro/form-item/src/index.vue 的最后代码（ <component v-else-if="formEl" :is="formELComponentsMap[formEl]"></component> 处）。

你可以参考 pro/form-item/src/components 目录下的组件，这些是内置的自定义 El 组件。

提示

如果你的组件比较简单，不想额外定义新的组件文件，可以使用 defineComponent 现场定义。

ProForm 配置项

Attributes

属性名	说明	类型	默认值
model-value / v-model	表单绑定值	object
columns	表单配置信息	array FormColumn[]	[]
elFormProps	ElForm Props	object	{}
rowProps	ElRow Props	object RowProps
colProps	ElCol Props	object ColProps
flexLayout	是否使用栅格布局	boolean	true
cleanModel	动态 model，如果 column 发生变化，则重新渲染 model 表单数据（将不存在 column 的 prop 从 model 中去掉）	boolean	false
notCleanModelKeys	清除 model 不存在的 prop 时，指定保留 prop，仅当 cleanModel 为 true 生效	array	[]
showLabel	是否显示 label	boolean	true
clearable	是否显示清除图标，作用于所有表单	boolean	true
width	表单组件宽度	string / number	100%
showErrorTip	表单提交时，如果校验失败，是否使用 ElMessage 提示错误信息	boolean	true
showFooter	是否显示 Footer（两个按钮）	boolean	true
showReset	是否显示重置按钮	bollean	true
footerAlign	底部按钮对齐方式	string	right
submitLoading	提交按钮 loading	boolean	false
submitText	提交按钮文字	string	提交
resetText	重置按钮文字	string	重置
preventNativeSubmit	是否阻止表单提交时默认的表单提交行为（即自动校验表单）	boolean	false
...	其他扩展属性，支持所有 ElForm Attributes	...	...

Events

名称	说明	类型
register	注册 ProForm 组件实例和 ElForm 实例	function
submit	点击提交按钮校验通过触发的事件	function
reset	点击重置按钮触发的事件	function
submitError	点击提交按钮校验不通过触发的事件	function
change	表单变化触发的事件	function
...	其他扩展属性，支持所有 ElForm Events	...

提示

如 el-form 的 validate，如下示例

示例：

模板中

<ProForm @validate="handleValidate" />

setup 中

const handleValidate = (prop: FormItemProp, isValid: boolean, message: string) => {
  console.log(dropdownItem);
};

Slots

插槽名	说明	作用域插槽参数
default	表单的内容
form-main	覆盖表单 FormMain 组件
footer-before	表单底部按钮前
footer	表单底部按钮
footer-after	表单底部按钮后
tooltip-icon	tooltip icon
'prop'	自定义表单组件，自动根据配置项的 prop 生成对应的插槽
'prop-label'	自定义表单项 label，自动根据配置项的 prop 生成对应的插槽

Exposes

名称	说明	类型
model	表单数据	object
setValues	设置 model 的值	function
setProps	设置 ProForm 组件的 props	function
setColumn	设置 column	function
addColumn	添加 column	function
delColumn	删除 column	function
submitForm	点击提交按钮校验通过触发的事件	function
resetForm	点击重置按钮触发的事件	function
elFormInstance	ElForm 实例	object
proFormMainInstance	FormMain 实例	object
getOptionsMap	获取所有 options 缓存数据	function
getElFormItemInstance	获取指定 prop 的 ElFormItem 实例	function
getElInstance	获取表单组件实例	function

拿到 elFormInstance 后支持所有 ElForm 方法

提示

如 validate, validateField 等