FormArray
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(validator: ValidatorFn, asyncValidator: 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
}
Description
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
.
Constructor
Creates a new FormArray instance.
| |||||||||
constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])Parameters
|
Properties
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. |
Methods
at() | |||
---|---|---|---|
Get the AbstractControl at the given index in the array.
| |||
at(index: number): AbstractControlParameters
Returns
|
push() | |||
---|---|---|---|
Insert a new AbstractControl at the end of the array.
| |||
push(control: AbstractControl): voidParameters
Returns
|
insert() | ||||||
---|---|---|---|---|---|---|
Insert a new AbstractControl at the given index in the array.
| ||||||
insert(index: number, control: AbstractControl): voidParameters
Returns
|
removeAt() | |||
---|---|---|---|
Remove the control at the given index in the array.
| |||
removeAt(index: number): voidParameters
Returns
|
setControl() | ||||||
---|---|---|---|---|---|---|
Replace an existing control. | ||||||
setControl(index: number, control: AbstractControl): voidParameters
Returns
|
setValue() | ||||||
---|---|---|---|---|---|---|
Sets the value of the FormArray . It accepts an array that matches the structure of the control.
| ||||||
setValue(value: any[], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): voidParameters
Returns
| ||||||
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. | ||||||
Usage NotesSet the values for the controls in the form arrayconst 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 FormArray . It accepts an array that matches the structure of the control, and does its best to match the values to the correct controls in the group.
| ||||||
patchValue(value: any[], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): voidParameters
Returns
| ||||||
It accepts both super-sets and sub-sets of the array without throwing an error. | ||||||
Usage NotesPatch the values for controls in a form arrayconst 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 FormArray and all descendants are marked pristine and untouched , and the value of all descendants to null or null maps.
| ||||||
reset(value: any = [], options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): voidParameters
Returns
| ||||||
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. | ||||||
Usage NotesReset the values in a form array
Reset the values in a form array and the disabled status for the first controlthis.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. |
getRawValue(): any[]ParametersThere are no parameters. Returns
|
Reports all values regardless of disabled status. For enabled controls only, the value property is the best way to get the value of the array.
|
clear() |
---|
Remove all controls in the FormArray .
|
clear(): voidParametersThere are no parameters. Returns
|
Usage NotesRemove all elements from a FormArray
It's a simpler and more efficient alternative to removing all elements one by one:
|
Usage notes
Create an array of form controls
const arr = new FormArray([ new FormControl('Nancy', Validators.minLength(2)), new FormControl('Drew'), ]); console.log(arr.value); // ['Nancy', 'Drew'] console.log(arr.status); // 'VALID'
Create a form array with array-level validators
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});
Set the updateOn property for all controls in a form array
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'});
Adding or removing controls from a form array
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://v8.angular.io/api/forms/FormArray