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(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(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
AbstractControl
- Reactive Forms Guide
- Usage Notes
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. See usage examples below.
Further information available in the Usage Notes...
Constructor
Creates a new FormControl instance.
| |||||||||
constructor(formState: any = null, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])Parameters
|
Methods
setValue() | ||||||
---|---|---|---|---|---|---|
Sets a new value for the form control. | ||||||
setValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): voidParameters
Returns
|
patchValue() | ||||||
---|---|---|---|---|---|---|
Patches the value of a control. See also:
| ||||||
patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): voidParameters
Returns
| ||||||
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 pristine and untouched , and setting the value to null.
| ||||||
reset(formState: any = null, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): voidParameters
Returns
|
registerOnChange() | |||
---|---|---|---|
Register a listener for change events. | |||
registerOnChange(fn: Function): voidParameters
Returns
|
registerOnDisabledChange() | |||
---|---|---|---|
Register a listener for disabled events. | |||
registerOnDisabledChange(fn: (isDisabled: boolean) => void): voidParameters
Returns
|
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–2021 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v11.angular.io/api/forms/FormControl