What it does
This is the base class for FormControl
, FormGroup
, and
FormArray
.
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.
Class Overview
class AbstractControl {
constructor
(validator: ValidatorFn, asyncValidator: AsyncValidatorFn)
validator
: ValidatorFn
asyncValidator
: AsyncValidatorFn
value
: any
parent
: FormGroup|FormArray
status
: string
valid
: boolean
invalid
: boolean
pending
: boolean
disabled
: boolean
enabled
: boolean
errors
: {[key: string]: any}
pristine
: boolean
dirty
: boolean
touched
: boolean
untouched
: boolean
valueChanges
: Observable<any>
statusChanges
: Observable<any>
setValidators
(newValidator: ValidatorFn|ValidatorFn[]) : void
setAsyncValidators
(newValidator: AsyncValidatorFn|AsyncValidatorFn[]) : void
clearValidators
() : void
clearAsyncValidators
() : void
markAsTouched
({onlySelf}?: {onlySelf?: boolean}) : void
markAsUntouched
({onlySelf}?: {onlySelf?: boolean}) : void
markAsDirty
({onlySelf}?: {onlySelf?: boolean}) : void
markAsPristine
({onlySelf}?: {onlySelf?: boolean}) : void
markAsPending
({onlySelf}?: {onlySelf?: boolean}) : void
disable
({onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
enable
({onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
setParent
(parent: FormGroup|FormArray) : void
setValue
(value: any, options?: Object) : void
patchValue
(value: any, options?: Object) : void
reset
(value?: any, options?: Object) : void
updateValueAndValidity
({onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
setErrors
(errors: {[key: string]: any}, {emitEvent}?: {emitEvent?: boolean}) : void
get
(path: Array<string|number>|string) : AbstractControl
getError
(errorCode: string, path?: string[]) : any
hasError
(errorCode: string, path?: string[]) : boolean
root
: AbstractControl
}
Class Description
Class Details
validator : ValidatorFn
asyncValidator : AsyncValidatorFn
value : any
The value of the control.
parent : FormGroup|FormArray
The parent control.
status : string
The validation status of the control. There are four possible validation statuses:
- VALID: control has passed all validation checks
- INVALID: control has failed at least one validation check
- PENDING: control is in the midst of conducting a validation check
- DISABLED: control is exempt from validation checks
These statuses are mutually exclusive, so a control cannot be both valid AND invalid or invalid AND disabled.
valid : boolean
A control is valid
when its status === VALID
.
In order to have this status, the control must have passed all its validation checks.
invalid : boolean
A control is invalid
when its status === INVALID
.
In order to have this status, the control must have failed at least one of its validation checks.
pending : boolean
A control is pending
when its status === PENDING
.
In order to have this status, the control must be in the middle of conducting a validation check.
disabled : boolean
A control is disabled
when its status === DISABLED
.
Disabled controls are exempt from validation checks and are not included in the aggregate value of their ancestor controls.
enabled : boolean
A control is enabled
as long as its status !== DISABLED
.
In other words, it has a status of VALID
, INVALID
, or
PENDING
.
errors : {[key: string]: any}
Returns any errors generated by failing validation. If there are no errors, it will return null.
pristine : boolean
A control is pristine
if the user has not yet changed
the value in the UI.
Note that programmatic changes to a control's value will not mark it dirty.
dirty : boolean
A control is dirty
if the user has changed the value
in the UI.
Note that programmatic changes to a control's value will not mark it dirty.
touched : boolean
A control is marked touched
once the user has triggered
a blur
event on it.
untouched : boolean
A control is untouched
if the user has not yet triggered
a blur
event on it.
valueChanges : Observable<any>
Emits an event every time the value of the control changes, in the UI or programmatically.
statusChanges : Observable<any>
Emits an event every time the validation status of the control is re-calculated.
setValidators(newValidator: ValidatorFn|ValidatorFn[]) : void
Sets the synchronous validators that are active on this control. Calling this will overwrite any existing sync validators.
setAsyncValidators(newValidator: AsyncValidatorFn|AsyncValidatorFn[]) : void
Sets the async validators that are active on this control. Calling this will overwrite any existing async validators.
clearValidators() : void
Empties out the sync validator list.
clearAsyncValidators() : void
Empties out the async validator list.
markAsTouched({onlySelf}?: {onlySelf?: boolean}) : void
Marks the control as touched
.
This will also mark all direct ancestors as touched
to maintain
the model.
markAsUntouched({onlySelf}?: {onlySelf?: boolean}) : void
Marks the control as untouched
.
If the control has any children, it will also mark all children as untouched
to maintain the model, and re-calculate the touched
status of all parent
controls.
markAsDirty({onlySelf}?: {onlySelf?: boolean}) : void
Marks the control as dirty
.
This will also mark all direct ancestors as dirty
to maintain
the model.
markAsPristine({onlySelf}?: {onlySelf?: boolean}) : void
Marks the control as pristine
.
If the control has any children, it will also mark all children as pristine
to maintain the model, and re-calculate the pristine
status of all parent
controls.
markAsPending({onlySelf}?: {onlySelf?: boolean}) : void
Marks the control as pending
.
disable({onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
Disables the control. This means the control will be exempt from validation checks and
excluded from the aggregate value of any parent. Its status is DISABLED
.
If the control has children, all children will be disabled to maintain the model.
enable({onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
Enables the control. This means the control will be included in validation checks and the aggregate value of its parent. Its status is re-calculated based on its value and its validators.
If the control has children, all children will be enabled.
setParent(parent: FormGroup|FormArray) : void
setValue(value: any, options?: Object) : void
Sets the value of the control. Abstract method (implemented in sub-classes).
patchValue(value: any, options?: Object) : void
Patches the value of the control. Abstract method (implemented in sub-classes).
reset(value?: any, options?: Object) : void
Resets the control. Abstract method (implemented in sub-classes).
updateValueAndValidity({onlySelf, emitEvent}?: {onlySelf?: boolean, emitEvent?: boolean}) : void
Re-calculates the value and validation status of the control.
By default, it will also update the value and validity of its ancestors.
setErrors(errors: {[key: string]: any}, {emitEvent}?: {emitEvent?: boolean}) : void
Sets errors on a form control.
This is used when validations are run manually by the user, rather than automatically.
Calling setErrors
will also update the validity of the parent control.
get(path: Array<string|number>|string) : AbstractControl
Retrieves a child control given the control's name or path.
Paths can be passed in as an array or a string delimited by a dot.
To get a control nested within a person
sub-group:
this.form.get('person.name');
-OR-
this.form.get(['person', 'name']);
getError(errorCode: string, path?: string[]) : any
Returns true if the control with the given path has the error specified. Otherwise returns null or undefined.
If no path is given, it checks for the error on the present control.
hasError(errorCode: string, path?: string[]) : boolean
Returns true if the control with the given path has the error specified. Otherwise returns false.
If no path is given, it checks for the error on the present control.
root : AbstractControl
Retrieves the top-level ancestor of this control.
exported from @angular/forms/index, defined in @angular/forms/src/model.ts