Form 表单 ​

表单包含 input、radio、select、checkbox 等需要用户输入的组件。 使用表单，您可以收集、验证和提交数据。

TIP

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

典型表单 ​

最基础的表单包括各种输入表单项，比如input、select、radio、checkbox等。

在每一个 form 组件中，你需要一个 form-item 字段作为输入项的容器，用于获取值与验证值。

Activity name
Activity zone
please select your zone
Activity time
-
Instant delivery
Activity type
Resources
Activity form

TIP

W3C 标准定义：

当一个表单中只有一个单行文本输入字段时， 浏览器应当将在此字段中按下 Enter （回车键）的行为视为提交表单的请求。 如果希望阻止这一默认行为，可以在 <el-form> 标签上添加 @submit.prevent。

行内表单 ​

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

通过设置 inline 属性为 true 可以让表单域变为行内的表单域。

Approved by
Activity zone
Activity zone
Activity time

对齐方式 ​

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

您可以分别设置 el-form-item 的label-position 2.7.7. 如果值为空, 则会使用 el-form的label-position。

通过设置 label-position 属性可以改变表单域标签的位置，可选值为 top、left, 当设为 top 时标签会置于表单域的顶部

Form Align
Form Item Align
Name
Activity zone
Activity form

标签提示 ​

为 el-form-item 设置 label-tooltip 对象后，标签旁会显示问号图标，鼠标移入图标即可查看提示信息。你可以在对象中配置图标位置、颜色以及 Tooltip 样式。

Activity name
Activity zone

表单校验 ​

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

Form 组件提供了表单验证的功能，只需为 rules 属性传入约定的验证规则，并将 form-Item 的 prop 属性设置为需要验证的特殊键值即可。 校验规则参见 async-validator

Activity name
Activity zone
Activity zone
Activity count
Activity count
Activity time
-
Instant delivery
Activity location
Activity type
Resources
Activity form

自定义校验规则 ​

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

本例还使用status-icon属性为输入框添加了表示校验结果的反馈图标。

TIP

自定义的校验回调函数必须被调用。 校验规则参见 async-validator

添加/删除表单项 ​

除了一次通过表单组件上的所有验证规则外. 您也可以动态地通过验证规则或删除单个表单字段的规则。

Email
Domain0

数字类型验证 ​

数字类型的验证需要在 v-model 处加上 .number 的修饰符，这是 Vue 自身提供的用于将绑定值转化为 number 类型的修饰符。

age

TIP

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

尺寸控制 ​

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

如果希望某个表单项或某个表单组件的尺寸不同于 Form 上的 size 属性，直接为这个表单项或表单组件设置自己的 size 属性即可。


Activity name
Activity zone
please select your zone
Activity time
-
Activity type
Resources

无障碍 ​

当在 el-form-item 内只有一个输入框（或相关的控制部件，如选择或复选框），表单项的标签将自动附加在那个输入框上。 如果 el-form-item内有多个 input，则表单项会被设置成 WAI-ARIA 组 的 role。 在这种情况下，需要手动给每个 input 指定访问标签。

Full Name
Your Information

Form API ​

Form Attributes ​

属性名说明类型默认值
model表单数据对象object—
rules表单验证规则object—
inline行内表单模式booleanfalse
label-position表单域标签的位置， 当设置为 left 或 right 时，则也需要设置 label-width 属性enumright
label-width标签的长度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 auto。string / 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是否禁用该表单内的所有组件。 在 2.12.0 以前，如果设置为 true，它将覆盖内部组件的 disabled 属性。 在 2.12.0 之后，内部组件的配置优先。booleanfalse
scroll-to-error当校验失败时，滚动到第一个错误表单项booleanfalse
scroll-into-view-options 2.3.2当校验有失败结果时，滚动到第一个失败的表单项目 可通过 scrollIntoView 配置object / booleantrue

Form Events ​

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

Form Slots ​

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

Form Exposes ​

名称说明类型
validate对整个表单的内容进行验证。 接收一个回调函数，或返回 Promise。Function
validateField验证具体的某个字段。Function
resetFields重置该表单项，将其值重置为初始值，并移除校验结果Function
scrollToField滚动到指定的字段Function
clearValidate清理某个字段的表单验证信息。Function
fields 2.7.3获取所有字段的 contextarray
getField 2.10.2获取字段的 contextFunction
setInitialValues 2.13.1设置表单字段的初始值。 当调用 resetFields 时，字段将重置为这些值。Function

FormItem API ​

FormItem Attributes ​

属性名说明类型Default
propmodel 的键名。 它可以是属性的路径（如 a.b.0 或 ['a', 'b', '0']）。 在使用了 validate、resetFields 的方法时，该属性是必填的。string / string[]—
label标签文本string—
label-tooltip 2.14.6标签旁 Tooltip 的配置object—
label-position 2.7.7表单域标签的位置， 当设置为 left 或 right 时，则也需要设置 label-width 属性 默认会继承 Form的label-positionenum''
label-width标签宽度，例如 '50px'。 可以使用 auto。string / number—
required是否为必填项，如不设置，则会根据校验规则确认boolean—
rules表单验证规则, 具体配置见下表, 更多内容可以参考async-validatorobject—
error表单域验证错误时的提示信息。设置该值会导致表单验证状态变为 error，并显示该错误信息。string—
show-message是否显示校验错误信息booleantrue
inline-message是否在行内显示校验信息booleanfalse
size用于控制该表单域下组件的默认尺寸enum—
for和原生标签相同能力string—
validate-statusformitem 校验的状态enum—

FormItemLabelTooltip 2.14.6 ​

名称说明类型默认值
contentTooltip 的提示内容string—
positionTooltip 图标相对于标签文本的位置enumafter
icon-colorTooltip 图标的颜色string#909399
effectTooltip 主题stringdark
popper-classTooltip 弹出层的自定义类名string / object / array—

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
setInitialValue 2.13.1设置表单字段的初始值。 当调用 resetFields 时，字段将重置为这些值。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
  setInitialValue: (value: any) => void
}

源代码 ​

组件 • 样式 • 文档

贡献者 ​