Form 表单

表单包含了输入框单选框选择器多选框等控件。 使用表单,您可以收集、验证和提交数据。

提示

组件已使用 flex 布局进行了升级,以取代旧的 float 布局。

基础表单

包括各种输入项,比如 inputselectradiocheckbox

提示

W3C 规定

当一个表单中只有一个单行文本输入字段时,用户代理应接受在该字段中按 Enter 键作为提交表单的请求。

要阻止此行为,您可以在 <el-form> 上添加 @submit.prevent

行内表单

当垂直空间有限且表单相对简单时,可以将其放在一行中。

对齐方式

根据您的设计,有几种不同的方法来对齐标签元素。

您可以单独设置 el-form-itemlabel-position 2.7.7。如果该值为空,则使用 el-formlabel-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-ARIAgroup 角色。在这种情况下,您有责任为单个输入框分配辅助标签。

Form API

Form 属性

名称描述类型默认值
model表单组件的数据对象。object
rules表单的校验规则。object
inline表单是否为行内形式。booleanfalse
label-position标签的位置。如果设置为 'left''right',则 label-width 属性也必须设置。枚举右侧
label-width标签的宽度,例如 '50px'。所有其直接子表单项将继承此值。支持 autostring / number''
label-suffix标签的后缀。string''
hide-required-asterisk是否隐藏必填字段标签旁边的红色星号。booleanfalse
require-asterisk-position星号的位置。枚举left
show-message是否显示错误信息。booleantrue
inline-message是否将错误信息与表单项内联显示。booleanfalse
status-icon是否显示一个指示校验结果的图标。booleanfalse
validate-on-rule-changerules 属性改变时是否触发校验。booleantrue
size控制此表单中组件的尺寸。枚举
disabled是否禁用此表单中的所有组件。如果设置为 true,它将覆盖内部组件的 disabled 属性。booleanfalse
scroll-to-error当校验失败时,滚动到第一个错误的表单条目。booleanfalse
scroll-into-view-options 2.3.2当校验失败时,它会根据 scrollIntoView 选项滚动到第一个错误项。 scrollIntoViewobject / booleantrue

Form 事件

名称描述类型
validate在表单项校验后触发Function

Form 插槽

名称描述子标签
default自定义默认内容表单项

Form Exposes

名称描述类型
validate校验整个表单。接收一个回调函数或返回 PromiseFunction
validateField校验指定的字段。Function
resetFields重置指定的字段并移除校验结果。Function
scrollToField滚动到指定的字段。Function
clearValidate清除所有或指定字段的校验信息。Function
fields 2.7.3获取所有字段的上下文。array
getField 2.10.2获取一个字段的上下文。Function

FormItem API

FormItem 属性

名称描述类型默认值
propmodel 的一个键。它可以是属性的路径(例如 a.b.0['a', 'b', '0'])。在使用 validateresetFields 方法时,该属性是必需的。string / string[]
label标签文本。string
label-position 2.7.7表单项标签的位置。如果设置为 'left''right'label-width 属性也是必需的。默认继承 formlabel-position枚举''
label-width标签的宽度,例如 '50px'。支持 'auto'string / number
required该字段是否为必填项,如果省略,将由校验规则决定。boolean
rules表单的校验规则,参见下表,更多高级用法请参见 async-validatorobject
error字段错误信息,设置其值,字段将立即校验错误并显示此信息。string
show-message是否显示错误信息。booleantrue
inline-message内联样式校验信息。booleanfalse
size控制此表单项中组件的尺寸。枚举
for与原生 label 中的 for 相同。string
validate-statusformItem 的校验状态。枚举

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

类型声明

显示声明
ts
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
}

来源

组件样式文档

贡献者