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

docs: More edits (#24255) 

PR Close #24255
This commit is contained in:
Brandon Roberts 2018-06-11 15:48:35 -05:00 committed by Miško Hevery
parent a57825acf3
commit 5b76f04b7f
1 changed files with 113 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
packages/forms/src/model.ts
View File

@ -13,7 +13,6 @@ import {AsyncValidatorFn, ValidationErrors, ValidatorFn} from './directives/vali
import {toObservable} from './validators'; import {toObservable} from './validators';
/** /**
* @description
* Reports that a FormControl is valid, meaning that no errors exist in the input value. * Reports that a FormControl is valid, meaning that no errors exist in the input value.
* *
* @see `status` * @see `status`
@ -21,7 +20,6 @@ import {toObservable} from './validators';
export const VALID = 'VALID'; export const VALID = 'VALID';
/** /**
* @description
* Reports that a FormControl is invalid, meaning that an error exists in the input value. * Reports that a FormControl is invalid, meaning that an error exists in the input value.
* *
* @see `status` * @see `status`
@ -29,7 +27,6 @@ export const VALID = 'VALID';
export const INVALID = 'INVALID'; export const INVALID = 'INVALID';
/** /**
* @description
* Reports that a FormControl is pending, meaning that that async validation is occurring and * Reports that a FormControl is pending, meaning that that async validation is occurring and
* errors are not yet available for the input value. * errors are not yet available for the input value.
* *
@ -39,7 +36,6 @@ export const INVALID = 'INVALID';
export const PENDING = 'PENDING'; export const PENDING = 'PENDING';
/** /**
* @description
* Reports that a FormControl is disabled, meaning that the control is exempt from ancestor * Reports that a FormControl is disabled, meaning that the control is exempt from ancestor
* calculations of validity or value. * calculations of validity or value.
* *
@ -95,8 +91,6 @@ function coerceToAsyncValidator(
export type FormHooks = 'change' | 'blur' | 'submit'; export type FormHooks = 'change' | 'blur' | 'submit';
/** /**
* @description
*
* Interface for options provided to an `AbstractControl`. * Interface for options provided to an `AbstractControl`.
* *
* @experimental * @experimental
@ -125,8 +119,6 @@ function isOptionsObj(
/** /**
* @description
*
* This is the base class for `FormControl`, `FormGroup`, and `FormArray`. * 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 * It provides some of the shared behavior that all controls and groups of controls have, like
@ -156,7 +148,6 @@ export abstract class AbstractControl {
private _asyncValidationSubscription: any; private _asyncValidationSubscription: any;
/** /**
* @description
* The current value of the control. * The current value of the control.
* *
* * For a `FormControl`, the current value. * * For a `FormControl`, the current value.
@ -168,7 +159,6 @@ export abstract class AbstractControl {
public readonly value: any; public readonly value: any;
/** /**
* @description
* Initialize the AbstractControl instance. * Initialize the AbstractControl instance.
* *
* @param validator The function that determines the synchronous validity of this control. * @param validator The function that determines the synchronous validity of this control.
@ -178,13 +168,11 @@ export abstract class AbstractControl {
constructor(public validator: ValidatorFn|null, public asyncValidator: AsyncValidatorFn|null) {} constructor(public validator: ValidatorFn|null, public asyncValidator: AsyncValidatorFn|null) {}
/** /**
* @description
* The parent control. * The parent control.
*/ */
get parent(): FormGroup|FormArray { return this._parent; } get parent(): FormGroup|FormArray { return this._parent; }
/** /**
* @description
* The validation status of the control. There are four possible * The validation status of the control. There are four possible
* validation status values: * validation status values:
* *
@ -199,7 +187,6 @@ export abstract class AbstractControl {
public readonly status: string; public readonly status: string;
/** /**
* @description
* A control is `valid` when its `status` is `VALID`. * A control is `valid` when its `status` is `VALID`.
* *
* @see `status` * @see `status`
@ -210,7 +197,6 @@ export abstract class AbstractControl {
get valid(): boolean { return this.status === VALID; } get valid(): boolean { return this.status === VALID; }
/** /**
* @description
* A control is `invalid` when its `status` is `INVALID`. * A control is `invalid` when its `status` is `INVALID`.
* *
* @see `status` * @see `status`
@ -221,7 +207,6 @@ export abstract class AbstractControl {
get invalid(): boolean { return this.status === INVALID; } get invalid(): boolean { return this.status === INVALID; }
/** /**
* @description
* A control is `pending` when its `status` is `PENDING`. * A control is `pending` when its `status` is `PENDING`.
* *
* @see `status` * @see `status`
@ -232,7 +217,6 @@ export abstract class AbstractControl {
get pending(): boolean { return this.status == PENDING; } get pending(): boolean { return this.status == PENDING; }
/** /**
* @description
* A control is `disabled` when its `status` is `DISABLED`. * A control is `disabled` when its `status` is `DISABLED`.
* *
* @see `status` * @see `status`
@ -246,7 +230,6 @@ export abstract class AbstractControl {
get disabled(): boolean { return this.status === DISABLED; } get disabled(): boolean { return this.status === DISABLED; }
/** /**
* @description
* A control is `enabled` as long as its `status` is not `DISABLED`. * A control is `enabled` as long as its `status` is not `DISABLED`.
* *
* @see `status` * @see `status`
@ -258,14 +241,12 @@ export abstract class AbstractControl {
get enabled(): boolean { return this.status !== DISABLED; } get enabled(): boolean { return this.status !== DISABLED; }
/** /**
* @description
* An object containing any errors generated by failing validation, * An object containing any errors generated by failing validation,
* or null if there are no errors. * or null if there are no errors.
*/ */
public readonly errors: ValidationErrors|null; public readonly errors: ValidationErrors|null;
/** /**
* @description
* A control is `pristine` if the user has not yet changed * A control is `pristine` if the user has not yet changed
* the value in the UI. * the value in the UI.
* *
@ -275,7 +256,6 @@ export abstract class AbstractControl {
public readonly pristine: boolean = true; public readonly pristine: boolean = true;
/** /**
* @description
* A control is `dirty` if the user has changed the value * A control is `dirty` if the user has changed the value
* in the UI. * in the UI.
* *
@ -285,7 +265,6 @@ export abstract class AbstractControl {
get dirty(): boolean { return !this.pristine; } get dirty(): boolean { return !this.pristine; }
/** /**
* @description
* True if the control is marked as `touched`. * True if the control is marked as `touched`.
* *
* A control is marked `touched` once the user has triggered * A control is marked `touched` once the user has triggered
@ -294,7 +273,6 @@ export abstract class AbstractControl {
public readonly touched: boolean = false; public readonly touched: boolean = false;
/** /**
* @description
* True if the control has not been marked as touched * True if the control has not been marked as touched
* *
* A control is `untouched` if the user has not yet triggered * A control is `untouched` if the user has not yet triggered
@ -303,21 +281,18 @@ export abstract class AbstractControl {
get untouched(): boolean { return !this.touched; } get untouched(): boolean { return !this.touched; }
/** /**
* @description
* A multicasting observable that emits an event every time the value of the control changes, in * A multicasting observable that emits an event every time the value of the control changes, in
* the UI or programmatically. * the UI or programmatically.
*/ */
public readonly valueChanges: Observable<any>; public readonly valueChanges: Observable<any>;
/** /**
* @description
* A multicasting observable that emits an event every time the validation `status` of the control * A multicasting observable that emits an event every time the validation `status` of the control
* recalculates. * recalculates.
*/ */
public readonly statusChanges: Observable<any>; public readonly statusChanges: Observable<any>;
/** /**
* @description
* Reports the update strategy of the `AbstractControl` (meaning * Reports the update strategy of the `AbstractControl` (meaning
* the event on which the control updates itself). * the event on which the control updates itself).
* Possible values: `'change'` | `'blur'` | `'submit'` * Possible values: `'change'` | `'blur'` | `'submit'`
@ -328,7 +303,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Sets the synchronous validators that are active on this control. Calling * Sets the synchronous validators that are active on this control. Calling
* this overwrites any existing sync validators. * this overwrites any existing sync validators.
*/ */
@ -337,7 +311,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Sets the async validators that are active on this control. Calling this * Sets the async validators that are active on this control. Calling this
* overwrites any existing async validators. * overwrites any existing async validators.
*/ */
@ -346,26 +319,23 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Empties out the sync validator list. * Empties out the sync validator list.
*/ */
clearValidators(): void { this.validator = null; } clearValidators(): void { this.validator = null; }
/** /**
* @description
* Empties out the async validator list. * Empties out the async validator list.
*/ */
clearAsyncValidators(): void { this.asyncValidator = null; } clearAsyncValidators(): void { this.asyncValidator = null; }
/** /**
* @description
* Marks the control as `touched`. A control is touched by focus and * Marks the control as `touched`. A control is touched by focus and
* blur events that do not change the value; compare `markAsDirty`; * blur events that do not change the value; compare `markAsDirty`;
* *
* @param opts Configuration options that determine how the control events events after * @param opts Configuration options that determine how the control propagates changes
* marking is applied. * and emits events events after marking is applied.
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false.
*/ */
markAsTouched(opts: {onlySelf?: boolean} = {}): void { markAsTouched(opts: {onlySelf?: boolean} = {}): void {
(this as{touched: boolean}).touched = true; (this as{touched: boolean}).touched = true;
@ -376,16 +346,15 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Marks the control as `untouched`. * Marks the control as `untouched`.
* *
* If the control has any children, also marks all children as `untouched` * If the control has any children, also marks all children as `untouched`
* and recalculates the `touched` status of all parent controls. * and recalculates the `touched` status of all parent controls.
* *
* @param opts Configuration options that determine how the control emits events after * @param opts Configuration options that determine how the control propagates changes
* the marking is applied. * and emits events after the marking is applied.
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false.
*/ */
markAsUntouched(opts: {onlySelf?: boolean} = {}): void { markAsUntouched(opts: {onlySelf?: boolean} = {}): void {
(this as{touched: boolean}).touched = false; (this as{touched: boolean}).touched = false;
@ -400,14 +369,13 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Marks the control as `dirty`. A control becomes dirty when * Marks the control as `dirty`. A control becomes dirty when
* the control's is changed through the UI; compare `markAsTouched`. * the control's is changed through the UI; compare `markAsTouched`.
* *
* @param opts Configuration options that determine how the control emits events after * @param opts Configuration options that determine how the control propagates changes
* marking is applied. * and emits events after marking is applied.
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false.
*/ */
markAsDirty(opts: {onlySelf?: boolean} = {}): void { markAsDirty(opts: {onlySelf?: boolean} = {}): void {
(this as{pristine: boolean}).pristine = false; (this as{pristine: boolean}).pristine = false;
@ -418,7 +386,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Marks the control as `pristine`. * Marks the control as `pristine`.
* *
* If the control has any children, marks all children as `pristine`, * If the control has any children, marks all children as `pristine`,
@ -428,7 +395,7 @@ export abstract class AbstractControl {
* @param opts Configuration options that determine how the control emits events after * @param opts Configuration options that determine how the control emits events after
* marking is applied. * marking is applied.
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false..
*/ */
markAsPristine(opts: {onlySelf?: boolean} = {}): void { markAsPristine(opts: {onlySelf?: boolean} = {}): void {
(this as{pristine: boolean}).pristine = true; (this as{pristine: boolean}).pristine = true;
@ -442,16 +409,17 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Marks the control as `pending`. * Marks the control as `pending`.
* *
* A control is pending while the control performs async validation. * A control is pending while the control performs async validation.
* *
* @param opts Configuration options that determine how the control propagates and * @param opts Configuration options that determine how the control propagates changes and
* emits events after marking is applied. * emits events after marking is applied.
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false..
* * `emitEvent`: When false, A `statusChanges` event is not emitted. * * `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 { markAsPending(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
@ -467,7 +435,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Disables the control. This means the control is exempt from validation checks and * 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`. * excluded from the aggregate value of any parent. Its status is `DISABLED`.
* *
@ -476,9 +443,11 @@ export abstract class AbstractControl {
* @param opts Configuration options that determine how the control propagates * @param opts Configuration options that determine how the control propagates
* changes and emits events after the control is disabled. * changes and emits events after the control is disabled.
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false..
* * `emitEvent`: Set to false to prevent observables from emitting both statusChanges * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* and valuesChanges events. * `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 { disable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
(this as{status: string}).status = DISABLED; (this as{status: string}).status = DISABLED;
@ -497,7 +466,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Enables the control. This means the control is included in validation checks and * 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 * the aggregate value of its parent. Its status recalculates based on its value and
* its validators. * its validators.
@ -507,9 +475,11 @@ export abstract class AbstractControl {
* @param opts Configure options that control how the control propagates changes and * @param opts Configure options that control how the control propagates changes and
* emits events when marked as untouched * emits events when marked as untouched
* * `onlySelf`: When true, mark only this control. When false or not supplied, * * `onlySelf`: When true, mark only this control. When false or not supplied,
* marks all direct ancestors, in order to maintain the model. * marks all direct ancestors. Default is false..
* * `emitEvent`: Set to false to prevent observables from emitting both statusChanges * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* and valuesChanges events. * `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 { enable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
(this as{status: string}).status = VALID; (this as{status: string}).status = VALID;
@ -530,25 +500,21 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* @param parent Sets the parent of the control * @param parent Sets the parent of the control
*/ */
setParent(parent: FormGroup|FormArray): void { this._parent = parent; } setParent(parent: FormGroup|FormArray): void { this._parent = parent; }
/** /**
* @description
* Sets the value of the control. Abstract method (implemented in sub-classes). * Sets the value of the control. Abstract method (implemented in sub-classes).
*/ */
abstract setValue(value: any, options?: Object): void; abstract setValue(value: any, options?: Object): void;
/** /**
* @description
* Patches the value of the control. Abstract method (implemented in sub-classes). * Patches the value of the control. Abstract method (implemented in sub-classes).
*/ */
abstract patchValue(value: any, options?: Object): void; abstract patchValue(value: any, options?: Object): void;
/** /**
* @description
* Resets the control. Abstract method (implemented in sub-classes). * Resets the control. Abstract method (implemented in sub-classes).
*/ */
abstract reset(value?: any, options?: Object): void; abstract reset(value?: any, options?: Object): void;
@ -558,12 +524,14 @@ export abstract class AbstractControl {
* *
* By default, it also updates the value and validity of its ancestors. * By default, it also updates the value and validity of its ancestors.
* *
* @param opts Configuration options determine how the control is updated and emits events * @param opts Configuration options determine how the control propagates changes and emits events
* after validity checks are applied. * after updates and validity checks are applied.
* * `onlySelf`: When true, only update this control. When false or not supplied, * * `onlySelf`: When true, only update this control. When false or not supplied,
* update all direct ancestors, in order to maintain the model. * update all direct ancestors. Default is false..
* * `emitEvent`: Set to false to prevent observables from emitting both statusChanges * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* and valuesChanges events. * `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 { updateValueAndValidity(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
this._setInitialStatus(); this._setInitialStatus();
@ -619,7 +587,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Sets errors on a form control when running validations manually, rather than automatically. * Sets errors on a form control when running validations manually, rather than automatically.
* *
* Calling `setErrors` also updates the validity of the parent control. * Calling `setErrors` also updates the validity of the parent control.
@ -646,7 +613,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Retrieves a child control given the control's name or path. * 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 * @param path A dot-delimited string or array of string/number values that define the path to the
@ -665,7 +631,6 @@ export abstract class AbstractControl {
get(path: Array<string|number>|string): AbstractControl|null { return _find(this, path, '.'); } get(path: Array<string|number>|string): AbstractControl|null { return _find(this, path, '.'); }
/** /**
* @description
* Reports error data for a specific error occurring in this control or in another control. * Reports error data for a specific error occurring in this control or in another control.
* *
* @param errorCode The error code for which to retrieve data * @param errorCode The error code for which to retrieve data
@ -681,7 +646,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Reports whether the control with the given path has the error specified. * Reports whether the control with the given path has the error specified.
* *
* @param errorCode The error code for which to retrieve data * @param errorCode The error code for which to retrieve data
@ -692,7 +656,6 @@ export abstract class AbstractControl {
hasError(errorCode: string, path?: string[]): boolean { return !!this.getError(errorCode, path); } hasError(errorCode: string, path?: string[]): boolean { return !!this.getError(errorCode, path); }
/** /**
* @description
* Retrieves the top-level ancestor of this control. * Retrieves the top-level ancestor of this control.
*/ */
get root(): AbstractControl { get root(): AbstractControl {
@ -802,7 +765,6 @@ export abstract class AbstractControl {
} }
/** /**
* @description
* Tracks the value and validation status of an individual form control. * 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 * This is one of the three fundamental building blocks of Angular forms, along with
@ -908,7 +870,6 @@ export class FormControl extends AbstractControl {
_pendingChange: any; _pendingChange: any;
/** /**
* @description
* Creates a new `FormControl` instance. * Creates a new `FormControl` instance.
* *
* @param formState Initializes the control with an initial state value, * @param formState Initializes the control with an initial state value,
@ -936,21 +897,25 @@ export class FormControl extends AbstractControl {
} }
/** /**
* @description
* Sets a new value for the form control. * Sets a new value for the form control.
* *
* @param value The new value for the control. * @param value The new value for the control.
* @param options Configuration options that determine how the control emits events when the * @param options Configuration options that determine how the control proopagates changes
* value changes. * and emits events when the value changes.
* The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
* *
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
* false. * false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
* * `emitModelToViewChange`: When true (the default), each change triggers an `onChange` event to * `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. * update the view.
* * `emitViewToModelChange`: When true (the default), each change triggers an `ngModelChange` * * `emitViewToModelChange`: When true or not supplied (the default), each change triggers an
* `ngModelChange`
* event to update the model. * event to update the model.
* *
*/ */
@ -969,7 +934,6 @@ export class FormControl extends AbstractControl {
} }
/** /**
* @description
* Patches the value of a control. * Patches the value of a control.
* *
* This function is functionally the same as {@link FormControl#setValue setValue} at this level. * This function is functionally the same as {@link FormControl#setValue setValue} at this level.
@ -988,7 +952,6 @@ export class FormControl extends AbstractControl {
} }
/** /**
* @description
* Resets the form control, marking it `pristine` and `untouched`, and setting * Resets the form control, marking it `pristine` and `untouched`, and setting
* the value to null. * the value to null.
* *
@ -996,12 +959,15 @@ export class FormControl extends AbstractControl {
* or with an object that defines the initial value, status, and options * or with an object that defines the initial value, status, and options
* for handling updates and validation. * for handling updates and validation.
* *
* @param options Configuration options that determine how the control is updated and * @param options Configuration options that determine how the control propagates changes
* emits events after the value changes. * and emits events after the value changes.
* *
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
* false. * false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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 = null, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void { reset(formState: any = null, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
@ -1028,7 +994,6 @@ export class FormControl extends AbstractControl {
_allControlsDisabled(): boolean { return this.disabled; } _allControlsDisabled(): boolean { return this.disabled; }
/** /**
* @description
* Register a listener for change events. * Register a listener for change events.
* *
* @param fn The method that is called when the value changes * @param fn The method that is called when the value changes
@ -1045,7 +1010,6 @@ export class FormControl extends AbstractControl {
} }
/** /**
* @description
* Register a listener for disabled events. * Register a listener for disabled events.
* *
* @param fn The method that is called when the disabled status changes. * @param fn The method that is called when the disabled status changes.
@ -1084,8 +1048,6 @@ export class FormControl extends AbstractControl {
} }
/** /**
* @description
*
* Tracks the value and validity state of a group of `FormControl` instances. * Tracks the value and validity state of a group of `FormControl` instances.
* *
* A `FormGroup` aggregates the values of each child `FormControl` into one object, * A `FormGroup` aggregates the values of each child `FormControl` into one object,
@ -1157,7 +1119,6 @@ export class FormControl extends AbstractControl {
*/ */
export class FormGroup extends AbstractControl { export class FormGroup extends AbstractControl {
/** /**
* @description
* Creates a new `FormGroup` instance. * Creates a new `FormGroup` instance.
* *
* @param controls A collection of child controls. The key for each child is the name * @param controls A collection of child controls. The key for each child is the name
@ -1184,7 +1145,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Registers a control with the group's list of controls. * Registers a control with the group's list of controls.
* *
* This method does not update the value or validity of the control. * This method does not update the value or validity of the control.
@ -1202,7 +1162,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Add a control to this group. * Add a control to this group.
* *
* This method also updates the value and validity of the control. * This method also updates the value and validity of the control.
@ -1217,7 +1176,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Remove a control from this group. * Remove a control from this group.
* *
* @param name The control name to remove from the collection * @param name The control name to remove from the collection
@ -1230,7 +1188,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Replace an existing control. * Replace an existing control.
* *
* @param name The control name to replace in the collection * @param name The control name to replace in the collection
@ -1245,7 +1202,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Check whether there is an enabled control with the given name in the group. * 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 * Reports false for disabled controls. If you'd like to check for existence in the group
@ -1260,7 +1216,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Sets the value of the `FormGroup`. It accepts an object that matches * Sets the value of the `FormGroup`. It accepts an object that matches
* the structure of the group, with control names as keys. * the structure of the group, with control names as keys.
* *
@ -1282,14 +1237,17 @@ export class FormGroup extends AbstractControl {
* that doesn't exist or if you excluding the value of a control. * that doesn't exist or if you excluding the value of a control.
* *
* @param value The new value for the control that matches the structure of the group. * @param value The new value for the control that matches the structure of the group.
* @param options Configuration options that determine how the control is updated and * @param options Configuration options that determine how the control propagates changes
* emits events after the value changes. * and emits events after the value changes.
* The configuration options are passed to the {@link AbstractControl#updateValueAndValidity * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
* *
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
* false. * false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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} = {}): setValue(value: {[key: string]: any}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}):
void { void {
@ -1302,7 +1260,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Patches the value of the `FormGroup`. It accepts an object with control * 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 * names as keys, and does its best to match the values to the correct controls
* in the group. * in the group.
@ -1324,11 +1281,14 @@ export class FormGroup extends AbstractControl {
* ``` * ```
* *
* @param value The object that matches the structure of the group * @param value The object that matches the structure of the group
* @param options Configure options that determines how the control emits events after * @param options Configure options that determines how the control propagates changes and
* the value is patched * emits events after the value is patched
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
* false. * true.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
*/ */
@ -1343,7 +1303,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* Resets the `FormGroup`, marks all descendants are marked `pristine` and `untouched`, and * Resets the `FormGroup`, marks all descendants are marked `pristine` and `untouched`, and
* the value of all descendants to null. * the value of all descendants to null.
* *
@ -1360,7 +1319,10 @@ export class FormGroup extends AbstractControl {
* and emits events when the group is reset. * and emits events when the group is reset.
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
* false. * false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
* *
@ -1408,7 +1370,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
* The aggregate value of the `FormGroup`, including any disabled controls. * The aggregate value of the `FormGroup`, including any disabled controls.
* *
* Retrieves all values regardless of disabled status. * Retrieves all values regardless of disabled status.
@ -1510,8 +1471,6 @@ export class FormGroup extends AbstractControl {
} }
/** /**
* @description
*
* Tracks the value and validity state of an array of `FormControl`, * Tracks the value and validity state of an array of `FormControl`,
* `FormGroup` or `FormArray` instances. * `FormGroup` or `FormArray` instances.
* *
@ -1577,7 +1536,6 @@ export class FormGroup extends AbstractControl {
*/ */
export class FormArray extends AbstractControl { export class FormArray extends AbstractControl {
/** /**
* @description
* Creates a new `FormArray` instance. * Creates a new `FormArray` instance.
* *
* @param controls An array of child controls. Each child control is given an index * @param controls An array of child controls. Each child control is given an index
@ -1604,7 +1562,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Get the `AbstractControl` at the given `index` in the array. * Get the `AbstractControl` at the given `index` in the array.
* *
* @param index Index in the array to retrieve the control * @param index Index in the array to retrieve the control
@ -1612,7 +1569,6 @@ export class FormArray extends AbstractControl {
at(index: number): AbstractControl { return this.controls[index]; } at(index: number): AbstractControl { return this.controls[index]; }
/** /**
* @description
* Insert a new `AbstractControl` at the end of the array. * Insert a new `AbstractControl` at the end of the array.
* *
* @param control Form control to be inserted * @param control Form control to be inserted
@ -1625,7 +1581,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Insert a new `AbstractControl` at the given `index` in the array. * Insert a new `AbstractControl` at the given `index` in the array.
* *
* @param index Index in the array to insert the control * @param index Index in the array to insert the control
@ -1639,7 +1594,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Remove the control at the given `index` in the array. * Remove the control at the given `index` in the array.
* *
* @param index Index in the array to remove the control * @param index Index in the array to remove the control
@ -1651,7 +1605,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Replace an existing control. * Replace an existing control.
* *
* @param index Index in the array to replace the control * @param index Index in the array to replace the control
@ -1671,13 +1624,11 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Length of the control array. * Length of the control array.
*/ */
get length(): number { return this.controls.length; } get length(): number { return this.controls.length; }
/** /**
* @description
* Sets the value of the `FormArray`. It accepts an array that matches * Sets the value of the `FormArray`. It accepts an array that matches
* the structure of the control. * the structure of the control.
* *
@ -1699,12 +1650,15 @@ export class FormArray extends AbstractControl {
* ``` * ```
* *
* @param value Array of values for the controls * @param value Array of values for the controls
* @param options Configure options that determine how the control emits events after the * @param options Configure options that determine how the control propagates changes and
* value changes * emits events after the value changes
* *
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default
* false. * is false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
*/ */
@ -1718,7 +1672,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Patches the value of the `FormArray`. It accepts an array that matches the * 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 * structure of the control, and does its best to match the values to the correct
* controls in the group. * controls in the group.
@ -1739,12 +1692,15 @@ export class FormArray extends AbstractControl {
* ``` * ```
* *
* @param value Array of latest values for the controls * @param value Array of latest values for the controls
* @param options Configure options that determine how the control emits events after the * @param options Configure options that determine how the control propagates changes and
* value changes * emits events after the value changes
* *
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default
* false. * is false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
*/ */
@ -1758,7 +1714,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* Resets the `FormArray` and all descendants are marked `pristine` and `untouched`, and the * Resets the `FormArray` and all descendants are marked `pristine` and `untouched`, and the
* value of all descendants to null or null maps. * value of all descendants to null or null maps.
* *
@ -1791,12 +1746,15 @@ export class FormArray extends AbstractControl {
* ``` * ```
* *
* @param value Array of values for the controls * @param value Array of values for the controls
* @param options Configure options that determine how the control emits events after the * @param options Configure options that determine how the control propagates changes and
* value changes * emits events after the value changes
* *
* * `onlySelf`: When true, each change only affects this control, and not its parent. Default is * * `onlySelf`: When true, each change only affects this control, and not its parent. Default
* false. * is false.
* * `emitEvent`: When true (the default), each change triggers a valueChanges event. * * `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 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
* updateValueAndValidity} method. * updateValueAndValidity} method.
*/ */
@ -1810,7 +1768,6 @@ export class FormArray extends AbstractControl {
} }
/** /**
* @description
* The aggregate value of the array, including any disabled controls. * The aggregate value of the array, including any disabled controls.
* *
* Reports all values regardless of disabled status. * Reports all values regardless of disabled status.