docs(forms): update API reference for forms interfaces and abstract classes (#25724)
PR Close #25724
This commit is contained in:
Brandon Roberts
committed by
Kara Erickson
Kara Erickson
parent
df5999a739
commit
07c10e2844
@ -11,153 +11,181 @@ import {AbstractControl} from '../model';
|
||||
import {ValidationErrors} from './validators';
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Base class for control directives.
|
||||
*
|
||||
* Only used internally in the forms module.
|
||||
*
|
||||
* This class is only used internally in the `FormsModule`.
|
||||
*
|
||||
*/
|
||||
export abstract class AbstractControlDirective {
|
||||
/**
|
||||
* The `FormControl`, `FormGroup`, or `FormArray`
|
||||
* that backs this directive. Most properties fall through to that
|
||||
* instance.
|
||||
* @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;
|
||||
|
||||
/** The value of the control. */
|
||||
/**
|
||||
* @description
|
||||
* The value of the control.
|
||||
*
|
||||
* @returns The value of the control if it is present, otherwise null.
|
||||
*/
|
||||
get value(): any { return this.control ? this.control.value : null; }
|
||||
|
||||
/**
|
||||
* A control is `valid` when its `status === VALID`.
|
||||
* @description
|
||||
* Reports that the control is valid, meaning that no errors exist in the input value.
|
||||
*
|
||||
* In order to have this status, the control must have passed all its
|
||||
* validation checks.
|
||||
* @returns The control's valid state if the control is present, otherwise null.
|
||||
*/
|
||||
get valid(): boolean|null { return this.control ? this.control.valid : null; }
|
||||
|
||||
/**
|
||||
* A control is `invalid` when its `status === INVALID`.
|
||||
* @description
|
||||
* Reports that the control is invalid, meaning that an error exists in the input value.
|
||||
*
|
||||
* In order to have this status, the control must have failed
|
||||
* at least one of its validation checks.
|
||||
* @returns The control's invalid state if the control is present, otherwise null.
|
||||
*/
|
||||
get invalid(): boolean|null { return this.control ? this.control.invalid : null; }
|
||||
|
||||
/**
|
||||
* A control is `pending` when its `status === PENDING`.
|
||||
* @description
|
||||
* Reports that a control is pending, meaning that that async validation is occurring and
|
||||
* errors are not yet available for the input value.
|
||||
*
|
||||
* In order to have this status, the control must be in the
|
||||
* middle of conducting a validation check.
|
||||
* @returns The control's pending state if the control is present, otherwise null.
|
||||
*/
|
||||
get pending(): boolean|null { return this.control ? this.control.pending : null; }
|
||||
|
||||
/**
|
||||
* A control is `disabled` when its `status === DISABLED`.
|
||||
* @description
|
||||
* Reports that the control is disabled, meaning that the control is exempt from ancestor
|
||||
* calculations of validity or value.
|
||||
*
|
||||
* Disabled controls are exempt from validation checks and
|
||||
* are not included in the aggregate value of their ancestor
|
||||
* controls.
|
||||
* @returns The control's disabled state if the control is present, otherwise null.
|
||||
*/
|
||||
get disabled(): boolean|null { return this.control ? this.control.disabled : null; }
|
||||
|
||||
/**
|
||||
* A control is `enabled` as long as its `status !== DISABLED`.
|
||||
* @description
|
||||
* Reports that the control is enabled, meaning that the control is included in ancestor
|
||||
* calculations of validity or value.
|
||||
*
|
||||
* In other words, it has a status of `VALID`, `INVALID`, or
|
||||
* `PENDING`.
|
||||
* @returns The control's enabled state if the control is present, otherwise null.
|
||||
*/
|
||||
get enabled(): boolean|null { return this.control ? this.control.enabled : null; }
|
||||
|
||||
/**
|
||||
* Returns any errors generated by failing validation. If there
|
||||
* are no errors, it will return null.
|
||||
* @description
|
||||
* Reports the FormControl validation errors.
|
||||
*
|
||||
* @returns The control's validation errors if the control is present, otherwise null.
|
||||
*/
|
||||
get errors(): ValidationErrors|null { return this.control ? this.control.errors : null; }
|
||||
|
||||
/**
|
||||
* A control is `pristine` if the user has not yet changed
|
||||
* @description
|
||||
* Reports that the control is pristine, meaning that the control the user has not yet changed
|
||||
* the value in the UI.
|
||||
*
|
||||
* Note that programmatic changes to a control's value will
|
||||
* *not* mark it dirty.
|
||||
* @returns The control's pristine state if the control is present, otherwise null.
|
||||
*/
|
||||
get pristine(): boolean|null { return this.control ? this.control.pristine : null; }
|
||||
|
||||
/**
|
||||
* A control is `dirty` if the user has changed the value
|
||||
* in the UI.
|
||||
* @description
|
||||
* Reports that the control is dirty, meaning that the control the user has changed
|
||||
* the value in the UI.
|
||||
*
|
||||
* Note that programmatic changes to a control's value will
|
||||
* *not* mark it dirty.
|
||||
* @returns The control's dirty state if the control is present, otherwise null.
|
||||
*/
|
||||
get dirty(): boolean|null { return this.control ? this.control.dirty : null; }
|
||||
|
||||
/**
|
||||
* A control is marked `touched` once the user has triggered
|
||||
* @description
|
||||
* Reports that the control is touched, meaning that the the user has triggered
|
||||
* a `blur` event on it.
|
||||
*
|
||||
* @returns The control's touched state if the control is present, otherwise null.
|
||||
*/
|
||||
get touched(): boolean|null { return this.control ? this.control.touched : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that a FormControl is touched, meaning that the the user has triggered
|
||||
* a `blur` event on it.
|
||||
*
|
||||
* @returns The control's touched state if the control is present, otherwise null.
|
||||
*/
|
||||
get status(): string|null { return this.control ? this.control.status : null; }
|
||||
|
||||
/**
|
||||
* A control is `untouched` if the user has not yet triggered
|
||||
* @description
|
||||
* Reports that a FormControl is untouched, meaning that the the user has not yet triggered
|
||||
* a `blur` event on it.
|
||||
*
|
||||
* @returns The control's untouched state if the control is present, otherwise null.
|
||||
*/
|
||||
get untouched(): boolean|null { return this.control ? this.control.untouched : null; }
|
||||
|
||||
/**
|
||||
* Emits an event every time the validation status of the control
|
||||
* is re-calculated.
|
||||
* @description
|
||||
* Reports the observable of status changes for the control.
|
||||
*
|
||||
* @returns An observable that emits every time the validation status of the control
|
||||
* is re-calculated if the control is present, otherwise null.
|
||||
*/
|
||||
get statusChanges(): Observable<any>|null {
|
||||
return this.control ? this.control.statusChanges : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Emits an event every time the value of the control changes, in
|
||||
* the UI or programmatically.
|
||||
* @description
|
||||
* Reports the observable of value changes for the control.
|
||||
*
|
||||
* @returns An observable that emits every time the value of the control
|
||||
* changes in the UI or programmatically if the control is present, otherwise null.
|
||||
*/
|
||||
get valueChanges(): Observable<any>|null {
|
||||
return this.control ? this.control.valueChanges : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* @description
|
||||
* Reports 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 { return null; }
|
||||
|
||||
/**
|
||||
* Resets the form control. This means by default:
|
||||
* @description
|
||||
* Resets the control with the provided value if the control is present
|
||||
*
|
||||
* * it is marked as `pristine`
|
||||
* * it is marked as `untouched`
|
||||
* * value is set to null
|
||||
*
|
||||
* For more information, see `AbstractControl`.
|
||||
*/
|
||||
reset(value: any = undefined): void {
|
||||
if (this.control) this.control.reset(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true if the control with the given path has the error specified. Otherwise
|
||||
* returns false.
|
||||
*
|
||||
* @description
|
||||
* Reports whether the control with the given path has the error specified.
|
||||
* If no path is given, it checks for the error on the present control.
|
||||
*
|
||||
* @returns True if the control is present and has the error specified, otherwise false
|
||||
*/
|
||||
hasError(errorCode: string, path?: string[]): boolean {
|
||||
return this.control ? this.control.hasError(errorCode, path) : false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns error data if the control with the given path has the error specified. Otherwise
|
||||
* @description
|
||||
* Reports error data for the control with the given path. Otherwise
|
||||
* returns null or undefined.
|
||||
*
|
||||
* If no path is given, it checks for the error on the present control.
|
||||
* @returns The control's error if the control is present, otherwise null
|
||||
*/
|
||||
getError(errorCode: string, path?: string[]): any {
|
||||
return this.control ? this.control.getError(errorCode, path) : null;
|
||||
|
||||
Reference in New Issue
Block a user