Form 表单

表单包含 输入框, 单选框, 下拉选择, 多选框 等用户输入的组件。 使用表单,您可以收集、验证和提交数据。

TIP

Form 组件已经从 2. x 的 Float 布局升级为 Flex 布局。

典型表单

最基础的表单包括各种输入表单项,比如inputselectradiocheckbox等。

TIP

W3C 标准定义:

当一个表单中只有一个单行文本输入字段时, 用户代理人应该在该字段中接受输入作为提交表单的请求。 如果希望阻止这一默认行为,可以在 <el-form> 标签上添加 @submit.prevent

行内表单

当垂直方向空间受限且表单较简单时,可以在一行内放置表单。

对齐方式

根据你们的设计情况,来选择最佳的标签对齐方式。

表单校验

Form 组件允许你验证用户的输入是否符合规范,来帮助你找到和纠正错误。

自定义校验规则

这个例子中展示了如何使用自定义验证规则来完成密码的二次验证。

TIP

自定义的校验回调函数必须被调用。 更多高级用法可参考 async-validator

添加/删除表单项

数字类型验证

TIP

当一个 el-form-item 嵌套在另一个 el-form-item时,其标签宽度将是 0。 如果需要可以为 el-form-item 单独设置 label-width 属性。

尺寸控制

表单中的所有子组件都继承了该表单的 size 属性。 同样,form-item 也有一个 size 属性。

无障碍

当在 el-form-item 内只有一个输入框(或相关的控制部件,如选择或复选框),表单项的标签将自动附加在那个输入框上。 然而,如果同时有多个输入框在 el-form-item内, 表单项将被分配为 WAI-ARIA 的角色。 在这种情况下,需要手动给每个 input 指定访问标签。

表单 API

Form 属性

属性名说明类型默认值
model表单数据对象Record<string, any>
rules表单验证规则FormRules
inline行内表单模式booleanfalse
label-position表单域标签的位置, 当设置为 leftright 时,则也需要设置 label-width 属性'left' | 'right' | 'top''right'
label-width标签的长度,例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 autostring | number
label-suffix表单域标签的后缀string
hide-required-asterisk是否隐藏必填字段标签旁边的红色星号。booleanfalse
require-asterisk-position星号的位置。'left' | 'right''left'
show-message是否显示校验错误信息booleantrue
inline-message是否以行内形式展示校验信息booleanfalse
status-icon是否在输入框中显示校验结果反馈图标booleanfalse
validate-on-rule-change是否在 rules 属性改变后立即触发一次验证booleantrue
size用于控制该表单内组件的尺寸'large' | 'default' | 'small'
disabled是否禁用该表单内的所有组件。 如果设置为 true, 它将覆盖内部组件的 disabled 属性booleanfalse
scroll-to-error当校验失败时,滚动到第一个错误表单项booleanfalse

Form 方法

方法名说明类型
validate对整个表单的内容进行验证。 接收一个回调函数,或返回 Promise(callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>
validateField验证具体的某个字段。(props?: Arrayable<FormItemProp>, callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>
resetFields重置该表单项,将其值重置为初始值,并移除校验结果(props?: Arrayable<FormItemProp>) => void
scrollToField滚动到指定的字段(prop: FormItemProp) => void
clearValidate清理某个字段的表单验证信息。(props?: Arrayable<FormItemProp>) => void

Form 事件

事件名说明回调参数
validate任一表单项被校验后触发(prop: FormItemProp, isValid: boolean, message: string) => void

Form 插槽

插槽名说明子标签
-自定义默认内容FormItem

表单项目 API

Form Item 属性

属性名说明类型默认值
propmodel 的键名。 它可以是一个路径数组(例如 ['a', 'b', 0])。 在定义了 validateresetFields 的方法时,该属性是必填的string | string[]
label标签文本string
label-width标签宽度,例如 '50px'。 可以使用 autostring | number
required是否为必填项,如不设置,则会根据校验规则确认booleanfalse
rules表单验证规则, 具体配置见下表, 更多内容可以参考async-validatorFormItemRule | FormItemRule[]
error表单域验证错误时的提示信息。设置该值会导致表单验证状态变为 error,并显示该错误信息。string
show-message是否显示校验错误信息booleantrue
inline-message是否在行内显示校验信息booleanfalse
size用于控制该表单域下组件的默认尺寸'large' | 'default' | 'small''default'

Form Item 规则

名称说明类型默认值
trigger验证逻辑的触发方式'blur' | 'change'

Form Item 插槽

插槽名说明插槽作用域
表单的内容。
label标签位置显示的内容{ label }
error验证错误信息的显示内容{ error }

Form Item 方法

方法名说明类型
resetField对该表单项进行重置,将其值重置为初始值并移除校验结果() => void
clearValidate移除该表单项的校验结果() => void

源代码

组件文档

贡献者