class
Tracks the value and validity state of an array of FormControl
, FormGroup
or FormArray
instances.
class FormArray extends AbstractControl { constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]) controls: AbstractControl[] length: number at(index: number): AbstractControl push(control: AbstractControl): void insert(index: number, control: AbstractControl): void removeAt(index: number): void setControl(index: number, control: AbstractControl): void setValue(value: any[], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void patchValue(value: any[], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void reset(value: any = [], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void getRawValue(): any[] clear(): void // inherited from forms/AbstractControl constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[]) value: any validator: ValidatorFn | null asyncValidator: AsyncValidatorFn | null parent: FormGroup | FormArray status: string valid: boolean invalid: boolean pending: boolean disabled: boolean enabled: boolean errors: ValidationErrors | null pristine: boolean dirty: boolean touched: boolean untouched: boolean valueChanges: Observable<any> statusChanges: Observable<any> updateOn: FormHooks root: AbstractControl setValidators(newValidator: ValidatorFn | ValidatorFn[]): void setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void clearValidators(): void clearAsyncValidators(): void markAsTouched(opts: { onlySelf?: boolean; } = {}): void markAllAsTouched(): void markAsUntouched(opts: { onlySelf?: boolean; } = {}): void markAsDirty(opts: { onlySelf?: boolean; } = {}): void markAsPristine(opts: { onlySelf?: boolean; } = {}): void markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void setParent(parent: FormGroup | FormArray): void abstract setValue(value: any, options?: Object): void abstract patchValue(value: any, options?: Object): void abstract reset(value?: any, options?: Object): void updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void get(path: string | (string | number)[]): AbstractControl | null getError(errorCode: string, path?: string | (string | number)[]): any hasError(errorCode: string, path?: string | (string | number)[]): boolean }
A FormArray
aggregates the values of each child FormControl
into an array. It calculates its status by reducing the status values of its children. For example, if one of the controls in a FormArray
is invalid, the entire array becomes invalid.
FormArray
is one of the three fundamental building blocks used to define forms in Angular, along with FormControl
and FormGroup
.
Creates a new | |||||||||
|
controls | AbstractControl[] | An array of child controls. Each child control is given an index where it is registered. |
validatorOrOpts | ValidatorFn | AbstractControlOptions | ValidatorFn[] | A synchronous validator function, or an array of such functions, or an Optional. Default is |
asyncValidator | AsyncValidatorFn | AsyncValidatorFn[] | A single async validator or array of async validator functions Optional. Default is |
Property | Description |
---|---|
controls: AbstractControl[] | Declared in Constructor An array of child controls. Each child control is given an index where it is registered. |
length: number |
Read-Only Length of the control array. |
at() | |||
---|---|---|---|
Get the | |||
|
index | number | Index in the array to retrieve the control |
push() | |||
---|---|---|---|
Insert a new | |||
|
control | AbstractControl | Form control to be inserted |
void
insert() | ||||||
---|---|---|---|---|---|---|
Insert a new | ||||||
|
index | number | Index in the array to insert the control |
control | AbstractControl | Form control to be inserted |
void
removeAt() | |||
---|---|---|---|
Remove the control at the given | |||
|
index | number | Index in the array to remove the control |
void
setControl() | ||||||
---|---|---|---|---|---|---|
Replace an existing control. | ||||||
|
index | number | Index in the array to replace the control |
control | AbstractControl | The |
void
setValue() | ||||||
---|---|---|---|---|---|---|
Sets the value of the | ||||||
|
value | any[] | Array of values for the controls |
options | object | Configure options that determine how the control propagates changes and emits events after the value changes
Optional. Default is |
void
This method performs strict checks, and throws an error if you try to set the value of a control that doesn't exist or if you exclude the value of a control.
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() | ||||||
---|---|---|---|---|---|---|
Patches the value of the | ||||||
|
value | any[] | Array of latest values for the controls |
options | object | Configure options that determine how the control propagates changes and emits events after the value changes
Optional. Default is |
void
It accepts both super-sets and sub-sets of the array without throwing an error.
const arr = new FormArray([ new FormControl(), new FormControl() ]); console.log(arr.value); // [null, null] arr.patchValue(['Nancy']); console.log(arr.value); // ['Nancy', null]
reset() | ||||||
---|---|---|---|---|---|---|
Resets the | ||||||
|
value | any | Array of values for the controls Optional. Default is |
options | object | Configure options that determine how the control propagates changes and emits events after the value changes
Optional. Default is |
void
You reset to a specific form state by passing in an array of states that matches the structure of the control. The state is a standalone value or a form state object with both a value and a disabled status.
const arr = new FormArray([ new FormControl(), new FormControl() ]); arr.reset(['name', 'last name']); console.log(this.arr.value); // ['name', 'last name']
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() |
---|
The aggregate value of the array, including any disabled controls. |
|
Reports all values regardless of disabled status. For enabled controls only, the |
clear() |
---|
Remove all controls in the |
|
Usage NotesRemove all elements from a FormArrayconst arr = new FormArray([ new FormControl(), new FormControl() ]); console.log(arr.length); // 2 arr.clear(); console.log(arr.length); // 0 It's a simpler and more efficient alternative to removing all elements one by one: const arr = new FormArray([ new FormControl(), new FormControl() ]); while (arr.length) { arr.removeAt(0); } |
const arr = new FormArray([ new FormControl('Nancy', Validators.minLength(2)), new FormControl('Drew'), ]); console.log(arr.value); // ['Nancy', 'Drew'] console.log(arr.status); // 'VALID'
You include array-level validators and async validators. These come in handy when you want to perform validation that considers the value of more than one child control.
The two types of validators are passed in separately as the second and third arg respectively, or together as part of an options object.
const arr = new FormArray([ new FormControl('Nancy'), new FormControl('Drew') ], {validators: myValidator, asyncValidators: myAsyncValidator});
The options object is used to set a default value for each child control's updateOn
property. If you set updateOn
to 'blur'
at the array level, all child controls default to 'blur', unless the child has explicitly specified a different updateOn
value.
const arr = new FormArray([ new FormControl() ], {updateOn: 'blur'});
To change the controls in the array, use the push
, insert
, removeAt
or clear
methods in FormArray
itself. These methods ensure the controls are properly tracked in the form's hierarchy. Do not modify the array of AbstractControl
s used to instantiate the FormArray
directly, as that result in strange and unexpected behavior such as broken change detection.
© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v10.angular.io/api/forms/FormArray