Formulario

El formulario consiste en input, radio, select, checkbox y así sucesivamente. Con el formulario, usted puede recoger, verificar y enviar datos.

TIP

El componente ha sido actualizado con un diseño flex para reemplazar el antiguo diseño flotante.

Formulario básico

Incluye todo tipo de entradas, tales como input, select, radio y checkbox.

TIP

W3C reglamenta esto

Cuando solo hay un campo de entrada de texto de una sola línea en un formulario, el agente de usuario debe aceptar Enter en ese campo como una solicitud de envío del formulario.. Para evitar este comportamiento, puede añadir @submit.prevent en <el-form>.

Formulario inline

Cuando el espacio vertical es limitado y el formulario es relativamente simple, puede ponerlo en una única línea.

Alineación

Dependiendo de su diseño, hay varias maneras diferentes de alinear la etiqueta.

Validación

Este componente de formulario le permite verificar sus datos, ayudándole a encontrar y corregir errores.

Reglas personalizadas de validación

Este ejemplo muestra cómo personalizar sus propias reglas de validación para finalizar una verificación de contraseña de dos pasos.

TIP

La función de callback de validación personalizada debe ser llamada. Vea más usos avanzados en async-validator.

Añadir/Eliminar validaciones del elemento del formulario

Validación numérica

TIP

Cuando un elemento el-form-item es anidado en otro el-form-item, su ancho de etiqueta será 0. Puedes establecer label-width en ese el-form-item si es necesario.

Control de tamaño

Todos los componentes de un formulario heredan su atributo size del Form. Del mismo modo, FormItem también tiene un atributo size.

Accesibilidad

Cuando solo una entrada (o control relacionado como un select o un checkbox) está dentro de un elemento el-form-item, la etiqueta del elemento del formulario se adjuntará automáticamente a esa entrada. Sin embargo, si hay múltiples entradas dentro del elemento el-form-item, al elemento del formulario le será asignado el rol WAI-ARIA del grupo en su lugar. En este caso, es su responsabilidad asignar etiquetas de asistencia a las entradas individuales.

API del Formulario

Atributos del formulario

NombreDescripciónTipoPor defecto
modelDatos del componente de formulario.object
rulesReglas de validación.object
inlineSi el formulario es inline.booleanfalse
label-positionPosición de la etiqueta. Si se establece en 'left' o 'right', se necesita definir la proplabel-width.enumright
label-widthAncho de la etiqueta, ej.: '50px'. Todos los componentes del formulario que sean hijos directos heredaran este valor. se puede usar auto.string / number''
label-suffixSufijo de la etiqueta.string''
hide-required-asteriskSi los campos obligatorios deben tener un asterisco rojo (estrella) al lado de sus etiquetas.booleanfalse
require-asterisk-positionPosición del asterisco.enumleft
show-messageSi mostrar o no el mensaje de error.booleantrue
inline-messageSi mostrar el mensaje de error en línea con el elemento del formulario.booleanfalse
status-iconSi se muestra un icono que indique el resultado de la validación.booleanfalse
validate-on-rule-changeSi se desencadena la validación cuando la prop rules cambia.booleantrue
sizeControla el tamaño de los componentes en este formulario.enum
disabledDeshabilitar o no todos los componentes en este formulario. Si se establece en true, anulará la propiedad disabled del componente interior.booleanfalse
scroll-to-errorCuando la validación falla, desplácese a la primera entrada del formulario de error.booleanfalse
scroll-into-view-options 2.3.2Cuando la validación falla, se desplaza al primer elemento de error basado en la opción scrollIntoView. scrollIntoView.object / boolean

Form Events

NameDescripciónTipo
validatetriggers after a form item is validatedFunction

Form Slots

NombreDescripciónSubtags
defaultcustomize default contentFormItem

Exposiciones del formulario

NombreDescripciónTipo
validateValidar todo el formulario. Recibe un callback o devuelve Promise.Function
validateFieldValidar campos específicos.Function
resetFieldsRestablece los campos especificados y elimina el resultado de la validación.Function
scrollToFieldDesplazarse hasta los campos especificados.Function
clearValidateBorrar mensaje de validación para los campos especificados.Function
fields 2.7.3Get all fields context.array

FormItem API

FormItem Attributes

NombreDescripciónTypeDefault
propA key of model. It could be a path of the property (e.g a.b.0 or ['a', 'b', '0']). In the use of validate and resetFields method, the attribute is required.string / string[]
labelLabel text.string
label-widthWidth of label, e.g. '50px'. 'auto' is supported.string / number''
requiredWhether the field is required or not, will be determined by validation rules if omitted.boolean
rulesValidation rules of form, see the following table, more advanced usage at async-validator.object
errorField error message, set its value and the field will validate error and show this message immediately.string
show-messageWhether to show the error message.booleantrue
inline-messageInline style validate message.string / boolean''
sizeControl the size of components in this form-item.enum
forSame as for in native label.string
validate-statusValidation state of formItem.enum

Reglas de los componentes del formulario

NombreDescripciónTipoPor defecto
triggerHow the validator is triggered.enum

TIP

Si no desea activar el validador basado en eventos de entrada, establecer el atributo validate-event como false en los componentes de tipo de entrada correspondientes (<el-input>, <el-radio>, <el-select>, . .).

FormItem Slots

NombreDescripciónTipo
defaultContent of Form Item.
labelCustom content to display on label.object
errorCustom content to display validation message.object

FormItem Exposes

NombreDescripciónTipo
sizeForm item size.object
validateMessageValidation message.object
validateStateValidation state.object
validateValidate form item.Function
resetFieldReset current field and remove validation result.Function
clearValidateRemove validation status of the field.Function

Type Declarations

Show declarations
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
  validateState: FormItemValidateState
  isGroup: boolean
  labelId: string
  inputIds: string[]
  hasLabel: boolean
  fieldValue: any
  addInputId: (id: string) => void
  removeInputId: (id: string) => void
  validate: (
    trigger: string,
    callback?: FormValidateCallback
  ) => FormValidationResult
  resetField(): void
  clearValidate(): void
}

Fuente

ComponentesDocumentación

Contribuidores