docs(forms): update form apis based on review feedback (#25724)
PR Close #25724
This commit is contained in:
Brandon Roberts
committed by
Kara Erickson
Kara Erickson
parent
07c10e2844
commit
a9a81f91cf
@ -14,7 +14,7 @@ import {ValidationErrors} from './validators';
|
||||
* @description
|
||||
* Base class for control directives.
|
||||
*
|
||||
* This class is only used internally in the `FormsModule`.
|
||||
* This class is only used internally in the `ReactiveFormsModule` and the `FormsModule`.
|
||||
*
|
||||
*/
|
||||
export abstract class AbstractControlDirective {
|
||||
@ -28,114 +28,94 @@ export abstract class AbstractControlDirective {
|
||||
|
||||
/**
|
||||
* @description
|
||||
* The value of the control.
|
||||
*
|
||||
* @returns The value of the control if it is present, otherwise null.
|
||||
* Reports the value of the control if it is present, otherwise null.
|
||||
*/
|
||||
get value(): any { return this.control ? this.control.value : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that the control is valid, meaning that no errors exist in the input value.
|
||||
*
|
||||
* @returns The control's valid state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.valid : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that the control is invalid, meaning that an error exists in the input value.
|
||||
*
|
||||
* @returns The control's invalid state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.invalid : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that a control is pending, meaning that that async validation is occurring and
|
||||
* errors are not yet available for the input value.
|
||||
*
|
||||
* @returns The control's pending state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.pending : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that the control is disabled, meaning that the control is exempt from ancestor
|
||||
* calculations of validity or value.
|
||||
*
|
||||
* @returns The control's disabled state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.disabled : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that the control is enabled, meaning that the control is included in ancestor
|
||||
* calculations of validity or value.
|
||||
*
|
||||
* @returns The control's enabled state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.enabled : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports the FormControl validation errors.
|
||||
*
|
||||
* @returns The control's validation errors if the control is present, otherwise null.
|
||||
* Reports the control's validation errors. If the control is not present, null is returned.
|
||||
*/
|
||||
get errors(): ValidationErrors|null { return this.control ? this.control.errors : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that the control is pristine, meaning that the control the user has not yet changed
|
||||
* the value in the UI.
|
||||
*
|
||||
* @returns The control's pristine state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.pristine : null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports that the control is dirty, meaning that the control the user has changed
|
||||
* the value in the UI.
|
||||
*
|
||||
* @returns The control's dirty state if the control is present, otherwise null.
|
||||
* 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 { return this.control ? this.control.dirty : null; }
|
||||
|
||||
/**
|
||||
* @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.
|
||||
* 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 { 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.
|
||||
* 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 { return this.control ? this.control.status : null; }
|
||||
|
||||
/**
|
||||
* @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.
|
||||
* 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 { return this.control ? this.control.untouched : null; }
|
||||
|
||||
/**
|
||||
* @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.
|
||||
* 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<any>|null {
|
||||
return this.control ? this.control.statusChanges : null;
|
||||
@ -143,10 +123,9 @@ export abstract class AbstractControlDirective {
|
||||
|
||||
/**
|
||||
* @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.
|
||||
* 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<any>|null {
|
||||
return this.control ? this.control.valueChanges : null;
|
||||
@ -154,16 +133,14 @@ export abstract class AbstractControlDirective {
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports an array that represents the path from the top-level form to this control.
|
||||
* 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 { return null; }
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Resets the control with the provided value if the control is present
|
||||
*
|
||||
* Resets the control with the provided value if the control is present.
|
||||
*/
|
||||
reset(value: any = undefined): void {
|
||||
if (this.control) this.control.reset(value);
|
||||
@ -173,8 +150,7 @@ export abstract class AbstractControlDirective {
|
||||
* @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
|
||||
* If the control is not present, false is returned.
|
||||
*/
|
||||
hasError(errorCode: string, path?: string[]): boolean {
|
||||
return this.control ? this.control.hasError(errorCode, path) : false;
|
||||
@ -182,10 +158,8 @@ export abstract class AbstractControlDirective {
|
||||
|
||||
/**
|
||||
* @description
|
||||
* Reports error data for the control with the given path. Otherwise
|
||||
* returns null or undefined.
|
||||
*
|
||||
* @returns The control's error if the control is present, otherwise null
|
||||
* Reports error data for the control with the given path.
|
||||
* If the control is not present, null is returned.
|
||||
*/
|
||||
getError(errorCode: string, path?: string[]): any {
|
||||
return this.control ? this.control.getError(errorCode, path) : null;
|
||||
|
||||
Reference in New Issue
Block a user