/** * @license Angular v10.0.1 * (c) 2010-2020 Google LLC. https://angular.io/ * License: MIT */ import { AfterViewInit } from '@angular/core'; import { ElementRef } from '@angular/core'; import { EventEmitter } from '@angular/core'; import { InjectionToken } from '@angular/core'; import { Injector } from '@angular/core'; import { ModuleWithProviders } from '@angular/core'; import { Observable } from 'rxjs'; import { OnChanges } from '@angular/core'; import { OnDestroy } from '@angular/core'; import { OnInit } from '@angular/core'; import { Renderer2 } from '@angular/core'; import { SimpleChanges } from '@angular/core'; import { StaticProvider } from '@angular/core'; import { Type } from '@angular/core'; import { Version } from '@angular/core'; /** * 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. * * @see [Forms Guide](/guide/forms) * @see [Reactive Forms Guide](/guide/reactive-forms) * @see [Dynamic Forms Guide](/guide/dynamic-form) * * @publicApi */ export declare abstract class AbstractControl { validator: ValidatorFn | null; asyncValidator: AsyncValidatorFn | null; private _parent; private _asyncValidationSubscription; /** * The current value of the control. * * * For a `FormControl`, the current value. * * For an enabled `FormGroup`, the values of enabled controls as an object * with a key-value pair for each member of the group. * * For a disabled `FormGroup`, the values of all controls as an object * with a key-value pair for each member of the group. * * For a `FormArray`, the values of enabled controls as an array. * */ readonly value: any; /** * Initialize the AbstractControl instance. * * @param validator The function that determines the synchronous validity of this control. * @param asyncValidator The function that determines the asynchronous validity of this * control. */ constructor(validator: ValidatorFn | null, asyncValidator: AsyncValidatorFn | null); /** * The parent control. */ get parent(): FormGroup | FormArray; /** * The validation status of the control. There are four possible * validation status values: * * * **VALID**: This control has passed all validation checks. * * **INVALID**: This control has failed at least one validation check. * * **PENDING**: This control is in the midst of conducting a validation check. * * **DISABLED**: This control is exempt from validation checks. * * These status values are mutually exclusive, so a control cannot be * both valid AND invalid or invalid AND disabled. */ readonly status: string; /** * A control is `valid` when its `status` is `VALID`. * * @see {@link AbstractControl.status} * * @returns True if the control has passed all of its validation tests, * false otherwise. */ get valid(): boolean; /** * A control is `invalid` when its `status` is `INVALID`. * * @see {@link AbstractControl.status} * * @returns True if this control has failed one or more of its validation checks, * false otherwise. */ get invalid(): boolean; /** * A control is `pending` when its `status` is `PENDING`. * * @see {@link AbstractControl.status} * * @returns True if this control is in the process of conducting a validation check, * false otherwise. */ get pending(): boolean; /** * A control is `disabled` when its `status` is `DISABLED`. * * Disabled controls are exempt from validation checks and * are not included in the aggregate value of their ancestor * controls. * * @see {@link AbstractControl.status} * * @returns True if the control is disabled, false otherwise. */ get disabled(): boolean; /** * A control is `enabled` as long as its `status` is not `DISABLED`. * * @returns True if the control has any status other than 'DISABLED', * false if the status is 'DISABLED'. * * @see {@link AbstractControl.status} * */ get enabled(): boolean; /** * An object containing any errors generated by failing validation, * or null if there are no errors. */ readonly errors: ValidationErrors | null; /** * A control is `pristine` if the user has not yet changed * the value in the UI. * * @returns True if the user has not yet changed the value in the UI; compare `dirty`. * Programmatic changes to a control's value do not mark it dirty. */ readonly pristine: boolean; /** * A control is `dirty` if the user has changed the value * in the UI. * * @returns True if the user has changed the value of this control in the UI; compare `pristine`. * Programmatic changes to a control's value do not mark it dirty. */ get dirty(): boolean; /** * True if the control is marked as `touched`. * * A control is marked `touched` once the user has triggered * a `blur` event on it. */ readonly touched: boolean; /** * True if the control has not been marked as touched * * A control is `untouched` if the user has not yet triggered * a `blur` event on it. */ get untouched(): boolean; /** * 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. */ readonly valueChanges: Observable; /** * A multicasting observable that emits an event every time the validation `status` of the control * recalculates. * * @see {@link AbstractControl.status} * */ readonly statusChanges: Observable; /** * Reports the update strategy of the `AbstractControl` (meaning * the event on which the control updates itself). * Possible values: `'change'` | `'blur'` | `'submit'` * Default value: `'change'` */ get updateOn(): FormHooks; /** * Sets the synchronous validators that are active on this control. Calling * this overwrites any existing sync validators. * * When you add or remove a validator at run time, you must call * `updateValueAndValidity()` for the new validation to take effect. * */ setValidators(newValidator: ValidatorFn | ValidatorFn[] | null): void; /** * Sets the async validators that are active on this control. Calling this * overwrites any existing async validators. * * When you add or remove a validator at run time, you must call * `updateValueAndValidity()` for the new validation to take effect. * */ setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[] | null): void; /** * Empties out the sync validator list. * * When you add or remove a validator at run time, you must call * `updateValueAndValidity()` for the new validation to take effect. * */ clearValidators(): void; /** * Empties out the async validator list. * * When you add or remove a validator at run time, you must call * `updateValueAndValidity()` for the new validation to take effect. * */ clearAsyncValidators(): void; /** * Marks the control as `touched`. A control is touched by focus and * blur events that do not change the value. * * @see `markAsUntouched()` * @see `markAsDirty()` * @see `markAsPristine()` * * @param opts Configuration options that determine how the control propagates changes * and emits events after marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. */ markAsTouched(opts?: { onlySelf?: boolean; }): void; /** * Marks the control and all its descendant controls as `touched`. * @see `markAsTouched()` */ markAllAsTouched(): void; /** * Marks the control as `untouched`. * * If the control has any children, also marks all children as `untouched` * and recalculates the `touched` status of all parent controls. * * @see `markAsTouched()` * @see `markAsDirty()` * @see `markAsPristine()` * * @param opts Configuration options that determine how the control propagates changes * and emits events after the marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. */ markAsUntouched(opts?: { onlySelf?: boolean; }): void; /** * Marks the control as `dirty`. A control becomes dirty when * the control's value is changed through the UI; compare `markAsTouched`. * * @see `markAsTouched()` * @see `markAsUntouched()` * @see `markAsPristine()` * * @param opts Configuration options that determine how the control propagates changes * and emits events after marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. */ markAsDirty(opts?: { onlySelf?: boolean; }): void; /** * Marks the control as `pristine`. * * If the control has any children, marks all children as `pristine`, * and recalculates the `pristine` status of all parent * controls. * * @see `markAsTouched()` * @see `markAsUntouched()` * @see `markAsDirty()` * * @param opts Configuration options that determine how the control emits events after * marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. */ markAsPristine(opts?: { onlySelf?: boolean; }): void; /** * Marks the control as `pending`. * * A control is pending while the control performs async validation. * * @see {@link AbstractControl.status} * * @param opts Configuration options that determine how the control propagates changes and * emits events after marking is applied. * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. * * `emitEvent`: When true or not supplied (the default), the `statusChanges` * observable emits an event with the latest status the control is marked pending. * When false, no events are emitted. * */ markAsPending(opts?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Disables the control. This means the control is exempt from validation checks and * excluded from the aggregate value of any parent. Its status is `DISABLED`. * * If the control has children, all children are also disabled. * * @see {@link AbstractControl.status} * * @param opts Configuration options that determine how the control propagates * changes and emits events after the control is disabled. * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control is disabled. * When false, no events are emitted. */ disable(opts?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * 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. * * By default, if the control has children, all children are enabled. * * @see {@link AbstractControl.status} * * @param opts Configure options that control how the control propagates changes and * emits events when marked as untouched * * `onlySelf`: When true, mark only this control. When false or not supplied, * marks all direct ancestors. Default is false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control is enabled. * When false, no events are emitted. */ enable(opts?: { onlySelf?: boolean; emitEvent?: boolean; }): void; private _updateAncestors; /** * @param parent Sets the parent of the control */ setParent(parent: FormGroup | FormArray): void; /** * Sets the value of the control. Abstract method (implemented in sub-classes). */ abstract setValue(value: any, options?: Object): void; /** * Patches the value of the control. Abstract method (implemented in sub-classes). */ abstract patchValue(value: any, options?: Object): void; /** * Resets the control. Abstract method (implemented in sub-classes). */ abstract reset(value?: any, options?: Object): void; /** * Recalculates the value and validation status of the control. * * By default, it also updates the value and validity of its ancestors. * * @param opts Configuration options determine how the control propagates changes and emits events * after updates and validity checks are applied. * * `onlySelf`: When true, only update this control. When false or not supplied, * update all direct ancestors. Default is false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control is updated. * When false, no events are emitted. */ updateValueAndValidity(opts?: { onlySelf?: boolean; emitEvent?: boolean; }): void; private _setInitialStatus; private _runValidator; private _runAsyncValidator; private _cancelExistingSubscription; /** * Sets errors on a form control when running validations manually, rather than automatically. * * Calling `setErrors` also updates the validity of the parent control. * * @usageNotes * * ### Manually set the errors for a 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); * ``` */ setErrors(errors: ValidationErrors | null, opts?: { emitEvent?: boolean; }): void; /** * Retrieves a child control given the control's name or path. * * @param path A dot-delimited string or array of string/number values that define the path to the * control. * * @usageNotes * ### Retrieve a nested control * * For example, to get a `name` control nested within a `person` sub-group: * * * `this.form.get('person.name');` * * -OR- * * * `this.form.get(['person', 'name']);` */ get(path: Array | string): AbstractControl | null; /** * @description * Reports error data for the control with the given path. * * @param errorCode The code of the error to check * @param path A list of control names that designates how to move from the current control * to the control that should be queried for errors. * * @usageNotes * 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: * * 1. An array of string control names, e.g. `['address', 'street']` * 1. A period-delimited list of control names in one string, e.g. `'address.street'` * * @returns error data for that particular error. If the control or error is not present, * null is returned. */ getError(errorCode: string, path?: Array | string): any; /** * @description * Reports whether the control with the given path has the error specified. * * @param errorCode The code of the error to check * @param path A list of control names that designates how to move from the current control * to the control that should be queried for errors. * * @usageNotes * 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: * * 1. An array of string control names, e.g. `['address', 'street']` * 1. A period-delimited list of control names in one string, e.g. `'address.street'` * * If no path is given, this method checks for the error on the current control. * * @returns whether the given error is present in the control at the given path. * * If the control is not present, false is returned. */ hasError(errorCode: string, path?: Array | string): boolean; /** * Retrieves the top-level ancestor of this control. */ get root(): AbstractControl; private _calculateStatus; } /** * @description * Base class for control directives. * * This class is only used internally in the `ReactiveFormsModule` and the `FormsModule`. * * @publicApi */ export declare abstract class AbstractControlDirective { /** * @description * A reference to the underlying control. * * @returns the control that backs this directive. Most properties fall through to that instance. */ abstract get control(): AbstractControl | null; /** * @description * Reports the value of the control if it is present, otherwise null. */ get value(): any; /** * @description * Reports whether the control is valid. A control is considered valid if no * validation errors exist with the current value. * If the control is not present, null is returned. */ get valid(): boolean | null; /** * @description * Reports whether the control is invalid, meaning that an error exists in the input value. * If the control is not present, null is returned. */ get invalid(): boolean | null; /** * @description * Reports whether a control is pending, meaning that that async validation is occurring and * errors are not yet available for the input value. If the control is not present, null is * returned. */ get pending(): boolean | null; /** * @description * Reports whether the control is disabled, meaning that the control is disabled * in the UI and is exempt from validation checks and excluded from aggregate * values of ancestor controls. If the control is not present, null is returned. */ get disabled(): boolean | null; /** * @description * Reports whether the control is enabled, meaning that the control is included in ancestor * calculations of validity or value. If the control is not present, null is returned. */ get enabled(): boolean | null; /** * @description * Reports the control's validation errors. If the control is not present, null is returned. */ get errors(): ValidationErrors | null; /** * @description * Reports whether the control is pristine, meaning that the user has not yet changed * the value in the UI. If the control is not present, null is returned. */ get pristine(): boolean | null; /** * @description * Reports whether the control is dirty, meaning that the user has changed * the value in the UI. If the control is not present, null is returned. */ get dirty(): boolean | null; /** * @description * Reports whether the control is touched, meaning that the user has triggered * a `blur` event on it. If the control is not present, null is returned. */ get touched(): boolean | null; /** * @description * Reports the validation status of the control. Possible values include: * 'VALID', 'INVALID', 'DISABLED', and 'PENDING'. * If the control is not present, null is returned. */ get status(): string | null; /** * @description * Reports whether the control is untouched, meaning that the user has not yet triggered * a `blur` event on it. If the control is not present, null is returned. */ get untouched(): boolean | null; /** * @description * Returns a multicasting observable that emits a validation status whenever it is * calculated for the control. If the control is not present, null is returned. */ get statusChanges(): Observable | null; /** * @description * Returns a multicasting observable of value changes for the control that emits every time the * value of the control changes in the UI or programmatically. * If the control is not present, null is returned. */ get valueChanges(): Observable | null; /** * @description * Returns an array that represents the path from the top-level form to this control. * Each index is the string name of the control on that level. */ get path(): string[] | null; /** * @description * Resets the control with the provided value if the control is present. */ reset(value?: any): void; /** * @description * Reports whether the control with the given path has the error specified. * * @param errorCode The code of the error to check * @param path A list of control names that designates how to move from the current control * to the control that should be queried for errors. * * @usageNotes * 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: * * 1. An array of string control names, e.g. `['address', 'street']` * 1. A period-delimited list of control names in one string, e.g. `'address.street'` * * If no path is given, this method checks for the error on the current control. * * @returns whether the given error is present in the control at the given path. * * If the control is not present, false is returned. */ hasError(errorCode: string, path?: Array | string): boolean; /** * @description * Reports error data for the control with the given path. * * @param errorCode The code of the error to check * @param path A list of control names that designates how to move from the current control * to the control that should be queried for errors. * * @usageNotes * 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: * * 1. An array of string control names, e.g. `['address', 'street']` * 1. A period-delimited list of control names in one string, e.g. `'address.street'` * * @returns error data for that particular error. If the control or error is not present, * null is returned. */ getError(errorCode: string, path?: Array | string): any; } /** * Interface for options provided to an `AbstractControl`. * * @publicApi */ export declare interface AbstractControlOptions { /** * @description * The list of validators applied to a control. */ validators?: ValidatorFn | ValidatorFn[] | null; /** * @description * The list of async validators applied to control. */ asyncValidators?: AsyncValidatorFn | AsyncValidatorFn[] | null; /** * @description * The event name for control to update upon. */ updateOn?: 'change' | 'blur' | 'submit'; } /** * @description * A base class for code shared between the `NgModelGroup` and `FormGroupName` directives. * * @publicApi */ export declare class AbstractFormGroupDirective extends ControlContainer implements OnInit, OnDestroy { /** * @description * An internal callback method triggered on the instance after the inputs are set. * Registers the group with its parent group. */ ngOnInit(): void; /** * @description * An internal callback method triggered before the instance is destroyed. * Removes the group from its parent group. */ ngOnDestroy(): void; /** * @description * The `FormGroup` bound to this directive. */ get control(): FormGroup; /** * @description * The path to this group from the top-level directive. */ get path(): string[]; /** * @description * The top-level directive for this group if present, otherwise null. */ get formDirective(): Form | null; /** * @description * The synchronous validators registered with this group. */ get validator(): ValidatorFn | null; /** * @description * The async validators registered with this group. */ get asyncValidator(): AsyncValidatorFn | null; } /** * @description * An interface implemented by classes that perform asynchronous validation. * * @usageNotes * * ### Provide a custom async validator directive * * The following example implements the `AsyncValidator` interface to create an * async validator directive with a custom error key. * * ```typescript * import { of } from 'rxjs'; * * @Directive({ * selector: '[customAsyncValidator]', * providers: [{provide: NG_ASYNC_VALIDATORS, useExisting: CustomAsyncValidatorDirective, multi: * true}] * }) * class CustomAsyncValidatorDirective implements AsyncValidator { * validate(control: AbstractControl): Observable { * return of({'custom': true}); * } * } * ``` * * @publicApi */ export declare interface AsyncValidator extends Validator { /** * @description * Method that performs async validation against the provided control. * * @param control The control to validate against. * * @returns A promise or observable that resolves a map of validation errors * if validation fails, otherwise null. */ validate(control: AbstractControl): Promise | Observable; } /** * @description * A function that receives a control and returns a Promise or observable * that emits validation errors if present, otherwise null. * * @publicApi */ export declare interface AsyncValidatorFn { (control: AbstractControl): Promise | Observable; } /** * @description * A `ControlValueAccessor` for writing a value and listening to changes on a checkbox input * element. * * @usageNotes * * ### Using a checkbox with a reactive form. * * The following example shows how to use a checkbox with a reactive form. * * ```ts * const rememberLoginControl = new FormControl(); * ``` * * ``` * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ export declare class CheckboxControlValueAccessor implements ControlValueAccessor { private _renderer; private _elementRef; /** * @description * The registered callback function called when a change event occurs on the input element. */ onChange: (_: any) => void; /** * @description * The registered callback function called when a blur event occurs on the input element. */ onTouched: () => void; constructor(_renderer: Renderer2, _elementRef: ElementRef); /** * Sets the "checked" property on the input element. * * @param value The checked value */ writeValue(value: any): void; /** * @description * Registers a function called when the control value changes. * * @param fn The callback function */ registerOnChange(fn: (_: any) => {}): void; /** * @description * Registers a function called when the control is touched. * * @param fn The callback function */ registerOnTouched(fn: () => {}): void; /** * Sets the "disabled" property on the input element. * * @param isDisabled The disabled value */ setDisabledState(isDisabled: boolean): void; } /** * A Directive that adds the `required` validator to checkbox controls marked with the * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a required checkbox validator using template-driven forms * * The following example shows how to add a checkbox required validator to an input attached to an * ngModel binding. * * ``` * * ``` * * @publicApi * @ngModule FormsModule * @ngModule ReactiveFormsModule */ export declare class CheckboxRequiredValidator extends RequiredValidator { /** * @description * Method that validates whether or not the checkbox has been checked. * Returns the validation result if enabled, otherwise null. */ validate(control: AbstractControl): ValidationErrors | null; } /** * @description * Provide this token to control if form directives buffer IME input until * the "compositionend" event occurs. * @publicApi */ export declare const COMPOSITION_BUFFER_MODE: InjectionToken; /** * @description * A base class for directives that contain multiple registered instances of `NgControl`. * Only used by the forms module. * * @publicApi */ export declare abstract class ControlContainer extends AbstractControlDirective { /** * @description * The name for the control */ name: string | number | null; /** * @description * The top-level form directive for the control. */ get formDirective(): Form | null; /** * @description * The path to this group. */ get path(): string[] | null; } /** * @description * Defines an interface that acts as a bridge between the Angular forms API and a * native element in the DOM. * * Implement this interface to create a custom form control directive * that integrates with Angular forms. * * @see DefaultValueAccessor * * @publicApi */ export declare interface ControlValueAccessor { /** * @description * Writes a new value to the element. * * This method is called by the forms API to write to the view when programmatic * changes from model to view are requested. * * @usageNotes * ### Write a value to the element * * The following example writes a value to the native DOM element. * * ```ts * writeValue(value: any): void { * this._renderer.setProperty(this._elementRef.nativeElement, 'value', value); * } * ``` * * @param obj The new value for the element */ writeValue(obj: any): void; /** * @description * Registers a callback function that is called when the control's value * changes in the UI. * * This method is called by the forms API on initialization to update the form * model when values propagate from the view to the model. * * When implementing the `registerOnChange` method in your own value accessor, * save the given function so your class calls it at the appropriate time. * * @usageNotes * ### Store the change function * * The following example stores the provided function as an internal method. * * ```ts * registerOnChange(fn: (_: any) => void): void { * this._onChange = fn; * } * ``` * * When the value changes in the UI, call the registered * function to allow the forms API to update itself: * * ```ts * host: { * '(change)': '_onChange($event.target.value)' * } * ``` * * @param fn The callback function to register */ registerOnChange(fn: any): void; /** * @description * Registers a callback function that is called by the forms API on initialization * to update the form model on blur. * * When implementing `registerOnTouched` in your own value accessor, save the given * function so your class calls it when the control should be considered * blurred or "touched". * * @usageNotes * ### Store the callback function * * The following example stores the provided function as an internal method. * * ```ts * registerOnTouched(fn: any): void { * this._onTouched = fn; * } * ``` * * On blur (or equivalent), your class should call the registered function to allow * the forms API to update itself: * * ```ts * host: { * '(blur)': '_onTouched()' * } * ``` * * @param fn The callback function to register */ registerOnTouched(fn: any): void; /** * @description * Function that is called by the forms API when the control status changes to * or from 'DISABLED'. Depending on the status, it enables or disables the * appropriate DOM element. * * @usageNotes * The following is an example of writing the disabled property to a native DOM element: * * ```ts * setDisabledState(isDisabled: boolean): void { * this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled); * } * ``` * * @param isDisabled The disabled status to set on the element */ setDisabledState?(isDisabled: boolean): void; } /** * @description * The default `ControlValueAccessor` for writing a value and listening to changes on input * elements. The accessor is used by the `FormControlDirective`, `FormControlName`, and * `NgModel` directives. * * @usageNotes * * ### Using the default value accessor * * The following example shows how to use an input element that activates the default value accessor * (in this case, a text field). * * ```ts * const firstNameControl = new FormControl(); * ``` * * ``` * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ export declare class DefaultValueAccessor implements ControlValueAccessor { private _renderer; private _elementRef; private _compositionMode; /** * @description * The registered callback function called when an input event occurs on the input element. */ onChange: (_: any) => void; /** * @description * The registered callback function called when a blur event occurs on the input element. */ onTouched: () => void; /** Whether the user is creating a composition string (IME events). */ private _composing; constructor(_renderer: Renderer2, _elementRef: ElementRef, _compositionMode: boolean); /** * Sets the "value" property on the input element. * * @param value The checked value */ writeValue(value: any): void; /** * @description * Registers a function called when the control value changes. * * @param fn The callback function */ registerOnChange(fn: (_: any) => void): void; /** * @description * Registers a function called when the control is touched. * * @param fn The callback function */ registerOnTouched(fn: () => void): void; /** * Sets the "disabled" property on the input element. * * @param isDisabled The disabled value */ setDisabledState(isDisabled: boolean): void; } /** * A directive that adds the `email` validator to controls marked with the * `email` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding an email validator * * The following example shows how to add an email validator to an input attached to an ngModel * binding. * * ``` * * * * ``` * * @publicApi * @ngModule FormsModule * @ngModule ReactiveFormsModule */ export declare class EmailValidator implements Validator { private _enabled; private _onChange; /** * @description * Tracks changes to the email attribute bound to this directive. */ set email(value: boolean | string); /** * @description * Method that validates whether an email address is valid. * Returns the validation result if enabled, otherwise null. */ validate(control: AbstractControl): ValidationErrors | null; /** * @description * Registers a callback function to call when the validator inputs change. * * @param fn The callback function */ registerOnValidatorChange(fn: () => void): void; } /** * @description * An interface implemented by `FormGroupDirective` and `NgForm` directives. * * Only used by the `ReactiveFormsModule` and `FormsModule`. * * @publicApi */ export declare interface Form { /** * @description * Add a control to this form. * * @param dir The control directive to add to the form. */ addControl(dir: NgControl): void; /** * @description * Remove a control from this form. * * @param dir: The control directive to remove from the form. */ removeControl(dir: NgControl): void; /** * @description * The control directive from which to get the `FormControl`. * * @param dir: The control directive. */ getControl(dir: NgControl): FormControl; /** * @description * Add a group of controls to this form. * * @param dir: The control group directive to add. */ addFormGroup(dir: AbstractFormGroupDirective): void; /** * @description * Remove a group of controls to this form. * * @param dir: The control group directive to remove. */ removeFormGroup(dir: AbstractFormGroupDirective): void; /** * @description * The `FormGroup` associated with a particular `AbstractFormGroupDirective`. * * @param dir: The form group directive from which to get the `FormGroup`. */ getFormGroup(dir: AbstractFormGroupDirective): FormGroup; /** * @description * Update the model for a particular control with a new value. * * @param dir: The control directive to update. * @param value: The new value for the control. */ updateModel(dir: NgControl, value: any): void; } /** * Tracks the value and validity state of an array of `FormControl`, * `FormGroup` or `FormArray` instances. * * A `FormArray` aggregates the values of each child `FormControl` into an array. * It calculates its status by reducing the status values of its children. For example, if one of * the controls in a `FormArray` is invalid, the entire array becomes invalid. * * `FormArray` is one of the three fundamental building blocks used to define forms in Angular, * along with `FormControl` and `FormGroup`. * * @usageNotes * * ### Create an array of form controls * * ``` * const arr = new FormArray([ * new FormControl('Nancy', Validators.minLength(2)), * new FormControl('Drew'), * ]); * * console.log(arr.value); // ['Nancy', 'Drew'] * console.log(arr.status); // 'VALID' * ``` * * ### Create a form array with array-level validators * * You include array-level validators and async validators. These come in handy * when you want to perform validation that considers the value of more than one child * control. * * The two types of validators are passed in separately as the second and third arg * respectively, or together as part of an options object. * * ``` * const arr = new FormArray([ * new FormControl('Nancy'), * new FormControl('Drew') * ], {validators: myValidator, asyncValidators: myAsyncValidator}); * ``` * * ### Set the updateOn property for all controls in a form array * * 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 * array level, all child controls default to 'blur', unless the child * has explicitly specified a different `updateOn` value. * * ```ts * const arr = new FormArray([ * new FormControl() * ], {updateOn: 'blur'}); * ``` * * ### Adding or removing controls from a form array * * To change the controls in the array, use the `push`, `insert`, `removeAt` or `clear` methods * in `FormArray` itself. These methods ensure the controls are properly tracked in the * form's hierarchy. Do not modify the array of `AbstractControl`s used to instantiate * the `FormArray` directly, as that result in strange and unexpected behavior such * as broken change detection. * * @publicApi */ export declare class FormArray extends AbstractControl { controls: AbstractControl[]; /** * Creates a new `FormArray` instance. * * @param controls An array of child controls. Each child control is given an index * where it is registered. * * @param validatorOrOpts A synchronous validator function, or an array of * such functions, or an `AbstractControlOptions` object that contains validation functions * and a validation trigger. * * @param asyncValidator A single async validator or array of async validator functions * */ constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null); /** * Get the `AbstractControl` at the given `index` in the array. * * @param index Index in the array to retrieve the control */ at(index: number): AbstractControl; /** * Insert a new `AbstractControl` at the end of the array. * * @param control Form control to be inserted */ push(control: AbstractControl): void; /** * Insert a new `AbstractControl` at the given `index` in the array. * * @param index Index in the array to insert the control * @param control Form control to be inserted */ insert(index: number, control: AbstractControl): void; /** * Remove the control at the given `index` in the array. * * @param index Index in the array to remove the control */ removeAt(index: number): void; /** * Replace an existing control. * * @param index Index in the array to replace the control * @param control The `AbstractControl` control to replace the existing control */ setControl(index: number, control: AbstractControl): void; /** * Length of the control array. */ get length(): number; /** * Sets the value of the `FormArray`. It accepts an array that matches * the structure of the control. * * This method performs strict checks, and throws an error if you try * to set the value of a control that doesn't exist or if you exclude the * value of a control. * * @usageNotes * ### Set the values for the controls in the form array * * ``` * const arr = new FormArray([ * new FormControl(), * new FormControl() * ]); * console.log(arr.value); // [null, null] * * arr.setValue(['Nancy', 'Drew']); * console.log(arr.value); // ['Nancy', 'Drew'] * ``` * * @param value Array of values for the controls * @param options Configure options that determine how the control propagates changes and * emits events after the value changes * * * `onlySelf`: When true, each change only affects this control, and not its parent. Default * is false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control value is updated. * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ setValue(value: any[], options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Patches the value of the `FormArray`. It accepts an array that matches the * structure of the control, and does its best to match the values to the correct * controls in the group. * * It accepts both super-sets and sub-sets of the array without throwing an error. * * @usageNotes * ### Patch the values for controls in a form array * * ``` * const arr = new FormArray([ * new FormControl(), * new FormControl() * ]); * console.log(arr.value); // [null, null] * * arr.patchValue(['Nancy']); * console.log(arr.value); // ['Nancy', null] * ``` * * @param value Array of latest values for the controls * @param options Configure options that determine how the control propagates changes and * emits events after the value changes * * * `onlySelf`: When true, each change only affects this control, and not its parent. Default * is false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control value is updated. * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ patchValue(value: any[], options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Resets the `FormArray` and all descendants are marked `pristine` and `untouched`, and the * value of all descendants to null or null maps. * * You reset to a specific form state by passing in an array of states * that matches the structure of the control. The state is a standalone value * or a form state object with both a value and a disabled status. * * @usageNotes * ### Reset the values in a form array * * ```ts * const arr = new FormArray([ * new FormControl(), * new FormControl() * ]); * arr.reset(['name', 'last name']); * * console.log(this.arr.value); // ['name', 'last name'] * ``` * * ### Reset the values in a form array and the disabled status for the first control * * ``` * this.arr.reset([ * {value: 'name', disabled: true}, * 'last' * ]); * * console.log(this.arr.value); // ['name', 'last name'] * console.log(this.arr.get(0).status); // 'DISABLED' * ``` * * @param value Array of values for the controls * @param options Configure options that determine how the control propagates changes and * emits events after the value changes * * * `onlySelf`: When true, each change only affects this control, and not its parent. Default * is false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control is reset. * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ reset(value?: any, options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * The aggregate value of the array, including any disabled controls. * * Reports all values regardless of disabled status. * For enabled controls only, the `value` property is the best way to get the value of the array. */ getRawValue(): any[]; /** * Remove all controls in the `FormArray`. * * @usageNotes * ### Remove all elements from a FormArray * * ```ts * const arr = new FormArray([ * new FormControl(), * new FormControl() * ]); * console.log(arr.length); // 2 * * arr.clear(); * console.log(arr.length); // 0 * ``` * * It's a simpler and more efficient alternative to removing all elements one by one: * * ```ts * const arr = new FormArray([ * new FormControl(), * new FormControl() * ]); * * while (arr.length) { * arr.removeAt(0); * } * ``` */ clear(): void; private _registerControl; } /** * @description * * Syncs a nested `FormArray` to a DOM element. * * This directive is designed to be used with a parent `FormGroupDirective` (selector: * `[formGroup]`). * * It accepts the string name of the nested `FormArray` you want to link, and * will look for a `FormArray` registered with that name in the parent * `FormGroup` instance you passed into `FormGroupDirective`. * * @see [Reactive Forms Guide](guide/reactive-forms) * @see `AbstractControl` * * @usageNotes * * ### Example * * {@example forms/ts/nestedFormArray/nested_form_array_example.ts region='Component'} * * @ngModule ReactiveFormsModule * @publicApi */ export declare class FormArrayName extends ControlContainer implements OnInit, OnDestroy { /** * @description * Tracks the name of the `FormArray` bound to the directive. The name corresponds * to a key in the parent `FormGroup` or `FormArray`. * Accepts a name as a string or a number. * The name in the form of a string is useful for individual forms, * while the numerical form allows for form arrays to be bound * to indices when iterating over arrays in a `FormArray`. */ name: string | number | null; constructor(parent: ControlContainer, validators: any[], asyncValidators: any[]); /** * @description * A lifecycle method called when the directive's inputs are initialized. For internal use only. * * @throws If the directive does not have a valid parent. */ ngOnInit(): void; /** * @description * A lifecycle method called before the directive's instance is destroyed. For internal use only. */ ngOnDestroy(): void; /** * @description * The `FormArray` bound to this directive. */ get control(): FormArray; /** * @description * The top-level directive for this group if present, otherwise null. */ get formDirective(): FormGroupDirective | null; /** * @description * Returns an array that represents the path from the top-level form to this control. * Each index is the string name of the control on that level. */ get path(): string[]; /** * @description * Synchronous validator function composed of all the synchronous validators registered with this * directive. */ get validator(): ValidatorFn | null; /** * @description * Async validator function composed of all the async validators registered with this directive. */ get asyncValidator(): AsyncValidatorFn | null; private _checkParentType; } /** * @description * Creates an `AbstractControl` from a user-specified configuration. * * The `FormBuilder` provides syntactic sugar that shortens creating instances of a `FormControl`, * `FormGroup`, or `FormArray`. It reduces the amount of boilerplate needed to build complex * forms. * * @see [Reactive Forms Guide](/guide/reactive-forms) * * @publicApi */ export declare class FormBuilder { /** * @description * Construct a new `FormGroup` instance. * * @param controlsConfig A collection of child controls. The key for each child is the name * under which it is registered. * * @param options Configuration options object for the `FormGroup`. The object can * have two shapes: * * 1) `AbstractControlOptions` object (preferred), which consists of: * * `validators`: A synchronous validator function, or an array of validator functions * * `asyncValidators`: A single async validator or array of async validator functions * * `updateOn`: The event upon which the control should be updated (options: 'change' | 'blur' | * submit') * * 2) Legacy configuration object, which consists of: * * `validator`: A synchronous validator function, or an array of validator functions * * `asyncValidator`: A single async validator or array of async validator functions * */ group(controlsConfig: { [key: string]: any; }, options?: AbstractControlOptions | { [key: string]: any; } | null): FormGroup; /** * @description * Construct a new `FormControl` with the given state, validators and options. * * @param formState Initializes the control with an initial state value, or * with an object that contains both a value and a disabled status. * * @param validatorOrOpts A synchronous validator function, or an array of * such functions, or an `AbstractControlOptions` object that contains * validation functions and a validation trigger. * * @param asyncValidator A single async validator or array of async validator * functions. * * @usageNotes * * ### Initialize a control as disabled * * The following example returns a control with an initial value in a disabled state. * * * */ control(formState: any, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormControl; /** * Constructs a new `FormArray` from the given array of configurations, * validators and options. * * @param controlsConfig An array of child controls or control configs. Each * child control is given an index when it is registered. * * @param validatorOrOpts A synchronous validator function, or an array of * such functions, or an `AbstractControlOptions` object that contains * validation functions and a validation trigger. * * @param asyncValidator A single async validator or array of async validator * functions. */ array(controlsConfig: any[], validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormArray; } /** * Tracks the value and validation status of an individual form control. * * 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](#usage-notes). * * @see `AbstractControl` * @see [Reactive Forms Guide](guide/reactive-forms) * @see [Usage Notes](#usage-notes) * * @usageNotes * * ### Initializing Form Controls * * Instantiate a `FormControl`, with an initial value. * * ```ts * 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. * * ```ts * 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. * * ```ts * 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. * * ```ts * 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`. * * ```ts * 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`. * * ```ts * 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). * * ```ts * 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' * ``` * * @publicApi */ export declare class FormControl extends AbstractControl { /** * Creates a new `FormControl` instance. * * @param formState Initializes the control with an initial value, * or an object that defines the initial value and disabled state. * * @param validatorOrOpts A synchronous validator function, or an array of * such functions, or an `AbstractControlOptions` object that contains validation functions * and a validation trigger. * * @param asyncValidator A single async validator or array of async validator functions * */ constructor(formState?: any, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null); /** * Sets a new value for the form control. * * @param value The new value for the control. * @param options Configuration options that determine how the control propagates changes * and emits events when the value changes. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. * * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control value is updated. * When false, no events are emitted. * * `emitModelToViewChange`: When true or not supplied (the default), each change triggers an * `onChange` event to * update the view. * * `emitViewToModelChange`: When true or not supplied (the default), each change triggers an * `ngModelChange` * event to update the model. * */ setValue(value: any, options?: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; }): void; /** * Patches the value of a control. * * This function is functionally the same as {@link FormControl#setValue setValue} at this level. * It exists for symmetry with {@link FormGroup#patchValue patchValue} on `FormGroups` and * `FormArrays`, where it does behave differently. * * @see `setValue` for options */ patchValue(value: any, options?: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; }): void; /** * Resets the form control, marking it `pristine` and `untouched`, and setting * the value to null. * * @param formState Resets the control with an initial value, * or an object that defines the initial value and disabled state. * * @param options Configuration options that determine how the control propagates changes * and emits events after the value changes. * * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control is reset. * When false, no events are emitted. * */ reset(formState?: any, options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Register a listener for change events. * * @param fn The method that is called when the value changes */ registerOnChange(fn: Function): void; /** * Register a listener for disabled events. * * @param fn The method that is called when the disabled status changes. */ registerOnDisabledChange(fn: (isDisabled: boolean) => void): void; private _applyFormState; } /** * @description * Synchronizes a standalone `FormControl` instance to a form control element. * * Note that support for using the `ngModel` input property and `ngModelChange` event with reactive * form directives was deprecated in Angular v6 and is scheduled for removal in * a future version of Angular. * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms). * * @see [Reactive Forms Guide](guide/reactive-forms) * @see `FormControl` * @see `AbstractControl` * * @usageNotes * * The following example shows how to register a standalone control and set its value. * * {@example forms/ts/simpleFormControl/simple_form_control_example.ts region='Component'} * * @ngModule ReactiveFormsModule * @publicApi */ export declare class FormControlDirective extends NgControl implements OnChanges { private _ngModelWarningConfig; /** * @description * Internal reference to the view model value. */ viewModel: any; /** * @description * Tracks the `FormControl` instance bound to the directive. */ form: FormControl; /** * @description * Triggers a warning that this input should not be used with reactive forms. */ set isDisabled(isDisabled: boolean); /** @deprecated as of v6 */ model: any; /** @deprecated as of v6 */ update: EventEmitter; constructor(validators: Array, asyncValidators: Array, valueAccessors: ControlValueAccessor[], _ngModelWarningConfig: string | null); /** * @description * A lifecycle method called when the directive's inputs change. For internal use * only. * * @param changes A object of key/value pairs for the set of changed inputs. */ ngOnChanges(changes: SimpleChanges): void; /** * @description * Returns an array that represents the path from the top-level form to this control. * Each index is the string name of the control on that level. */ get path(): string[]; /** * @description * Synchronous validator function composed of all the synchronous validators * registered with this directive. */ get validator(): ValidatorFn | null; /** * @description * Async validator function composed of all the async validators registered with this * directive. */ get asyncValidator(): AsyncValidatorFn | null; /** * @description * The `FormControl` bound to this directive. */ get control(): FormControl; /** * @description * Sets the new value for the view model and emits an `ngModelChange` event. * * @param newValue The new value for the view model. */ viewToModelUpdate(newValue: any): void; private _isControlChanged; } /** * @description * Syncs a `FormControl` in an existing `FormGroup` to a form control * element by name. * * @see [Reactive Forms Guide](guide/reactive-forms) * @see `FormControl` * @see `AbstractControl` * * @usageNotes * * ### Register `FormControl` within a group * * The following example shows how to register multiple form controls within a form group * and set their value. * * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'} * * To see `formControlName` examples with different form control types, see: * * * Radio buttons: `RadioControlValueAccessor` * * Selects: `SelectControlValueAccessor` * * ### Use with ngModel is deprecated * * Support for using the `ngModel` input property and `ngModelChange` event with reactive * form directives has been deprecated in Angular v6 and is scheduled for removal in * a future version of Angular. * * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms). * * @ngModule ReactiveFormsModule * @publicApi */ export declare class FormControlName extends NgControl implements OnChanges, OnDestroy { private _ngModelWarningConfig; private _added; /** * @description * Tracks the `FormControl` instance bound to the directive. */ readonly control: FormControl; /** * @description * Tracks the name of the `FormControl` bound to the directive. The name corresponds * to a key in the parent `FormGroup` or `FormArray`. * Accepts a name as a string or a number. * The name in the form of a string is useful for individual forms, * while the numerical form allows for form controls to be bound * to indices when iterating over controls in a `FormArray`. */ name: string | number | null; /** * @description * Triggers a warning that this input should not be used with reactive forms. */ set isDisabled(isDisabled: boolean); /** @deprecated as of v6 */ model: any; /** @deprecated as of v6 */ update: EventEmitter; constructor(parent: ControlContainer, validators: Array, asyncValidators: Array, valueAccessors: ControlValueAccessor[], _ngModelWarningConfig: string | null); /** * @description * A lifecycle method called when the directive's inputs change. For internal use only. * * @param changes A object of key/value pairs for the set of changed inputs. */ ngOnChanges(changes: SimpleChanges): void; /** * @description * Lifecycle method called before the directive's instance is destroyed. For internal use only. */ ngOnDestroy(): void; /** * @description * Sets the new value for the view model and emits an `ngModelChange` event. * * @param newValue The new value for the view model. */ viewToModelUpdate(newValue: any): void; /** * @description * Returns an array that represents the path from the top-level form to this control. * Each index is the string name of the control on that level. */ get path(): string[]; /** * @description * The top-level directive for this group if present, otherwise null. */ get formDirective(): any; /** * @description * Synchronous validator function composed of all the synchronous validators * registered with this directive. */ get validator(): ValidatorFn | null; /** * @description * Async validator function composed of all the async validators registered with this * directive. */ get asyncValidator(): AsyncValidatorFn; private _checkParentType; private _setUpControl; } /** * Tracks the value and validity state of a group of `FormControl` instances. * * 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. * * @usageNotes * * ### Create a form group with 2 controls * * ``` * 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' * ``` * * ### Create a form group with a group-level validator * * 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 }); * ``` * * ### Set the updateOn property for all controls in a form group * * 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. * * ```ts * const c = new FormGroup({ * one: new FormControl() * }, { updateOn: 'blur' }); * ``` * * @publicApi */ export declare class FormGroup extends AbstractControl { controls: { [key: string]: AbstractControl; }; /** * Creates a new `FormGroup` instance. * * @param controls A collection of child controls. The key for each child is the name * under which it is registered. * * @param validatorOrOpts A synchronous validator function, or an array of * such functions, or an `AbstractControlOptions` object that contains validation functions * and a validation trigger. * * @param asyncValidator A single async validator or array of async validator functions * */ constructor(controls: { [key: string]: AbstractControl; }, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null); /** * Registers a control with the group's list of controls. * * This method does not update the value or validity of the control. * Use {@link FormGroup#addControl addControl} instead. * * @param name The control name to register in the collection * @param control Provides the control for the given name */ registerControl(name: string, control: AbstractControl): AbstractControl; /** * Add a control to this group. * * This method also updates the value and validity of the control. * * @param name The control name to add to the collection * @param control Provides the control for the given name */ addControl(name: string, control: AbstractControl): void; /** * Remove a control from this group. * * @param name The control name to remove from the collection */ removeControl(name: string): void; /** * Replace an existing control. * * @param name The control name to replace in the collection * @param control Provides the control for the given name */ setControl(name: string, control: AbstractControl): void; /** * Check whether there is an enabled control with the given name in the group. * * Reports false for disabled controls. If you'd like to check for existence in the group * only, use {@link AbstractControl#get get} instead. * * @param controlName The control name to check for existence in the collection * * @returns false for disabled controls, true otherwise. */ contains(controlName: string): boolean; /** * Sets the value of the `FormGroup`. It accepts an object that matches * the structure of the group, with control names as keys. * * @usageNotes * ### Set the complete value for the form group * * ``` * 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'} * ``` * * @throws 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. * * @param value The new value for the control that matches the structure of the group. * @param options Configuration options that determine how the control propagates changes * and emits events after the value changes. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. * * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control value is updated. * When false, no events are emitted. */ setValue(value: { [key: string]: any; }, options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Patches the value of the `FormGroup`. It accepts an object with control * names as keys, and does its best to match the values to the correct controls * in the group. * * It accepts both super-sets and sub-sets of the group without throwing an error. * * @usageNotes * ### Patch the value for a form group * * ``` * 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} * ``` * * @param value The object that matches the structure of the group. * @param options Configuration options that determine how the control propagates changes and * emits events after the value is patched. * * `onlySelf`: When true, each change only affects this control and not its parent. Default is * true. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control value is updated. * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. */ patchValue(value: { [key: string]: any; }, options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Resets the `FormGroup`, marks all descendants are marked `pristine` and `untouched`, and * the value of all descendants to null. * * 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. * * @param value Resets the control with an initial value, * or an object that defines the initial value and disabled state. * * @param options Configuration options that determine how the control propagates changes * and emits events when the group is reset. * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * false. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and * `valueChanges` * observables emit events with the latest status and value when the control is reset. * When false, no events are emitted. * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * updateValueAndValidity} method. * * @usageNotes * * ### Reset the form group values * * ```ts * 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'} * ``` * * ### Reset the form group values and disabled status * * ``` * 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' * ``` */ reset(value?: any, options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * The aggregate value of the `FormGroup`, including any disabled controls. * * Retrieves all values regardless of disabled status. * The `value` property is the best way to get the value of the group, because * it excludes disabled controls in the `FormGroup`. */ getRawValue(): any; } /** * @description * * Binds an existing `FormGroup` to a DOM element. * * This directive accepts an existing `FormGroup` instance. It will then use this * `FormGroup` instance to match any child `FormControl`, `FormGroup`, * and `FormArray` instances to child `FormControlName`, `FormGroupName`, * and `FormArrayName` directives. * * @see [Reactive Forms Guide](guide/reactive-forms) * @see `AbstractControl` * * ### Register Form Group * * The following example registers a `FormGroup` with first name and last name controls, * and listens for the *ngSubmit* event when the button is clicked. * * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'} * * @ngModule ReactiveFormsModule * @publicApi */ export declare class FormGroupDirective extends ControlContainer implements Form, OnChanges { private _validators; private _asyncValidators; /** * @description * Reports whether the form submission has been triggered. */ readonly submitted: boolean; private _oldForm; /** * @description * Tracks the list of added `FormControlName` instances */ directives: FormControlName[]; /** * @description * Tracks the `FormGroup` bound to this directive. */ form: FormGroup; /** * @description * Emits an event when the form submission has been triggered. */ ngSubmit: EventEmitter; constructor(_validators: any[], _asyncValidators: any[]); /** * @description * A lifecycle method called when the directive's inputs change. For internal use only. * * @param changes A object of key/value pairs for the set of changed inputs. */ ngOnChanges(changes: SimpleChanges): void; /** * @description * Returns this directive's instance. */ get formDirective(): Form; /** * @description * Returns the `FormGroup` bound to this directive. */ get control(): FormGroup; /** * @description * Returns an array representing the path to this group. Because this directive * always lives at the top level of a form, it always an empty array. */ get path(): string[]; /** * @description * Method that sets up the control directive in this group, re-calculates its value * and validity, and adds the instance to the internal list of directives. * * @param dir The `FormControlName` directive instance. */ addControl(dir: FormControlName): FormControl; /** * @description * Retrieves the `FormControl` instance from the provided `FormControlName` directive * * @param dir The `FormControlName` directive instance. */ getControl(dir: FormControlName): FormControl; /** * @description * Removes the `FormControlName` instance from the internal list of directives * * @param dir The `FormControlName` directive instance. */ removeControl(dir: FormControlName): void; /** * Adds a new `FormGroupName` directive instance to the form. * * @param dir The `FormGroupName` directive instance. */ addFormGroup(dir: FormGroupName): void; /** * No-op method to remove the form group. * * @param dir The `FormGroupName` directive instance. */ removeFormGroup(dir: FormGroupName): void; /** * @description * Retrieves the `FormGroup` for a provided `FormGroupName` directive instance * * @param dir The `FormGroupName` directive instance. */ getFormGroup(dir: FormGroupName): FormGroup; /** * Adds a new `FormArrayName` directive instance to the form. * * @param dir The `FormArrayName` directive instance. */ addFormArray(dir: FormArrayName): void; /** * No-op method to remove the form array. * * @param dir The `FormArrayName` directive instance. */ removeFormArray(dir: FormArrayName): void; /** * @description * Retrieves the `FormArray` for a provided `FormArrayName` directive instance. * * @param dir The `FormArrayName` directive instance. */ getFormArray(dir: FormArrayName): FormArray; /** * Sets the new value for the provided `FormControlName` directive. * * @param dir The `FormControlName` directive instance. * @param value The new value for the directive's control. */ updateModel(dir: FormControlName, value: any): void; /** * @description * Method called with the "submit" event is triggered on the form. * Triggers the `ngSubmit` emitter to emit the "submit" event as its payload. * * @param $event The "submit" event object */ onSubmit($event: Event): boolean; /** * @description * Method called when the "reset" event is triggered on the form. */ onReset(): void; /** * @description * Resets the form to an initial value and resets its submitted status. * * @param value The new value for the form. */ resetForm(value?: any): void; private _updateRegistrations; private _updateValidators; private _checkFormPresent; } /** * @description * * Syncs a nested `FormGroup` to a DOM element. * * This directive can only be used with a parent `FormGroupDirective`. * * It accepts the string name of the nested `FormGroup` to link, and * looks for a `FormGroup` registered with that name in the parent * `FormGroup` instance you passed into `FormGroupDirective`. * * Use nested form groups to validate a sub-group of a * form separately from the rest or to group the values of certain * controls into their own nested object. * * @see [Reactive Forms Guide](guide/reactive-forms) * * @usageNotes * * ### Access the group by name * * The following example uses the {@link AbstractControl#get get} method to access the * associated `FormGroup` * * ```ts * this.form.get('name'); * ``` * * ### Access individual controls in the group * * The following example uses the {@link AbstractControl#get get} method to access * individual controls within the group using dot syntax. * * ```ts * this.form.get('name.first'); * ``` * * ### Register a nested `FormGroup`. * * The following example registers a nested *name* `FormGroup` within an existing `FormGroup`, * and provides methods to retrieve the nested `FormGroup` and individual controls. * * {@example forms/ts/nestedFormGroup/nested_form_group_example.ts region='Component'} * * @ngModule ReactiveFormsModule * @publicApi */ export declare class FormGroupName extends AbstractFormGroupDirective implements OnInit, OnDestroy { /** * @description * Tracks the name of the `FormGroup` bound to the directive. The name corresponds * to a key in the parent `FormGroup` or `FormArray`. * Accepts a name as a string or a number. * The name in the form of a string is useful for individual forms, * while the numerical form allows for form groups to be bound * to indices when iterating over groups in a `FormArray`. */ name: string | number | null; constructor(parent: ControlContainer, validators: any[], asyncValidators: any[]); } declare type FormHooks = 'change' | 'blur' | 'submit'; /** * Exports the required providers and directives for template-driven forms, * making them available for import by NgModules that import this module. * * @see [Forms Overview](/guide/forms-overview) * @see [Template-driven Forms Guide](/guide/forms) * * @publicApi */ export declare class FormsModule { } /** * A directive that adds max length validation to controls marked with the * `maxlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a maximum length validator * * The following example shows how to add a maximum length validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ export declare class MaxLengthValidator implements Validator, OnChanges { private _validator; private _onChange; /** * @description * Tracks changes to the the maximum length bound to this directive. */ maxlength: string | number; /** * @description * A lifecycle method called when the directive's inputs change. For internal use * only. * * @param changes A object of key/value pairs for the set of changed inputs. */ ngOnChanges(changes: SimpleChanges): void; /** * @description * Method that validates whether the value exceeds * the maximum length requirement. */ validate(control: AbstractControl): ValidationErrors | null; /** * @description * Registers a callback function to call when the validator inputs change. * * @param fn The callback function */ registerOnValidatorChange(fn: () => void): void; private _createValidator; } /** * A directive that adds minimum length validation to controls marked with the * `minlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a minimum length validator * * The following example shows how to add a minimum length validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ export declare class MinLengthValidator implements Validator, OnChanges { private _validator; private _onChange; /** * @description * Tracks changes to the the minimum length bound to this directive. */ minlength: string | number; /** * @description * A lifecycle method called when the directive's inputs change. For internal use * only. * * @param changes A object of key/value pairs for the set of changed inputs. */ ngOnChanges(changes: SimpleChanges): void; /** * @description * Method that validates whether the value meets a minimum length * requirement. Returns the validation result if enabled, otherwise null. */ validate(control: AbstractControl): ValidationErrors | null; /** * @description * Registers a callback function to call when the validator inputs change. * * @param fn The callback function */ registerOnValidatorChange(fn: () => void): void; private _createValidator; } /** * @description * An `InjectionToken` for registering additional asynchronous validators used with * `AbstractControl`s. * * @see `NG_VALIDATORS` * * @publicApi */ export declare const NG_ASYNC_VALIDATORS: InjectionToken<(Function | Validator)[]>; /** * @description * An `InjectionToken` for registering additional synchronous validators used with * `AbstractControl`s. * * @see `NG_ASYNC_VALIDATORS` * * @usageNotes * * ### Providing a custom validator * * The following example registers a custom validator directive. Adding the validator to the * existing collection of validators requires the `multi: true` option. * * ```typescript * @Directive({ * selector: '[customValidator]', * providers: [{provide: NG_VALIDATORS, useExisting: CustomValidatorDirective, multi: true}] * }) * class CustomValidatorDirective implements Validator { * validate(control: AbstractControl): ValidationErrors | null { * return { 'custom': true }; * } * } * ``` * * @publicApi */ export declare const NG_VALIDATORS: InjectionToken<(Function | Validator)[]>; /** * Used to provide a `ControlValueAccessor` for form controls. * * See `DefaultValueAccessor` for how to implement one. * * @publicApi */ export declare const NG_VALUE_ACCESSOR: InjectionToken; /** * @description * A base class that all control `FormControl`-based directives extend. It binds a `FormControl` * object to a DOM element. * * @publicApi */ export declare abstract class NgControl extends AbstractControlDirective { /** * @description * The name for the control */ name: string | number | null; /** * @description * The value accessor for the control */ valueAccessor: ControlValueAccessor | null; /** * @description * The registered synchronous validator function for the control * * @throws An exception that this method is not implemented */ get validator(): ValidatorFn | null; /** * @description * The registered async validator function for the control * * @throws An exception that this method is not implemented */ get asyncValidator(): AsyncValidatorFn | null; /** * @description * The callback method to update the model from the view when requested * * @param newValue The new value for the view */ abstract viewToModelUpdate(newValue: any): void; } /** * @description * Directive automatically applied to Angular form controls that sets CSS classes * based on control status. * * @usageNotes * * ### CSS classes applied * * The following classes are applied as the properties become true: * * * ng-valid * * ng-invalid * * ng-pending * * ng-pristine * * ng-dirty * * ng-untouched * * ng-touched * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ export declare class NgControlStatus extends ɵangular_packages_forms_forms_g { constructor(cd: NgControl); } /** * @description * Directive automatically applied to Angular form groups that sets CSS classes * based on control status (valid/invalid/dirty/etc). * * @see `NgControlStatus` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ export declare class NgControlStatusGroup extends ɵangular_packages_forms_forms_g { constructor(cd: ControlContainer); } /** * @description * Creates a top-level `FormGroup` instance and binds it to a form * to track aggregate form value and validation status. * * As soon as you import the `FormsModule`, this directive becomes active by default on * all `
` tags. You don't need to add a special selector. * * You optionally export the directive into a local template variable using `ngForm` as the key * (ex: `#myForm="ngForm"`). This is optional, but useful. Many properties from the underlying * `FormGroup` instance are duplicated on the directive itself, so a reference to it * gives you access to the aggregate value and validity status of the form, as well as * user interaction properties like `dirty` and `touched`. * * To register child controls with the form, use `NgModel` with a `name` * attribute. You may use `NgModelGroup` to create sub-groups within the form. * * If necessary, listen to the directive's `ngSubmit` event to be notified when the user has * triggered a form submission. The `ngSubmit` event emits the original form * submission event. * * In template driven forms, all `` tags are automatically tagged as `NgForm`. * To import the `FormsModule` but skip its usage in some forms, * for example, to use native HTML5 validation, add the `ngNoForm` and the `` * tags won't create an `NgForm` directive. In reactive forms, using `ngNoForm` is * unnecessary because the `` tags are inert. In that case, you would * refrain from using the `formGroup` directive. * * @usageNotes * * ### Listening for form submission * * The following example shows how to capture the form values from the "ngSubmit" event. * * {@example forms/ts/simpleForm/simple_form_example.ts region='Component'} * * ### Setting the update options * * The following example shows you how to change the "updateOn" option from its default using * ngFormOptions. * * ```html * * *
* ``` * * ### Native DOM validation UI * * In order to prevent the native DOM form validation UI from interfering with Angular's form * validation, Angular automatically adds the `novalidate` attribute on any `
` whenever * `FormModule` or `ReactiveFormModule` are imported into the application. * If you want to explicitly enable native DOM validation UI with Angular forms, you can add the * `ngNativeValidate` attribute to the `` element: * * ```html * * ... *
* ``` * * @ngModule FormsModule * @publicApi */ export declare class NgForm extends ControlContainer implements Form, AfterViewInit { /** * @description * Returns whether the form submission has been triggered. */ readonly submitted: boolean; private _directives; /** * @description * The `FormGroup` instance created for this form. */ form: FormGroup; /** * @description * Event emitter for the "ngSubmit" event */ ngSubmit: EventEmitter; /** * @description * Tracks options for the `NgForm` instance. * * **updateOn**: Sets the default `updateOn` value for all child `NgModels` below it * unless explicitly set by a child `NgModel` using `ngModelOptions`). Defaults to 'change'. * Possible values: `'change'` | `'blur'` | `'submit'`. * */ options: { updateOn?: FormHooks; }; constructor(validators: any[], asyncValidators: any[]); /** * @description * Lifecycle method called after the view is initialized. For internal use only. */ ngAfterViewInit(): void; /** * @description * The directive instance. */ get formDirective(): Form; /** * @description * The internal `FormGroup` instance. */ get control(): FormGroup; /** * @description * Returns an array representing the path to this group. Because this directive * always lives at the top level of a form, it is always an empty array. */ get path(): string[]; /** * @description * Returns a map of the controls in this group. */ get controls(): { [key: string]: AbstractControl; }; /** * @description * Method that sets up the control directive in this group, re-calculates its value * and validity, and adds the instance to the internal list of directives. * * @param dir The `NgModel` directive instance. */ addControl(dir: NgModel): void; /** * @description * Retrieves the `FormControl` instance from the provided `NgModel` directive. * * @param dir The `NgModel` directive instance. */ getControl(dir: NgModel): FormControl; /** * @description * Removes the `NgModel` instance from the internal list of directives * * @param dir The `NgModel` directive instance. */ removeControl(dir: NgModel): void; /** * @description * Adds a new `NgModelGroup` directive instance to the form. * * @param dir The `NgModelGroup` directive instance. */ addFormGroup(dir: NgModelGroup): void; /** * @description * Removes the `NgModelGroup` directive instance from the form. * * @param dir The `NgModelGroup` directive instance. */ removeFormGroup(dir: NgModelGroup): void; /** * @description * Retrieves the `FormGroup` for a provided `NgModelGroup` directive instance * * @param dir The `NgModelGroup` directive instance. */ getFormGroup(dir: NgModelGroup): FormGroup; /** * Sets the new value for the provided `NgControl` directive. * * @param dir The `NgControl` directive instance. * @param value The new value for the directive's control. */ updateModel(dir: NgControl, value: any): void; /** * @description * Sets the value for this `FormGroup`. * * @param value The new value */ setValue(value: { [key: string]: any; }): void; /** * @description * Method called when the "submit" event is triggered on the form. * Triggers the `ngSubmit` emitter to emit the "submit" event as its payload. * * @param $event The "submit" event object */ onSubmit($event: Event): boolean; /** * @description * Method called when the "reset" event is triggered on the form. */ onReset(): void; /** * @description * Resets the form to an initial value and resets its submitted status. * * @param value The new value for the form. */ resetForm(value?: any): void; private _setUpdateStrategy; } /** * @description * Creates a `FormControl` instance from a domain model and binds it * to a form control element. * * The `FormControl` instance tracks the value, user interaction, and * validation status of the control and keeps the view synced with the model. If used * within a parent form, the directive also registers itself with the form as a child * control. * * This directive is used by itself or as part of a larger form. Use the * `ngModel` selector to activate it. * * It accepts a domain model as an optional `Input`. If you have a one-way binding * to `ngModel` with `[]` syntax, changing the value of the domain model in the component * class sets the value in the view. If you have a two-way binding with `[()]` syntax * (also known as 'banana-box syntax'), the value in the UI always syncs back to * the domain model in your class. * * To inspect the properties of the associated `FormControl` (like validity state), * export the directive into a local template variable using `ngModel` as the key (ex: * `#myVar="ngModel"`). You then access the control using the directive's `control` property, but * most properties used (like `valid` and `dirty`) fall through to the control anyway for direct * access. See a full list of properties directly available in `AbstractControlDirective`. * * @see `RadioControlValueAccessor` * @see `SelectControlValueAccessor` * * @usageNotes * * ### Using ngModel on a standalone control * * The following examples show a simple standalone control using `ngModel`: * * {@example forms/ts/simpleNgModel/simple_ng_model_example.ts region='Component'} * * When using the `ngModel` within `
` tags, you'll also need to supply a `name` attribute * so that the control can be registered with the parent form under that name. * * In the context of a parent form, it's often unnecessary to include one-way or two-way binding, * as the parent form syncs the value for you. You access its properties by exporting it into a * local template variable using `ngForm` such as (`#f="ngForm"`). Use the variable where * needed on form submission. * * If you do need to populate initial values into your form, using a one-way binding for * `ngModel` tends to be sufficient as long as you use the exported form's value rather * than the domain model's value on submit. * * ### Using ngModel within a form * * The following example shows controls using `ngModel` within a form: * * {@example forms/ts/simpleForm/simple_form_example.ts region='Component'} * * ### Using a standalone ngModel within a group * * The following example shows you how to use a standalone ngModel control * within a form. This controls the display of the form, but doesn't contain form data. * * ```html * * * Show more options? *
* * ``` * * ### Setting the ngModel name attribute through options * * The following example shows you an alternate way to set the name attribute. The name attribute is * used within a custom form component, and the name `@Input` property serves a different purpose. * * ```html *
* * *
* * ``` * * @ngModule FormsModule * @publicApi */ export declare class NgModel extends NgControl implements OnChanges, OnDestroy { readonly control: FormControl; /** @nodoc */ static ngAcceptInputType_isDisabled: boolean | string; /** * @description * Internal reference to the view model value. */ viewModel: any; /** * @description * Tracks the name bound to the directive. The parent form * uses this name as a key to retrieve this control's value. */ name: string; /** * @description * Tracks whether the control is disabled. */ isDisabled: boolean; /** * @description * Tracks the value bound to this directive. */ model: any; /** * @description * Tracks the configuration options for this `ngModel` instance. * * **name**: An alternative to setting the name attribute on the form control element. See * the [example](api/forms/NgModel#using-ngmodel-on-a-standalone-control) for using `NgModel` * as a standalone control. * * **standalone**: When set to true, the `ngModel` will not register itself with its parent form, * and acts as if it's not in the form. Defaults to false. * * **updateOn**: Defines the event upon which the form control value and validity update. * Defaults to 'change'. Possible values: `'change'` | `'blur'` | `'submit'`. * */ options: { name?: string; standalone?: boolean; updateOn?: FormHooks; }; /** * @description * Event emitter for producing the `ngModelChange` event after * the view model updates. */ update: EventEmitter; constructor(parent: ControlContainer, validators: Array, asyncValidators: Array, valueAccessors: ControlValueAccessor[]); /** * @description * A lifecycle method called when the directive's inputs change. For internal use * only. * * @param changes A object of key/value pairs for the set of changed inputs. */ ngOnChanges(changes: SimpleChanges): void; /** * @description * Lifecycle method called before the directive's instance is destroyed. For internal * use only. */ ngOnDestroy(): void; /** * @description * Returns an array that represents the path from the top-level form to this control. * Each index is the string name of the control on that level. */ get path(): string[]; /** * @description * The top-level directive for this control if present, otherwise null. */ get formDirective(): any; /** * @description * Synchronous validator function composed of all the synchronous validators * registered with this directive. */ get validator(): ValidatorFn | null; /** * @description * Async validator function composed of all the async validators registered with this * directive. */ get asyncValidator(): AsyncValidatorFn | null; /** * @description * Sets the new value for the view model and emits an `ngModelChange` event. * * @param newValue The new value emitted by `ngModelChange`. */ viewToModelUpdate(newValue: any): void; private _setUpControl; private _setUpdateStrategy; private _isStandalone; private _setUpStandalone; private _checkForErrors; private _checkParentType; private _checkName; private _updateValue; private _updateDisabled; } /** * @description * Creates and binds a `FormGroup` instance to a DOM element. * * This directive can only be used as a child of `NgForm` (within `
` tags). * * Use this directive to validate a sub-group of your form separately from the * rest of your form, or if some values in your domain model make more sense * to consume together in a nested object. * * Provide a name for the sub-group and it will become the key * for the sub-group in the form's full value. If you need direct access, export the directive into * a local template variable using `ngModelGroup` (ex: `#myGroup="ngModelGroup"`). * * @usageNotes * * ### Consuming controls in a grouping * * The following example shows you how to combine controls together in a sub-group * of the form. * * {@example forms/ts/ngModelGroup/ng_model_group_example.ts region='Component'} * * @ngModule FormsModule * @publicApi */ export declare class NgModelGroup extends AbstractFormGroupDirective implements OnInit, OnDestroy { /** * @description * Tracks the name of the `NgModelGroup` bound to the directive. The name corresponds * to a key in the parent `NgForm`. */ name: string; constructor(parent: ControlContainer, validators: any[], asyncValidators: any[]); } /** * @description * Marks `