import { AbstractControl } from './AbstractControl'; import _ from 'lodash'; import { ControlOptions, ControlProperties, FormControlState } from '../interfaces/Form'; /** * Tracks the value and validation status of an individual form control. * * This is one of the three fundamental building blocks of Angular form, along with * `FormGroup.ts` and `FormArray`. It extends the `AzoraAbstractControl` class that * implements most of the base functionality for accessing the value, validation status, * user interactions and events. * * @see `AzoraAbstractControl` * @see [Reactive Forms Guide](guide/reactive-form) * @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('', types.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('', { * types: types.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 { readonly props: ControlProperties; /** * Creates a new `FormControl` instance. * * @param state Initializes the control with an initial value, or an object that defines the initial value and disabled state. * * @param options An `ControlOptions` object * */ constructor(state?: FormControlState, options?: ControlOptions); /** * Sets a new value for the form control. * * @param value The new value for the control. * @param options options options that determine how the control proopagates changes * and emits events when the value changes. * The options options are passed to the {@link AzoraAbstractControl#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; }): 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 options 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(value?: any, options?: { onlySelf?: boolean; emitEvent?: 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 options 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. * */ clear(options?: { onlySelf?: boolean; emitEvent?: boolean; }): void; /** * Sets control state on a form control . * * Calling `setOptions` also updates the validity of the parent control. * * @usageNotes * ### Manually set the options 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); * ``` */ setControlState(newState: FormControlState | null, opts?: { emitEvent?: boolean; }): void; updateControlState(newState: FormControlState | null, opts?: { emitEvent?: boolean; }): void; /** @internal */ _getControlSchema: () => object; /** @internal */ _updateValue(): void; /** @internal */ _runValidator: (() => void) & _.Cancelable; private _applyControlState; /** * @internal */ _getControlProperties(): void; /** * @internal */ _allControlsDisabled(): boolean; /** @internal */ _anyControlsHaveStatus(status: string): boolean; }