class
Tracks the value and validity state of a group of FormControl
instances.
class FormGroup extends AbstractControl { constructor(controls: { [key: string]: AbstractControl; }, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]) controls: {...} registerControl(name: string, control: AbstractControl): AbstractControl addControl(name: string, control: AbstractControl): void removeControl(name: string): void setControl(name: string, control: AbstractControl): void contains(controlName: string): boolean setValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void patchValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void reset(value: any = {}, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void getRawValue(): any // 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 FormGroup
aggregates the values of each child FormControl
into one object, with each control name as the key. It calculates its status by reducing the status values of its children. For example, if one of the controls in a group is invalid, the entire group becomes invalid.
FormGroup
is one of the three fundamental building blocks used to define forms in Angular, along with FormControl
and FormArray
.
When instantiating a FormGroup
, pass in a collection of child controls as the first argument. The key for each child registers the name for the control.
Creates a new | |||||||||
|
controls | object | A collection of child controls. The key for each child is the name under which 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: {
[key: string]: AbstractControl;
} | Declared in Constructor A collection of child controls. The key for each child is the name under which it is registered. |
registerControl() | ||||||
---|---|---|---|---|---|---|
Registers a control with the group's list of controls. | ||||||
|
name | string | The control name to register in the collection |
control | AbstractControl | Provides the control for the given name |
This method does not update the value or validity of the control. Use addControl instead.
addControl() | ||||||
---|---|---|---|---|---|---|
Add a control to this group. | ||||||
|
name | string | The control name to add to the collection |
control | AbstractControl | Provides the control for the given name |
void
This method also updates the value and validity of the control.
removeControl() | |||
---|---|---|---|
Remove a control from this group. | |||
|
name | string | The control name to remove from the collection |
void
setControl() | ||||||
---|---|---|---|---|---|---|
Replace an existing control. | ||||||
|
name | string | The control name to replace in the collection |
control | AbstractControl | Provides the control for the given name |
void
contains() | |||
---|---|---|---|
Check whether there is an enabled control with the given name in the group. | |||
|
controlName | string | The control name to check for existence in the collection |
boolean
: false for disabled controls, true otherwise.
Reports false for disabled controls. If you'd like to check for existence in the group only, use get instead.
setValue() | ||||||
---|---|---|---|---|---|---|
Sets the value of the | ||||||
|
value | object | The new value for the control that matches the structure of the group. |
options | object | Configuration options that determine how the control propagates changes and emits events after the value changes. The configuration options are passed to the updateValueAndValidity method.
Optional. Default is |
void
Error
When strict checks fail, such as setting the value of a control that doesn't exist or if you exclude a value of a control that does exist.
const form = new FormGroup({ first: new FormControl(), last: new FormControl() }); console.log(form.value); // {first: null, last: null} form.setValue({first: 'Nancy', last: 'Drew'}); console.log(form.value); // {first: 'Nancy', last: 'Drew'}
patchValue() | ||||||
---|---|---|---|---|---|---|
Patches the value of the | ||||||
|
value | object | The object that matches the structure of the group. |
options | object | Configuration options that determine how the control propagates changes and emits events after the value is patched.
Optional. Default is |
void
It accepts both super-sets and sub-sets of the group without throwing an error.
const form = new FormGroup({ first: new FormControl(), last: new FormControl() }); console.log(form.value); // {first: null, last: null} form.patchValue({first: 'Nancy'}); console.log(form.value); // {first: 'Nancy', last: null}
reset() | ||||||
---|---|---|---|---|---|---|
Resets the | ||||||
|
value | any | Resets the control with an initial value, or an object that defines the initial value and disabled state. Optional. Default is |
options | object | Configuration options that determine how the control propagates changes and emits events when the group is reset.
Optional. Default is |
void
You reset to a specific form state by passing in a map of states that matches the structure of your form, with control names as keys. The state is a standalone value or a form state object with both a value and a disabled status.
const form = new FormGroup({ first: new FormControl('first name'), last: new FormControl('last name') }); console.log(form.value); // {first: 'first name', last: 'last name'} form.reset({ first: 'name', last: 'last name' }); console.log(form.value); // {first: 'name', last: 'last name'}
const form = new FormGroup({ first: new FormControl('first name'), last: new FormControl('last name') }); form.reset({ first: {value: 'name', disabled: true}, last: 'last' }); console.log(this.form.value); // {first: 'name', last: 'last name'} console.log(this.form.get('first').status); // 'DISABLED'
getRawValue() |
---|
The aggregate value of the |
|
Retrieves all values regardless of disabled status. The |
const form = new FormGroup({ first: new FormControl('Nancy', Validators.minLength(2)), last: new FormControl('Drew'), }); console.log(form.value); // {first: 'Nancy', last; 'Drew'} console.log(form.status); // 'VALID'
You include group-level validators as the second arg, or group-level async validators as the third arg. These come in handy when you want to perform validation that considers the value of more than one child control.
const form = new FormGroup({ password: new FormControl('', Validators.minLength(2)), passwordConfirm: new FormControl('', Validators.minLength(2)), }, passwordMatchValidator); function passwordMatchValidator(g: FormGroup) { return g.get('password').value === g.get('passwordConfirm').value ? null : {'mismatch': true}; }
Like FormControl
instances, you choose to pass in validators and async validators as part of an options object.
const form = new FormGroup({ password: new FormControl('') passwordConfirm: new FormControl('') }, { validators: passwordMatchValidator, asyncValidators: otherValidator });
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 group level, all child controls default to 'blur', unless the child has explicitly specified a different updateOn
value.
const c = new FormGroup({ one: new FormControl() }, { updateOn: 'blur' });
© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v10.angular.io/api/forms/FormGroup