FormControl
class
Tracks the value and validation status of an individual form control.
class FormControl extends AbstractControl {
constructor(formState: any = null, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])
setValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void
patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void
reset(formState: any = null, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
registerOnChange(fn: Function): void
registerOnDisabledChange(fn: (isDisabled: boolean) => void): 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
}
See also
Description
This is one of the three fundamental building blocks of Angular forms, along with FormGroup
and FormArray
. It extends the AbstractControl
class that implements most of the base functionality for accessing the value, validation status, user interactions and events.
Constructor
Creates a new | |||||||||
|
formState | any | Initializes the control with an initial value, or an object that defines the initial value and disabled state. Optional. Default is |
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 |
Methods
setValue() | ||||||
---|---|---|---|---|---|---|
Sets a new value for the form control. | ||||||
|
value | any | The new value for the control. |
options | object | Configuration options that determine how the control propagates changes and emits events when the value changes. The configuration options are passed to the updateValueAndValidity method.
Optional. Default is |
Returns
void
patchValue() | ||||||
---|---|---|---|---|---|---|
Patches the value of a control. See also:
| ||||||
|
value | any | |
options | object | Optional. Default is |
Returns
void
This function is functionally the same as setValue at this level. It exists for symmetry with patchValue on FormGroups
and FormArrays
, where it does behave differently.
reset() | ||||||
---|---|---|---|---|---|---|
Resets the form control, marking it | ||||||
|
formState | 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 after the value changes.
Optional. Default is |
Returns
void
registerOnChange() | |||
---|---|---|---|
Register a listener for change events. | |||
|
fn | Function | The method that is called when the value changes |
Returns
void
registerOnDisabledChange() | |||
---|---|---|---|
Register a listener for disabled events. | |||
|
fn | (isDisabled: boolean) => void | The method that is called when the disabled status changes. |
Returns
void
Usage notes
Initializing Form Controls
Instantiate a FormControl
, with an initial value.
const control = new FormControl('some value');
console.log(control.value); // 'some value'
The following example initializes the control with a form state object. The value
and disabled
keys are required in this case.
const control = new FormControl({ value: 'n/a', disabled: true });
console.log(control.value); // 'n/a'
console.log(control.status); // 'DISABLED'
The following example initializes the control with a sync validator.
const control = new FormControl('', Validators.required);
console.log(control.value); // ''
console.log(control.status); // 'INVALID'
The following example initializes the control using an options object.
const control = new FormControl('', {
validators: Validators.required,
asyncValidators: myAsyncValidator
});
Configure the control to update on a blur event
Set the updateOn
option to 'blur'
to update on the blur event
.
const control = new FormControl('', { updateOn: 'blur' });
Configure the control to update on a submit event
Set the updateOn
option to 'submit'
to update on a submit event
.
const control = new FormControl('', { updateOn: 'submit' });
Reset the control back to an initial value
You reset to a specific form state by passing through a standalone value or a form state object that contains both a value and a disabled state (these are the only two properties that cannot be calculated).
const control = new FormControl('Nancy');
console.log(control.value); // 'Nancy'
control.reset('Drew');
console.log(control.value); // 'Drew'
Reset the control back to an initial value and disabled
const control = new FormControl('Nancy');
console.log(control.value); // 'Nancy'
console.log(control.status); // 'VALID'
control.reset({ value: 'Drew', disabled: true });
console.log(control.value); // 'Drew'
console.log(control.status); // 'DISABLED'
© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v8.angular.io/api/forms/FormControl