Form 表单
表单包含了输入框、单选框、选择器、多选框等控件。 使用表单,您可以收集、验证和提交数据。
提示
组件已使用 flex 布局进行了升级,以取代旧的 float 布局。
基础表单
包括各种输入项,比如 input、select、radio 和 checkbox。
提示
W3C 规定
当一个表单中只有一个单行文本输入字段时,用户代理应接受在该字段中按 Enter 键作为提交表单的请求。
要阻止此行为,您可以在 <el-form> 上添加 @submit.prevent。
行内表单
当垂直空间有限且表单相对简单时,可以将其放在一行中。
对齐方式
根据您的设计,有几种不同的方法来对齐标签元素。
您可以单独设置 el-form-item 的 label-position 2.7.7。如果该值为空,则使用 el-form 的 label-position。
表单校验
表单组件允许您验证您的数据,帮助您发现和纠正错误。
自定义校验规则
本例展示了如何自定义校验规则来完成密码的二次验证。
提示
必须调用自定义校验回调函数。更多高级用法请参见 async-validator。
添加/删除表单项
数字类型校验
提示
当一个 el-form-item 嵌套在另一个 el-form-item 中时,其标签宽度将为 0。如果需要,您可以在该 el-form-item 上设置 label-width。
尺寸控制
表单中的所有组件都从表单继承其 size 属性。同样,FormItem 也有一个 size 属性。
无障碍访问
当 el-form-item 中只有一个输入框(或相关控件,如选择器或复选框)时,表单项的标签将自动附加到该输入框上。但是,如果 el-form-item 中有多个输入框,则表单项将被分配 WAI-ARIA 的 group 角色。在这种情况下,您有责任为单个输入框分配辅助标签。
Form API
Form 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model | 表单组件的数据对象。 | object | — |
| rules | 表单的校验规则。 | object | — |
| inline | 表单是否为行内形式。 | boolean | false |
| label-position | 标签的位置。如果设置为 'left' 或 'right',则 label-width 属性也必须设置。 | 枚举 | 右侧 |
| label-width | 标签的宽度,例如 '50px'。所有其直接子表单项将继承此值。支持 auto。 | string / number | '' |
| label-suffix | 标签的后缀。 | string | '' |
| hide-required-asterisk | 是否隐藏必填字段标签旁边的红色星号。 | boolean | false |
| require-asterisk-position | 星号的位置。 | 枚举 | left |
| show-message | 是否显示错误信息。 | boolean | true |
| inline-message | 是否将错误信息与表单项内联显示。 | boolean | false |
| status-icon | 是否显示一个指示校验结果的图标。 | boolean | false |
| validate-on-rule-change | 当 rules 属性改变时是否触发校验。 | boolean | true |
| size | 控制此表单中组件的尺寸。 | 枚举 | — |
| disabled | 是否禁用此表单中的所有组件。如果设置为 true,它将覆盖内部组件的 disabled 属性。 | boolean | false |
| scroll-to-error | 当校验失败时,滚动到第一个错误的表单条目。 | boolean | false |
| scroll-into-view-options 2.3.2 | 当校验失败时,它会根据 scrollIntoView 选项滚动到第一个错误项。 scrollIntoView。 | object / boolean | true |
Form 事件
| 名称 | 描述 | 类型 |
|---|---|---|
| validate | 在表单项校验后触发 | Function |
Form 插槽
| 名称 | 描述 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | 表单项 |
Form Exposes
| 名称 | 描述 | 类型 |
|---|---|---|
| validate | 校验整个表单。接收一个回调函数或返回 Promise。 | Function |
| validateField | 校验指定的字段。 | Function |
| resetFields | 重置指定的字段并移除校验结果。 | Function |
| scrollToField | 滚动到指定的字段。 | Function |
| clearValidate | 清除所有或指定字段的校验信息。 | Function |
| fields 2.7.3 | 获取所有字段的上下文。 | array |
| getField 2.10.2 | 获取一个字段的上下文。 | Function |
FormItem API
FormItem 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| prop | model 的一个键。它可以是属性的路径(例如 a.b.0 或 ['a', 'b', '0'])。在使用 validate 和 resetFields 方法时,该属性是必需的。 | string / string[] | — |
| label | 标签文本。 | string | — |
| label-position 2.7.7 | 表单项标签的位置。如果设置为 'left' 或 'right',label-width 属性也是必需的。默认继承 form 的 label-position。 | 枚举 | '' |
| label-width | 标签的宽度,例如 '50px'。支持 'auto'。 | string / number | — |
| required | 该字段是否为必填项,如果省略,将由校验规则决定。 | boolean | — |
| rules | 表单的校验规则,参见下表,更多高级用法请参见 async-validator。 | object | — |
| error | 字段错误信息,设置其值,字段将立即校验错误并显示此信息。 | string | — |
| show-message | 是否显示错误信息。 | boolean | true |
| inline-message | 内联样式校验信息。 | boolean | false |
| size | 控制此表单项中组件的尺寸。 | 枚举 | — |
| for | 与原生 label 中的 for 相同。 | string | — |
| validate-status | formItem 的校验状态。 | 枚举 | — |
FormItemRule
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| trigger | 校验器如何被触发。 | 枚举 | — |
提示
如果您不希望基于输入事件触发校验器,请在相应的输入类型组件(<el-input>、<el-radio>、<el-select> 等)上将 validate-event 属性设置为 false。
FormItem 插槽
| 名称 | 描述 | 类型 |
|---|---|---|
| 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
) => 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
}