Form 表单

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

TIP

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

典型表单

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

TIP

W3C 标准定义:

当一个表单中只有一个单行文本输入字段时, 浏览器应当将在此字段中按下 Enter (回车键)的行为视为提交表单的请求。 如果希望阻止这一默认行为,可以在 <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 指定访问标签。

Form API

Form Attributes

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

Form 事件

名称说明类型
validate任一表单项被校验后触发Function

Form Slots

事件名说明子标签
default自定义默认内容FormItem

Form Exposes

名称说明类型
validate对整个表单的内容进行验证。 接收一个回调函数,或返回 PromiseFunction
validateField验证具体的某个字段。Function
resetFields重置该表单项,将其值重置为初始值,并移除校验结果Function
scrollToField滚动到指定的字段Function
clearValidate清理某个字段的表单验证信息。Function

FormItem API

FormItem Attributes

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

FormItemRule

名称说明类型默认值
trigger验证逻辑的触发方式enum

TIP

如果您不想根据输入事件触发验证器, 在相应的输入类型组件上设置 validate-event 属性为 false (<el-input>, <el-radio>, <el-select>, . ……).

FormItem Slots

插槽名说明类型
default表单的内容。
label标签位置显示的内容object
error验证错误信息的显示内容object

FormItem Exposes

名称说明类型
size表单项大小object
validateMessage校验消息object
validateState校验状态object
validate验证表单项Function
resetField对该表单项进行重置,将其值重置为初始值并移除校验结果Function
clearValidate移除该表单项的校验结果Function

类型声明

显示类型声明
type Arrayable<T> = T | T[]

type FormValidationResult = Promise<boolean>

// ValidateFieldsError: see [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
type FormValidateCallback = (
  isValid: boolean,
  invalidFields?: ValidateFieldsError
) => void

// RuleItem: see [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
interface FormItemRule extends RuleItem {
  trigger?: Arrayable<string>
}

type Primitive = null | undefined | string | number | boolean | symbol | bigint
type BrowserNativeObject = Date | FileList | File | Blob | RegExp
type IsTuple<T extends ReadonlyArray<any>> = number extends T['length']
  ? false
  : true
type ArrayMethodKey = keyof any[]
type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, ArrayMethodKey>
type ArrayKey = number
type PathImpl<K extends string | number, V> = V extends
  | Primitive
  | BrowserNativeObject
  ? `${K}`
  : `${K}` | `${K}.${Path<V>}`
type Path<T> = T extends ReadonlyArray<infer V>
  ? IsTuple<T> extends true
    ? {
        [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K]>
      }[TupleKey<T>]
    : PathImpl<ArrayKey, V>
  : {
      [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K]>
    }[keyof T]
type FieldPath<T> = T extends object ? Path<T> : never
// MaybeRef: see [@vueuse/core](https://github.com/vueuse/vueuse/blob/main/packages/shared/utils/types.ts)
// UnwrapRef: see [vue](https://github.com/vuejs/core/blob/main/packages/reactivity/src/ref.ts)
type FormRules<T extends MaybeRef<Record<string, any> | string> = string> =
  Partial<
    Record<
      UnwrapRef<T> extends string ? UnwrapRef<T> : FieldPath<UnwrapRef<T>>,
      Arrayable<FormItemRule>
    >
  >

源代码

组件文档

贡献者