iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(forms): update form apis based on review feedback (#25724) 

PR Close #25724
This commit is contained in:
Brandon Roberts 2018-09-17 14:36:00 -05:00 committed by Kara Erickson
parent 07c10e2844
commit a9a81f91cf
7 changed files with 75 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
packages/forms/src/directives/abstract_control_directive.ts
View File

@ -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;

16
packages/forms/src/directives/abstract_form_group_directive.ts
View File

@ -52,7 +52,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
/**
* @description
* The callback method triggered on the instance after the inputs are set.
* An internal callback method triggered on the instance after the inputs are set.
* Registers the group with its parent group.
*/
ngOnInit(): void {
@ -62,7 +62,7 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
/**
* @description
* The callback method trigger before the instance is destroyed.
* An internal callback method triggered before the instance is destroyed.
* Removes the group from its parent group.
*/
ngOnDestroy(): void {
@ -73,33 +73,31 @@ export class AbstractFormGroupDirective extends ControlContainer implements OnIn
/**
* @description
* Reports the `FormGroup` bound to this directive from its parent
* The `FormGroup` bound to this directive.
*/
get control(): FormGroup { return this.formDirective !.getFormGroup(this); }
/**
* @description
* Reports the path to this group
* The path to this group from the top-level directive.
*/
get path(): string[] { return controlPath(this.name, this._parent); }
/**
* @description
* Reports the parent form for this group
*
* @returns The parent form if present, otherwise null.
* The top-level directive for this group if present, otherwise null.
*/
get formDirective(): Form|null { return this._parent ? this._parent.formDirective : null; }
/**
* @description
* Reports the synchronous validators registered with this group
* The synchronous validators registered with this group.
*/
get validator(): ValidatorFn|null { return composeValidators(this._validators); }
/**
* @description
* Reports the async validators registered with this group
* The async validators registered with this group.
*/
get asyncValidator(): AsyncValidatorFn|null {
return composeAsyncValidators(this._asyncValidators);

4
packages/forms/src/directives/control_container.ts
View File

@ -25,13 +25,13 @@ export abstract class ControlContainer extends AbstractControlDirective {
/**
* @description
* Reports the parent form for the control
* The top-level form directive for the control.
*/
get formDirective(): Form|null { return null; }
/**
* @description
* Reports the path to this group
* The path to this group.
*/
get path(): string[]|null { return null; }
}

18
packages/forms/src/directives/control_value_accessor.ts
View File

@ -55,7 +55,7 @@ export interface ControlValueAccessor {
*
* The following example stores the provided function as an internal method.
*
* ```typescript
* ```ts
* registerOnChange(fn: (_: any) => void): void {
* this._onChange = fn;
* }
@ -64,7 +64,7 @@ export interface ControlValueAccessor {
* When the value changes in the UI, call the registered
* function to allow the forms API to update itself:
*
* ```typescript
* ```ts
* host: {
* (change): '_onChange($event.target.value)'
* }
@ -76,10 +76,8 @@ export interface ControlValueAccessor {
/**
* @description
* Registers a callback function that is called when the control receives a blur event.
*
* This is called by the forms API on initialization so it can update the form model
* on blur.
* Registers a callback function 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
@ -87,7 +85,7 @@ export interface ControlValueAccessor {
*
* ### Store the callback function
*
* The folliwing example stores the provided function as an internal method.
* The following example stores the provided function as an internal method.
*
* ```ts
* registerOnTouched(fn: any): void {
@ -95,7 +93,7 @@ export interface ControlValueAccessor {
* }
* ```
*
* On blur (or equivalent), your class calls the registered function to allow
* On blur (or equivalent), your class should call the registered function to allow
* the forms API to update itself:
*
* ```ts
@ -110,8 +108,8 @@ export interface ControlValueAccessor {
/**
* @description
* Registers a callback function that is called when the control status is disabled or
* re-enabled. Depending on the status, it enables or disables the
* 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.
*
* The following is an example of writing the disabled property to a native DOM element:

22
packages/forms/src/directives/form_interface.ts
View File

@ -17,14 +17,14 @@ import {NgControl} from './ng_control';
* @description
* An interface implemented by `FormGroupDirective` and `NgForm` directives.
*
* Only used by the `FormsModule`.
* Only used by the `ReactiveFormsModule` and `FormsModule`.
*/
export interface Form {
/**
* @description
* Add a control to this form.
*
* @param dir The control to add to the form
* @param dir The control directive to add to the form.
*/
addControl(dir: NgControl): void;
@ -32,15 +32,15 @@ export interface Form {
* @description
* Remove a control from this form.
*
* @param dir: The control to remove from the form
* @param dir: The control directive to remove from the form.
*/
removeControl(dir: NgControl): void;
/**
* @description
* Reports the `FormControl` associated with the provided `NgControl`.
* The control directive from which to get the `FormControl`.
*
* @param dir: The form control instance
* @param dir: The control directive.
*/
getControl(dir: NgControl): FormControl;
@ -48,7 +48,7 @@ export interface Form {
* @description
* Add a group of controls to this form.
*
* @param dir: The control group to remove
* @param dir: The control group directive to add.
*/
addFormGroup(dir: AbstractFormGroupDirective): void;
@ -56,15 +56,15 @@ export interface Form {
* @description
* Remove a group of controls to this form.
*
* @param dir: The control group to remove
* @param dir: The control group directive to remove.
*/
removeFormGroup(dir: AbstractFormGroupDirective): void;
/**
* @description
* Reports the form group for the provided control
* The `FormGroup` associated with a particular `AbstractFormGroupDirective`.
*
* @param dir: The form group to query
* @param dir: The form group directive from which to get the `FormGroup`.
*/
getFormGroup(dir: AbstractFormGroupDirective): FormGroup;
@ -72,8 +72,8 @@ export interface Form {
* @description
* Update the model for a particular control with a new value.
*
* @param dir: The control to update
* @param value: The new value for the control
* @param dir: The control directive to update.
* @param value: The new value for the control.
*/
updateModel(dir: NgControl, value: any): void;
}

7
packages/forms/src/directives/ng_control.ts
View File

@ -18,13 +18,14 @@ function unimplemented(): any {
/**
* @description
* A base class that all control directives extend. It binds a `FormControl` object to a
* DOM element and is only used internally by Angular forms.
* A base class that all control `FormControl`-based directives extend. It binds a `FormControl`
* object to a DOM element.
*/
export abstract class NgControl extends AbstractControlDirective {
/**
* @description
* The parent form for the control
* The parent form for the control.
*
* @internal
*/
_parent: ControlContainer|null = null;

12
packages/forms/src/directives/validators.ts
View File

@ -36,11 +36,11 @@ export type ValidationErrors = {
*
* ```typescript
* @Directive({
* selector: '[custom-validator]',
* selector: '[customValidator]',
* providers: [{provide: NG_VALIDATORS, useExisting: CustomValidatorDirective, multi: true}]
* })
* class CustomValidatorDirective implements Validator {
* validate(c: AbstractControl): {[key: string]: any} {
* validate(c: AbstractControl): ValidationErrors|null {
* return {'custom': true};
* }
* }
@ -49,7 +49,7 @@ export type ValidationErrors = {
export interface Validator {
/**
* @description
* Method that performs synchronous verification against the provided control.
* Method that performs synchronous validation against the provided control.
*
* @param c The control to validate against.
*
@ -82,12 +82,12 @@ export interface Validator {
* import { of as observableOf } from 'rxjs';
*
* @Directive({
* selector: '[custom-async-validator]',
* selector: '[customAsyncValidator]',
* providers: [{provide: NG_ASYNC_VALIDATORS, useExisting: CustomAsyncValidatorDirective, multi:
* true}]
* })
* class CustomAsyncValidatorDirective implements AsyncValidator {
* validate(c: AbstractControl): Observable<{[key: string]: any}> {
* validate(c: AbstractControl): Observable<ValidationErrors|null> {
* return observableOf({'custom': true});
* }
* }
@ -98,7 +98,7 @@ export interface Validator {
export interface AsyncValidator extends Validator {
/**
* @description
* Method that performs async verification against the provided control.
* Method that performs async validation against the provided control.
*
* @param c The control to validate against.
*