class

Realiza un seguimiento del valor y el estado de validez de una matriz de FormControl, FormGroup o FormArray instancias.

Ver más…

classFormArrayextendsAbstractControlnull
  parent: FormGroup

Descripción

A FormArray agrega los valores de cada niño FormControl en una matriz. Calcula su estado reduciendo los valores de estado de sus hijos. Por ejemplo, si uno de los controles en un FormArray no es válido, toda la matriz deja de ser válida.

FormArray es uno de los tres bloques de construcción fundamentales que se utilizan para definir formas en Angular, junto con FormControl y FormGroup.

Más información disponible en las Notas de uso …

Constructor

Crea un nuevo FormArray ejemplo.

constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])

Parámetros
controls AbstractControl[]

Una matriz de controles secundarios. A cada control secundario se le asigna un índice donde está registrado.
validatorOrOpts ValidatorFn | AbstractControlOptions | ValidatorFn[]

Una función de validación síncrona, o una matriz de tales funciones, o una AbstractControlOptions objeto que contiene funciones de validación y un disparador de validación.

Opcional. El valor predeterminado es undefined.
asyncValidator AsyncValidatorFn | AsyncValidatorFn[]

Un solo validador asíncrono o matriz de funciones de validador asíncrono

Opcional. El valor predeterminado es undefined.

Propiedades

Propiedad Descripción
controls: AbstractControl[] Declarado en Constructor

Una matriz de controles secundarios. A cada control secundario se le asigna un índice donde se registra.
length: number Solo lectura

Longitud de la matriz de control.

Métodos

a()

Consigue el AbstractControl en el dado index en la matriz.

at(index: number): AbstractControl

Parámetros
index number

Índice en la matriz para recuperar el control
Devoluciones

AbstractControl
empujar()

Insertar un nuevo AbstractControl al final de la matriz.

push(control: AbstractControl, options: emitEvent?: boolean; = ): void

Parámetros
control AbstractControl

Control de formulario para insertar
options object

Especifica si esta instancia de FormArray debe emitir eventos después de agregar un nuevo control.

  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se inserta el control. Cuando es falso, no se emiten eventos.

Opcional. El valor predeterminado es .
Devoluciones

void
insertar()

Insertar un nuevo AbstractControl en el dado index en la matriz.

insert(index: number, control: AbstractControl, options: emitEvent?: boolean; = ): void

Parámetros
index number

Índice en la matriz para insertar el control
control AbstractControl

Control de formulario para insertar
options object

Especifica si esta instancia de FormArray debe emitir eventos después de insertar un nuevo control.

  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se inserta el control. Cuando es falso, no se emiten eventos.

Opcional. El valor predeterminado es .
Devoluciones

void
removeAt ()

Quite el control en el dado index en la matriz.

removeAt(index: number, options: emitEvent?: boolean; = ): void

Parámetros
index number

Índice en la matriz para eliminar el control
options object

Especifica si esta instancia de FormArray debe emitir eventos después de eliminar un control.

  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se quita el control. Cuando es falso, no se emiten eventos.

Opcional. El valor predeterminado es .
Devoluciones

void
setControl ()

Reemplazar un control existente.

setControl(index: number, control: AbstractControl, options: emitEvent?: boolean; = ): void

Parámetros
index number

Índice en la matriz para reemplazar el control
control AbstractControl

los AbstractControl control para reemplazar el control existente
options object

Especifica si esta instancia de FormArray debe emitir eventos después de que un control existente se reemplace por uno nuevo.

  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando el control es reemplazado por uno nuevo. Cuando es falso, no se emiten eventos.

Opcional. El valor predeterminado es .
Devoluciones

void
valor ajustado()

Establece el valor de la FormArray. Acepta una matriz que coincide con la estructura del control.

setValue(value: any[], options: onlySelf?: boolean; emitEvent?: boolean; = ): void

Parámetros
value any[]

Matriz de valores para los controles
options object

Configurar opciones que determinan cómo el control propaga los cambios y emite eventos después de que cambia el valor.

  • onlySelf: Cuando es verdadero, cada cambio solo afecta a este control y no a su padre. El valor predeterminado es falso.
  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se actualiza el valor de control. Cuando es falso, no se emiten eventos. Las opciones de configuración se pasan al método updateValueAndValidity.

Opcional. El valor predeterminado es .
Devoluciones

void

Este método realiza comprobaciones estrictas y arroja un error si intenta establecer el valor de un control que no existe o si excluye el valor de un control.

Notas de uso

