class
This is the base class for FormControl
, FormGroup
, and FormArray
.
abstract class AbstractControl { constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[]) value: any validator: ValidatorFn | null asyncValidator: AsyncValidatorFn | null parent: FormGroup | FormArray | null 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(validators: ValidatorFn | ValidatorFn[]): void setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void addValidators(validators: ValidatorFn | ValidatorFn[]): void addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void removeValidators(validators: ValidatorFn | ValidatorFn[]): void removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void hasValidator(validator: ValidatorFn): boolean hasAsyncValidator(validator: AsyncValidatorFn): boolean 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 }
It provides some of the shared behavior that all controls and groups of controls have, like running validators, calculating status, and resetting state. It also defines the properties that are shared between all sub-classes, like value
, valid
, and dirty
. It shouldn't be instantiated directly.
Initialize the AbstractControl instance. | ||||||
|
validators | ValidatorFn | ValidatorFn[] | The function or array of functions that is used to determine the validity of this control synchronously. |
asyncValidators | AsyncValidatorFn | AsyncValidatorFn[] | The function or array of functions that is used to determine validity of this control asynchronously. |
Property | Description |
---|---|
value: any | Read-Only The current value of the control.
|
validator: ValidatorFn | null | Returns the function that is used to determine the validity of this control synchronously. If multiple validators have been added, this will be a single composed function. See |
asyncValidator: AsyncValidatorFn | null | Returns the function that is used to determine the validity of this control asynchronously. If multiple validators have been added, this will be a single composed function. See |
parent: FormGroup | FormArray | null | Read-Only The parent control. |
status: string | Read-Only The validation status of the control. There are four possible validation status values:
These status values are mutually exclusive, so a control cannot be both valid AND invalid or invalid AND disabled. |
valid: boolean | Read-Only A control is See also: |
invalid: boolean | Read-Only A control is See also: |
pending: boolean | Read-Only A control is See also: |
disabled: boolean | Read-Only A control is Disabled controls are exempt from validation checks and are not included in the aggregate value of their ancestor controls. See also: |
enabled: boolean | Read-Only A control is See also: |
errors: ValidationErrors | null | Read-Only An object containing any errors generated by failing validation, or null if there are no errors. |
pristine: boolean | Read-Only A control is |
dirty: boolean | Read-Only A control is |
touched: boolean | Read-Only True if the control is marked as A control is marked |
untouched: boolean | Read-Only True if the control has not been marked as touched A control is |
valueChanges: Observable<any> | Read-Only A multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically. It also emits an event each time you call enable() or disable() without passing along {emitEvent: false} as a function argument. |
statusChanges: Observable<any> | Read-Only A multicasting observable that emits an event every time the validation See also: |
updateOn: FormHooks | Read-Only Reports the update strategy of the |
root: AbstractControl | Read-Only Retrieves the top-level ancestor of this control. |
setValidators() | |||
---|---|---|---|
Sets the synchronous validators that are active on this control. Calling this overwrites any existing synchronous validators. | |||
|
validators | ValidatorFn | ValidatorFn[] |
void
When you add or remove a validator at run time, you must call updateValueAndValidity()
for the new validation to take effect.
If you want to add a new validator without affecting existing ones, consider using addValidators()
method instead.
setAsyncValidators() | |||
---|---|---|---|
Sets the asynchronous validators that are active on this control. Calling this overwrites any existing asynchronous validators. | |||
|
validators | AsyncValidatorFn | AsyncValidatorFn[] |
void
When you add or remove a validator at run time, you must call updateValueAndValidity()
for the new validation to take effect.
If you want to add a new validator without affecting existing ones, consider using addAsyncValidators()
method instead.
addValidators() | |||
---|---|---|---|
Add a synchronous validator or validators to this control, without affecting other validators. | |||
|
validators | ValidatorFn | ValidatorFn[] | The new validator function or functions to add to this control. |
void
When you add or remove a validator at run time, you must call updateValueAndValidity()
for the new validation to take effect.
Adding a validator that already exists will have no effect. If duplicate validator functions are present in the validators
array, only the first instance would be added to a form control.
addAsyncValidators() | |||
---|---|---|---|
Add an asynchronous validator or validators to this control, without affecting other validators. | |||
|
validators | AsyncValidatorFn | AsyncValidatorFn[] | The new asynchronous validator function or functions to add to this control. |
void
When you add or remove a validator at run time, you must call updateValueAndValidity()
for the new validation to take effect.
Adding a validator that already exists will have no effect.
removeValidators() | |||
---|---|---|---|
Remove a synchronous validator from this control, without affecting other validators. Validators are compared by function reference; you must pass a reference to the exact same validator function as the one that was originally set. If a provided validator is not found, it is ignored. | |||
|
validators | ValidatorFn | ValidatorFn[] | The validator or validators to remove. |
void
When you add or remove a validator at run time, you must call updateValueAndValidity()
for the new validation to take effect.
removeAsyncValidators() | |||
---|---|---|---|
Remove an asynchronous validator from this control, without affecting other validators. Validators are compared by function reference; you must pass a reference to the exact same validator function as the one that was originally set. If a provided validator is not found, it is ignored. | |||
|
validators | AsyncValidatorFn | AsyncValidatorFn[] | The asynchronous validator or validators to remove. |
void
When you add or remove a validator at run time, you must call updateValueAndValidity()
for the new validation to take effect.
hasValidator() | |||
---|---|---|---|
Check whether a synchronous validator function is present on this control. The provided validator must be a reference to the exact same function that was provided. | |||
|
validator | ValidatorFn | The validator to check for presence. Compared by function reference. |
boolean
: Whether the provided validator was found on this control.
hasAsyncValidator() | |||
---|---|---|---|
Check whether an asynchronous validator function is present on this control. The provided validator must be a reference to the exact same function that was provided. | |||
|
validator | AsyncValidatorFn | The asynchronous validator to check for presence. Compared by function reference. |
boolean
: Whether the provided asynchronous validator was found on this control.
clearValidators() |
---|
Empties out the synchronous validator list. |
|
When you add or remove a validator at run time, you must call |
clearAsyncValidators() |
---|
Empties out the async validator list. |
|
When you add or remove a validator at run time, you must call |
markAsTouched() | |||
---|---|---|---|
Marks the control as See also:
| |||
|
opts | object | Configuration options that determine how the control propagates changes and emits events after marking is applied.
Optional. Default is |
void
markAllAsTouched() |
---|
Marks the control and all its descendant controls as See also:
|
|
markAsUntouched() | |||
---|---|---|---|
Marks the control as See also:
| |||
|
opts | object | Configuration options that determine how the control propagates changes and emits events after the marking is applied.
Optional. Default is |
void
If the control has any children, also marks all children as untouched
and recalculates the touched
status of all parent controls.
markAsDirty() | |||
---|---|---|---|
Marks the control as See also:
| |||
|
opts | object | Configuration options that determine how the control propagates changes and emits events after marking is applied.
Optional. Default is |
void
markAsPristine() | |||
---|---|---|---|
Marks the control as See also:
| |||
|
opts | object | Configuration options that determine how the control emits events after marking is applied.
Optional. Default is |
void
If the control has any children, marks all children as pristine
, and recalculates the pristine
status of all parent controls.
markAsPending() | |||
---|---|---|---|
Marks the control as See also: | |||
|
opts | object | Configuration options that determine how the control propagates changes and emits events after marking is applied.
Optional. Default is |
void
A control is pending while the control performs async validation.
disable() | |||
---|---|---|---|
Disables the control. This means the control is exempt from validation checks and excluded from the aggregate value of any parent. Its status is See also: | |||
|
opts | object | Configuration options that determine how the control propagates changes and emits events after the control is disabled.
Optional. Default is |
void
If the control has children, all children are also disabled.
enable() | |||
---|---|---|---|
Enables the control. This means the control is included in validation checks and the aggregate value of its parent. Its status recalculates based on its value and its validators. See also: | |||
|
opts | object | Configure options that control how the control propagates changes and emits events when marked as untouched
Optional. Default is |
void
By default, if the control has children, all children are enabled.
setParent() |
---|
setValue() | ||||||
---|---|---|---|---|---|---|
Sets the value of the control. Abstract method (implemented in sub-classes). | ||||||
|
value | any | |
options | Object | Optional. Default is |
void
patchValue() | ||||||
---|---|---|---|---|---|---|
Patches the value of the control. Abstract method (implemented in sub-classes). | ||||||
|
value | any | |
options | Object | Optional. Default is |
void
reset() | ||||||
---|---|---|---|---|---|---|
Resets the control. Abstract method (implemented in sub-classes). | ||||||
|
value | any | Optional. Default is |
options | Object | Optional. Default is |
void
updateValueAndValidity() | |||
---|---|---|---|
Recalculates the value and validation status of the control. | |||
|
opts | object | Configuration options determine how the control propagates changes and emits events after updates and validity checks are applied.
Optional. Default is |
void
By default, it also updates the value and validity of its ancestors.
setErrors() | ||||||
---|---|---|---|---|---|---|
Sets errors on a form control when running validations manually, rather than automatically. | ||||||
|
errors | ValidationErrors | |
opts | object | Optional. Default is |
void
Calling setErrors
also updates the validity of the parent control.
const login = new FormControl('someLogin'); login.setErrors({ notUnique: true }); expect(login.valid).toEqual(false); expect(login.errors).toEqual({ notUnique: true }); login.setValue('someOtherLogin'); expect(login.valid).toEqual(true);
get() | |||
---|---|---|---|
Retrieves a child control given the control's name or path. | |||
|
path | string | (string | number)[] | A dot-delimited string or array of string/number values that define the path to the control. |
AbstractControl | null
For example, to get a name
control nested within a person
sub-group:
this.form.get('person.name');
-OR-
this.form.get(['person', 'name']);
When accessing an element inside a FormArray, you can use an element index. For example, to get a price
control from the first element in an items
array you can use:
this.form.get('items.0.price');
-OR-
this.form.get(['items', 0, 'price']);
getError() | ||||||
---|---|---|---|---|---|---|
Reports error data for the control with the given path. | ||||||
|
errorCode | string | The code of the error to check |
path | string | (string | number)[] | A list of control names that designates how to move from the current control to the control that should be queried for errors. Optional. Default is |
any
: error data for that particular error. If the control or error is not present, null is returned.
For example, for the following FormGroup
:
form = new FormGroup({ address: new FormGroup({ street: new FormControl() }) });
The path to the 'street' control from the root form would be 'address' -> 'street'.
It can be provided to this method in one of two formats:
['address', 'street']
'address.street'
hasError() | ||||||
---|---|---|---|---|---|---|
Reports whether the control with the given path has the error specified. | ||||||
|
errorCode | string | The code of the error to check |
path | string | (string | number)[] | A list of control names that designates how to move from the current control to the control that should be queried for errors. Optional. Default is |
boolean
: whether the given error is present in the control at the given path.
If the control is not present, false is returned.
For example, for the following FormGroup
:
form = new FormGroup({ address: new FormGroup({ street: new FormControl() }) });
The path to the 'street' control from the root form would be 'address' -> 'street'.
It can be provided to this method in one of two formats:
['address', 'street']
'address.street'
If no path is given, this method checks for the error on the current control.
© 2010–2021 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v12.angular.io/api/forms/AbstractControl