表单
表单由 input、radio、select、checkbox 等组成。通过表单，您可以收集、验证和提交数据。
TIP
该组件已升级为弹性布局，以取代旧的浮动布局。
以下示例展示当前默认布局、校验提示和操作区写法。
基本形式
包括input、select、radio、checkbox等各种输入项。
在每个 form 组件中，您需要一个 form-item 字段作为输入项的容器。
默认布局
Form 默认使用纵向排列、标签置顶和文档流内的校验提示。
这个示例展示当前默认的表单布局。展开 Select / SelectV2 可以继续查看确认与取消流程。
TIP
W3C 规定
当表单中只有一个单行文本输入字段时，用户代理应接受该字段中的 Enter 作为提交表单的请求。
为了防止这种行为，您可以在 <el-form> 上添加 @submit.prevent。
验证
表单组件允许您验证数据，帮助您发现并纠正错误。
只需为Form组件添加rules属性，通过验证规则，并将FormItem的prop属性设置为需要验证的特定密钥即可。请参阅异步验证器
自定义验证规则
本示例展示了如何自定义自己的验证规则来完成双因素密码验证。
这里我们使用 status-icon 将验证结果反映为图标。
TIP
必须调用自定义验证回调函数。在 async-validator 中查看更多高级用法。
添加/删除表单项
除了在表单组件上一次性传递所有验证规则外，您还可以在单个表单字段上动态传递验证规则或删除规则。
号码验证
Number Validate 需要在输入 v-model 绑定上添加 .number 修饰符，用于将字符串值转换为 Vue 提供的数字。
尺寸控制
表单中的所有组件都从该表单继承其 size 属性。同样，FormItem也有一个size属性。
如果您不希望该组件从 From 或 FormItem 继承其大小，您仍然可以微调每个组件的 size。
辅助功能
当 el-form-item 内只有一个输入（或相关控件，例如选择或复选框）时，表单项的标签将自动附加到该输入。但是，如果 el-form-item 内部有多个输入，则表单项将被分配 group 的 WAI-ARIA 角色。在这种情况下，您有责任为各个输入分配辅助标签。
表单API
表单属性
| 名称 | 描述 | 类型 | 默认 |
|---|---|---|---|
| 型号 | 表单组件的数据。 | 对象 | — |
| 规则 | 表单的验证规则。 | 对象 | — |
| 标签后缀 | 标签的后缀。 | 字符串 | '' |
| 隐藏所需星号 | 是否隐藏必填字段的标签旁边应有一个红色星号（星号）。 | 布尔值 | 假 |
| 需要星号位置 | 星号的位置。 | 枚举 | 左 |
| 显示消息 | 是否显示错误信息。 | 布尔值 | 真实 |
| 内联消息 | 是否在表单项内显示错误消息。 | 布尔值 | 假 |
| 状态图标 | 是否显示指示验证结果的图标。 | 布尔值 | 假 |
| 规则更改时验证 | 当 rules 属性更改时是否触发验证。 | 布尔值 | 真实 |
| 尺寸 | 控制此表单中组件的大小。 | 枚举 | — |
| 已禁用 | 是否禁用此表单中的所有组件。在 2.12.0 之前，如果设置为 true，它将覆盖内部组件的 disabled 属性。在2.12.0之后，内部组件的配置优先。 | 布尔值 | 假 |
| 滚动至错误 | 当验证失败时，滚动到第一个错误表单条目。 | 布尔值 | 假 |
| 滚动到视图选项 2.3.2 | 当验证失败时，它会根据scrollIntoView选项滚动到第一个错误项。 滚动到视图。 | 对象 / 布尔值 | 真实 |
表单事件
| 名称 | 描述 | 类型 |
|---|---|---|
| 验证 | 验证表单项后触发 | 功能 |
表单插槽
| 名称 | 描述 | 子标签 |
|---|---|---|
| 默认 | 自定义默认内容 | 表单项 |
表单暴露
| 名称 | 描述 | 类型 |
|---|---|---|
| 验证 | 验证整个表格。接收回调或返回Promise。 | 功能 |
| 验证字段 | 验证指定字段。 | 功能 |
| 重置字段 | 重置指定字段并删除验证结果。 | 功能 |
| 滚动到字段 | 滚动到指定字段。 | 功能 |
| 清除验证 | 清除所有或指定字段的验证消息。 | 功能 |
| 字段 2.7.3 | 获取所有字段上下文。 | 数组 |
| getField 2.10.2 | 获取字段上下文。 | 功能 |
| 设置初始值 2.13.1 | 设置表单字段的初始值。当调用 resetFields 时，字段将重置为这些值。 | 功能 |
表单项 API
表单项属性
| 名称 | 描述 | 类型 | 默认 |
|---|---|---|---|
| prop | model 的字段键名。它可以是属性路径（例如 a.b.0 或 ['a', 'b', '0']）。在使用 validate 和 resetFields 方法时，该属性是必需的。 | 字符串 / 字符串[] | — |
| 标签 | 标签文本。 | 字符串 | — |
| 必填 | 该字段是否为必填字段，如果省略，将由验证规则确定。 | 布尔值 | — |
| 规则 | 表单校验规则见 下表，更高级的用法见 async-validator。 | 对象 | — |
| 错误 | 字段错误消息，设置其值，字段将验证错误并立即显示此消息。 | 字符串 | — |
| 显示消息 | 是否显示错误信息。 | 布尔值 | 真实 |
| 内联消息 | 内联样式验证消息。 | 布尔值 | 假 |
| 尺寸 | 控制此表单项中组件的大小。 | 枚举 | — |
| for | 与原生 label 元素中的 for 属性相同。 | 字符串 | — |
| 验证状态 | formItem 的验证状态。 | 枚举 | — |
表单项规则
| 名称 | 描述 | 类型 | 默认 |
|---|---|---|---|
| trigger | 验证器的触发时机。 | 枚举 | — |
TIP
如果您不想根据输入事件触发验证器，请在相应的输入类型组件（<el-input>、<el-radio>、<el-select>，...）上将 validate-event 属性设置为 false。
表单项槽
| 名称 | 描述 | 类型 |
|---|---|---|
| 默认 | 表单项的内容。 | — |
| 标签 | 要在标签上显示的自定义内容。 | 对象 |
| 错误 | 显示验证消息的自定义内容。 | 对象 |
FormItem 暴露
| 名称 | 描述 | 类型 |
|---|---|---|
| 尺寸 | 表格项目尺寸。 | 对象 |
| 验证消息 | 验证消息。 | 对象 |
| 验证状态 | 验证状态。 | 对象 |
| 验证 | 验证表单项。 | 功能 |
| 重置字段 | 重置当前字段并删除验证结果。 | 功能 |
| 清除验证 | 删除字段的验证状态。 | 功能 |
| 设置初始值 2.13.1 | 设置该字段的初始值。当调用 resetField 时，该字段将重置为该值。 | 功能 |
类型声明
显示声明
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
) => Promise<void> | 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>
>
>
type FormItemValidateState = (typeof formItemValidateStates)[number]
type FormItemProps = ExtractPropTypes<typeof formItemProps>
type FormItemContext = FormItemProps & {
$el: HTMLDivElement | undefined
size: ComponentSize
validateMessage: string
validateState: FormItemValidateState
isGroup: boolean
labelId: string
inputIds: string[]
hasLabel: boolean
fieldValue: any
propString: string
addInputId: (id: string) => void
removeInputId: (id: string) => void
validate: (
trigger: string,
callback?: FormValidateCallback
) => FormValidationResult
resetField(): void
clearValidate(): void
setInitialValue: (value: any) => void
}