2.14.0

表单 ​

表单包含 input、radio、select、checkbox 等。 使用表单，您可以收集、验证和提交数据。

提示

该组件已升级为 flex 布局，以取代旧的 float 布局。

典型表单 ​

包括各种输入项，如 input、select、radio 和 checkbox。

在每一个 form 组件中，您需要一个 form-item 字段作为输入项的容器。

活动名称
活动区域
请选择活动区域
活动时间
-
即时配送
活动性质
特殊资源
活动形式

提示

W3C 规定：

当表单中只有一个单行文本输入字段时，用户代理（浏览器）应当将该字段中的回车键接受为提交表单的请求。

为了防止这种行为，您可以在 <el-form> 上添加 @submit.prevent。

行内表单 ​

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

设置 inline 属性为 true，表单将变为行内布局。

审批人
活动区域
活动区域
活动时间

对齐方式 ​

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

您可以单独设置 el-form-item 的 label-position 2.7.7。如果值为空，则使用 el-form 的 label-position。

label-position 属性决定标签如何对齐，可以是 top 或 left。当设置为 top 时，标签将放置在表单字段的顶部。

表单对齐
表单项对齐
名称
活动区域
活动形式

表单校验 ​

表单组件允许您验证数据，帮助您发现并纠正错误。

只需为 Form 组件添加 rules 属性，传递校验规则，并将 FormItem 的 prop 属性设置为需要校验的具体键。 更多信息请查看 async-validator。

活动名称
活动区域
活动区域
活动数量
活动数量
活动时间
-
即时配送
活动地点
活动性质
特殊资源
活动形式

自定义校验规则 ​

本例展示了如何自定义校验规则来完成二次密码确认。

这里我们使用 status-icon 来将校验结果以图标形式展示。

提示

必须调用自定义验证回调函数。 更多高级用法请查看 async-validator。

动态增删表单项 ​

除了在表单组件上一次性传递所有校验规则外，您还可以动态地为单个表单字段传递校验规则或删除规则。

邮箱
域名0

数字类型校验 ​

数字类型校验需要在 input 的 v-model 绑定上添加 .number 修饰符，它用于将 Vue 提供的字符串值转换为数字。

年龄

提示

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

表单内组件尺寸控制 ​

表单中的所有组件都从该表单继承 size 属性。类似地，FormItem 也有 size 属性。

如果您不希望该组件从 Form 或 FormItem 继承其尺寸，您仍然可以微调每个组件的 size。


活动名称
活动区域
请选择活动区域
活动时间
-
活动性质
特殊资源

无障碍 ​

当 el-form-item 内部只有一个输入框（或相关的控件，如选择器或多选框）时，表单项的标签将自动绑定到该输入框。 但是，如果 el-form-item 内部有多个输入框，则该表单项将被分配 WAI-ARIA 的 group 角色。 在这种情况下，您有责任为每个输入框分配辅助标签。

全名
您的信息

表单 API ​

表单属性 ​

名称描述类型默认值
model表单数据对象。object—
rules表单验证规则。object—
inline是否为行内表单模式。booleanfalse
label-position表单域标签的位置。 如果设置为 'left' 或 'right'，则 label-width 属性也是必需的。枚举右侧
label-width表单域标签的宽度，例如 '50px'。 所有直接子表单项都将继承该值。 支持 auto。string / number''
label-suffix表单域标签的后缀。string''
hide-required-asterisk是否隐藏必填字段标签旁边的红色星号（星号）。booleanfalse
require-asterisk-position星号的位置。枚举left
show-message是否显示校验错误信息。booleantrue
inline-message是否以行内形式展示校验错误信息。booleanfalse
status-icon是否在输入框中显示校验结果图标。booleanfalse
validate-on-rule-change是否在 rules 属性改变后立即触发一次验证。booleantrue
size用于控制该表单内组件的尺寸。枚举—
disabled是否禁用该表单内的所有组件。 在 2.12.0 之前，如果设置为 true，它将覆盖内部组件的 disabled 属性。 2.12.0 之后，内部组件的配置优先。booleanfalse
scroll-to-error当校验失败时，滚动到第一个错误表单项。booleanfalse
scroll-into-view-options 2.3.2当校验失败时，根据 scrollIntoView 选项滚动到第一个错误表单项。 scrollIntoView。object / booleantrue

表单事件 ​

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

表单插槽 ​

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

表单公开方法 ​

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

表单项 API ​

表单项属性 ​

名称描述类型默认值
propmodel 的键名。 它可以是一个属性路径（例如 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表单域错误信息，设置该值会使表单校验状态变为 error，并立即显示该提示信息。string—
show-message是否显示校验错误信息。booleantrue
inline-message以行内形式展示校验错误信息。booleanfalse
size用于控制该表单域下组件的尺寸。枚举—
for等同于原生标签中的 for。string—
validate-status表单项的校验状态。枚举—

表单项规则 ​

名称描述类型默认值
trigger验证触发方式。枚举—

提示

如果您不希望基于输入事件触发验证器，请在相应的输入类型组件（<el-input>, <el-radio>, <el-select>, ...）上将 validate-event 属性设置为 false。

表单项插槽 ​

名称描述类型
default表单项的内容。—
label自定义标签显示的内容。object
error自定义校验信息显示的内容。object

表单项公开方法 ​

名称描述类型
size表单项尺寸。object
validateMessage校验信息。object
validateState校验状态。object
validate校验表单项。Function
resetField重置当前表单项并移除校验结果。Function
clearValidate移除该表单项的校验状态。Function
setInitialValue 2.13.1为此字段设置初始值。 当调用 resetField 时，该字段将重置为该值。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
}

来源 ​

组件源码 • 样式源码 • 文档源码

贡献者 ​