Form 表单

继承el-form所有属性

用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型，需要与 Field 输入框 组件搭配使用。

基础用法

在表单中，每个 Field 组件 代表一个表单项，使用 Field 的 rules 属性定义校验规则。

校验规则

通过 rules 定义表单校验规则，所有可用字段见下方表格。

API

Form 属性

Rule 数据结构

使用 Field 的 rules 属性可以定义校验规则，可选属性如下:

键名	说明	类型
required	是否为必选字段，当值为空值时（空字符串、空数组、false、undefined、null ），校验不通过	Boolean
message	错误提示文案，可以设置为一个函数来返回动态的文案内容	`string
validator	通过函数进行校验，可以返回一个 Promise 来进行异步校验	`(value, rule) => boolean
trigger	设置本项规则的触发时机，优先级高于 Form 组件设置的 validate-trigger 属性，可选值为 onChange、onBlur、onSubmit	` string
pattern	通过正则表达式进行校验，正则无法匹配表示校验不通过	RegExp
formatter	格式化函数，将表单项的值转换后进行校验	(value, rule) => any
validateEmpty	设置 validator 和 pattern 是否要对空值进行校验，默认值为 true，可以设置为 false 来禁用该行为	Boolean

validate-trigger 可选值

通过 validate-trigger 属性可以自定义表单校验的触发时机。

值	说明
onSubmit	表单提交时触发校验
onBlur	输入框失去焦点时触发校验
onChange	输入框值改变时触发校验

事件

事件明	说明	回调参数
submit	表单提交时触发	values: object
failed	表单校验失败时触发	errorInfo: { values: object, errors: object[] }

方法

通过 ref 可以获取到 Form 实例并调用实例方法，详见组件实例方法。

方法名	说明	参数	返回值
submit	触发表单提交	-	-
getValues	获取表单项的值	-	Record<string, unknown>
validate	验证表单，支持传入一个或多个 name 来验证单个或部分表单项，不传入 name 时，会验证所有表单项	`name?: string	string[]`
resetValidation	重置表单项的验证提示，支持传入一个或多个 name 来重置单个或部分表单项，不传入 name 时，会重置所有表单项	`name?: string	string[]`
getValidationStatus	获取所有表单项的校验状态，状态包括 passed、failed、unvalidated	-	Record<string, FieldValidationStatus>
scrollToField	滚动到对应表单项的位置，默认滚动到顶部，第二个参数传 false 可滚动至底部	name: string, alignToTop: boolean	-

Field 字段属性

Attribute	Description	Type	Default
name	表单项名称	String	-
label	表单项标签	String	-
placeholder	表单项占位符	String	-
value	表单项值	Any	-
type	表单项类型，可选值为text number password url email tel textarea switch checkbox checkbox-group radio radio-group stepper rate slider upload	String	text
required	是否必填	Boolean	false
disabled	是否禁用表单项	Boolean	false
readonly	是否只读表单项	Boolean	false
rules	表单项校验规则，具体见下方表格	Object	-
maxlength	最大输入长度	Number	-
minlength	最小输入长度	Number	-
min	最小值	Number	-
max	最大值	Number	-
step	步长	Number	-
pattern	正则表达式	String	-
validator	自定义校验函数	Function	-
formatter	自定义格式化函数	Function	-
clearable	是否显示清除按钮	Boolean	false
size	表单项尺寸，可选值为large medium small	String	-
label-width	表单项标签宽度，默认单位为px	String	-
label-align	表单项标签对齐方式，可选值为left right	String	left
show-message	是否显示校验错误信息	Boolean	true
validate-trigger	触发表单校验的时机，可选值为onBlur onChange	String	onBlur

Field 插槽

Name	Description	SlotProps
default	表单项内容	-