Establecer los valores para los controles en la matriz de formularios
const arr = new FormArray([
  new FormControl(),
  new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.setValue(['Nancy', 'Drew']);
console.log(arr.value);   // ['Nancy', 'Drew']
patchValue ()

Parcha el valor del FormArray. Acepta una matriz que coincide con la estructura del control y hace todo lo posible para hacer coincidir los valores con los controles correctos del grupo.

patchValue(value: any[], options: onlySelf?: boolean; emitEvent?: boolean; = ): void

Parámetros
value any[]

Matriz de valores más recientes para los controles
options object

Configurar opciones que determinan cómo el control propaga los cambios y emite eventos después de que cambia el valor.

  • onlySelf: Cuando es verdadero, cada cambio solo afecta a este control y no a su padre. El valor predeterminado es falso.
  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se actualiza el valor de control. Cuando es falso, no se emiten eventos. Las opciones de configuración se pasan al método updateValueAndValidity.

Opcional. El valor predeterminado es .
Devoluciones

void

Acepta superconjuntos y subconjuntos de la matriz sin arrojar un error.

Notas de uso

Parchear los valores de los controles en una matriz de formulario
const arr = new FormArray([
   new FormControl(),
   new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.patchValue(['Nancy']);
console.log(arr.value);   // ['Nancy', null]
Reiniciar()

Restablece el FormArray y todos los descendientes están marcados pristine y untouchedy el valor de todos los descendientes de mapas nulos o nulos.

reset(value: any = [], options: onlySelf?: boolean; emitEvent?: boolean; = ): void

Parámetros
value any

Matriz de valores para los controles

Opcional. El valor predeterminado es [].
options object

Configurar opciones que determinan cómo el control propaga los cambios y emite eventos después de que cambia el valor.

  • onlySelf: Cuando es verdadero, cada cambio solo afecta a este control y no a su padre. El valor predeterminado es falso.
  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se reinicia el control. Cuando es falso, no se emiten eventos. Las opciones de configuración se pasan al método updateValueAndValidity.

Opcional. El valor predeterminado es .
Devoluciones

void

Se restablece a un estado de formulario específico pasando una matriz de estados que coincida con la estructura del control. El estado es un valor independiente o un objeto de estado de formulario con un valor y un estado desactivado.

Notas de uso

Restablecer los valores en una matriz de formulario
const arr =newFormArray([newFormControl(),newFormControl()]);
arr.reset(['name','last name']);console.log(this.arr.value);// ['name', 'last name']
Restablecer los valores en una matriz de formularios y el estado deshabilitado para el primer control
this.arr.reset([
  value: 'name', disabled: true,
  'last'
]);

console.log(this.arr.value);  // ['name', 'last name']
console.log(this.arr.get(0).status);  // 'DISABLED'
getRawValue ()

El valor agregado de la matriz, incluidos los controles deshabilitados.

getRawValue(): any[]

Parámetros

No hay parámetros.

Devoluciones

any[]

Reporta todos los valores independientemente del estado desactivado. Solo para controles habilitados, el value property es la mejor manera de obtener el valor de la matriz.
claro()

Quite todos los controles en el FormArray.

clear(options: emitEvent?: boolean; = ): void

Parámetros
options object

Especifica si esta instancia de FormArray debe emitir eventos después de que se eliminen todos los controles.

  • emitEvent: Cuando es verdadero o no se proporciona (el valor predeterminado), tanto el statusChanges y valueChanges Los observables emiten eventos con el último estado y valor cuando se eliminan todos los controles en esta instancia de FormArray. Cuando es falso, no se emiten eventos.

Opcional. El valor predeterminado es .
Devoluciones

void

Notas de uso

Eliminar todos los elementos de un FormArray
const arr =newFormArray([newFormControl(),newFormControl()]);console.log(arr.length);// 2

arr.clear();console.log(arr.length);// 0

Es una alternativa más simple y eficiente que eliminar todos los elementos uno por uno:

const arr =newFormArray([newFormControl(),newFormControl()]);while(arr.length)
   arr.removeAt(0);

Notas de uso

Crea una matriz de controles de formulario

const arr = new FormArray([
  new FormControl('Nancy', Validators.minLength(2)),
  new FormControl('Drew'),
]);

console.log(arr.value);   // ['Nancy', 'Drew']
console.log(arr.status);  // 'VALID'

Cree una matriz de formulario con validadores de nivel de matriz

Incluye validadores de nivel de matriz y validadores asíncronos. Estos son útiles cuando desea realizar una validación que considere el valor de más de un control secundario.

Los dos tipos de validadores se pasan por separado como segundo y tercer argumento respectivamente, o juntos como parte de un objeto de opciones.

const arr = new FormArray([
  new FormControl('Nancy'),
  new FormControl('Drew')
], validators: myValidator, asyncValidators: myAsyncValidator);

Establecer la propiedad updateOn para todos los controles en una matriz de formulario

El objeto de opciones se utiliza para establecer un valor predeterminado para cada control secundario updateOn propiedad. Si pones updateOn para 'blur' en el nivel de la matriz, todos los controles secundarios están predeterminados en ‘desenfoque’, a menos que el niño haya especificado explícitamente una diferente updateOn valor.

const arr =newFormArray([newFormControl()],updateOn:'blur');

Agregar o quitar controles de una matriz de formularios

Para cambiar los controles en la matriz, use el push, insert, removeAt o clear métodos en FormArray sí mismo. Estos métodos garantizan que se realice un seguimiento adecuado de los controles en la jerarquía del formulario. No modifique la matriz de AbstractControlse utiliza para instanciar el FormArray directamente, ya que eso da como resultado un comportamiento extraño e inesperado, como la detección de cambios rotos.