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

docs(forms): move extended text to @usageNotes (#26039) 

Headings are not allowed in the basic description block.

PR Close #26039
This commit is contained in:
Pete Bacon Darwin 2018-09-20 15:18:14 +01:00 committed by Kara Erickson
parent 32ad2438ca
commit 7d39bc68fb
16 changed files with 106 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
packages/forms/src/directives/checkbox_value_accessor.ts
View File

@ -19,10 +19,12 @@ export const CHECKBOX_VALUE_ACCESSOR: any = {
/**
* The accessor for writing a value and listening to changes on a checkbox input element.
*
* ### Example
* ```
* <input type="checkbox" name="rememberLogin" ngModel>
* ```
* @usageNotes
* ### Example
*
* ```
* <input type="checkbox" name="rememberLogin" ngModel>
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule

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

@ -15,7 +15,7 @@ import {InjectionToken} from '@angular/core';
*
* Implement this interface to create a custom form control directive
* that integrates with Angular forms.
*
*
* @see DefaultValueAccessor
*/
export interface ControlValueAccessor {
@ -26,6 +26,7 @@ export interface ControlValueAccessor {
* This method is called by the forms API to write to the view when programmatic
* changes from model to view are requested.
*
* @usageNotes
* ### Write a value to the element
*
* The following example writes a value to the native DOM element.
@ -51,6 +52,7 @@ export interface ControlValueAccessor {
* When implementing the `registerOnChange` method in your own value accessor,
* save the given function so your class calls it at the appropriate time.
*
* @usageNotes
* ### Store the change function
*
* The following example stores the provided function as an internal method.
@ -83,6 +85,7 @@ export interface ControlValueAccessor {
* function so your class calls it when the control should be considered
* blurred or "touched".
*
* @usageNotes
* ### Store the callback function
*
* The following example stores the provided function as an internal method.
@ -112,6 +115,7 @@ export interface ControlValueAccessor {
* or from 'DISABLED'. Depending on the status, it enables or disables the
* appropriate DOM element.
*
* @usageNotes
* The following is an example of writing the disabled property to a native DOM element:
*
* ```ts

10
packages/forms/src/directives/default_value_accessor.ts
View File

@ -35,10 +35,12 @@ export const COMPOSITION_BUFFER_MODE = new InjectionToken<boolean>('CompositionE
* The default accessor for writing a value and listening to changes that is used by the
* `NgModel`, `FormControlDirective`, and `FormControlName` directives.
*
* ### Example
* ```
* <input type="text" name="searchQuery" ngModel>
* ```
* @usageNotes
* ### Example
*
* ```
* <input type="text" name="searchQuery" ngModel>
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule

11
packages/forms/src/directives/number_value_accessor.ts
View File

@ -20,10 +20,13 @@ export const NUMBER_VALUE_ACCESSOR: any = {
* The accessor for writing a number value and listening to changes that is used by the
* `NgModel`, `FormControlDirective`, and `FormControlName` directives.
*
* ### Example
* ```
* <input type="number" [(ngModel)]="age">
* ```
* @usageNotes
* ### Example
*
* ```
* <input type="number" [(ngModel)]="age">
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
*/

1
packages/forms/src/directives/radio_control_value_accessor.ts
View File

@ -66,6 +66,7 @@ export class RadioControlRegistry {
* value accessor will be active on any radio control that has a form directive. You do
* **not** need to add a special selector to activate it.
*
* @usageNotes
* ### How to use radio buttons with form directives
*
* To use radio buttons in a template-driven form, you'll want to ensure that radio buttons

11
packages/forms/src/directives/range_value_accessor.ts
View File

@ -20,10 +20,13 @@ export const RANGE_VALUE_ACCESSOR: StaticProvider = {
* The accessor for writing a range value and listening to changes that is used by the
* `NgModel`, `FormControlDirective`, and `FormControlName` directives.
*
* ### Example
* ```
* <input type="range" [(ngModel)]="age" >
* ```
* @usageNotes
* ### Example
*
* ```
* <input type="range" [(ngModel)]="age" >
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
*/

2
packages/forms/src/directives/reactive_directives/form_control_directive.ts
View File

@ -38,6 +38,7 @@ export const formControlBinding: any = {
* any values written to the DOM element through user input will be reflected in the
* `FormControl` instance (view -> model).
*
* @usageNotes
* Use this directive if you'd like to create and manage a `FormControl` instance directly.
* Simply create a `FormControl`, save it to your component class, and pass it into the
* `FormControlDirective`.
@ -70,6 +71,7 @@ export const formControlBinding: any = {
* form directives has been deprecated in Angular v6 and will be removed in Angular v7.
*
* Now deprecated:
*
* ```html
* <input [formControl]="control" [(ngModel)]="value">
* ```

2
packages/forms/src/directives/reactive_directives/form_control_name.ts
View File

@ -38,6 +38,7 @@ export const controlNameBinding: any = {
* any values written to the DOM element through user input will be reflected in the
* `FormControl` instance (view -> model).
*
* @usageNotes
* This directive is designed to be used with a parent `FormGroupDirective` (selector:
* `[formGroup]`).
*
@ -78,6 +79,7 @@ export const controlNameBinding: any = {
* form directives has been deprecated in Angular v6 and will be removed in Angular v7.
*
* Now deprecated:
*
* ```html
* <form [formGroup]="form">
* <input formControlName="first" [(ngModel)]="value">

1
packages/forms/src/directives/reactive_directives/form_group_directive.ts
View File

@ -32,6 +32,7 @@ export const formDirectiveProvider: any = {
* and `FormArray` instances to child `FormControlName`, `FormGroupName`,
* and `FormArrayName` directives.
*
* @usageNotes
* **Set value**: You can set the form's initial value when instantiating the
* `FormGroup`, or you can set it programmatically later using the `FormGroup`'s
* {@link AbstractControl#setValue setValue} or {@link AbstractControl#patchValue patchValue}

2
packages/forms/src/directives/reactive_directives/form_group_name.ts
View File

@ -39,6 +39,7 @@ export const formGroupNameProvider: any = {
* form separately from the rest or when you'd like to group the values of certain
* controls into their own nested object.
*
* @usageNotes
* **Access the group**: You can access the associated `FormGroup` using the
* {@link AbstractControl#get get} method. Ex: `this.form.get('name')`.
*
@ -107,6 +108,7 @@ export const formArrayNameProvider: any = {
* you're not sure how many there will be. Form arrays allow you to create new
* form controls dynamically.
*
* @usageNotes
* **Access the array**: You can access the associated `FormArray` using the
* {@link AbstractControl#get get} method on the parent `FormGroup`.
* Ex: `this.form.get('cities')`.

3
packages/forms/src/directives/select_control_value_accessor.ts
View File

@ -38,6 +38,7 @@ function _extractId(valueString: string): string {
* value accessor will be active on any select control that has a form directive. You do
* **not** need to add a special selector to activate it.
*
* @usageNotes
* ### How to use select controls with form directives
*
* To use a select in a template-driven form, simply add an `ngModel` and a `name`
@ -66,7 +67,7 @@ function _extractId(valueString: string): string {
* `compareWith` takes a **function** which has two arguments: `option1` and `option2`.
* If `compareWith` is given, Angular selects option by the return value of the function.
*
* #### Syntax
* ### Syntax
*
* ```
* <select [compareWith]="compareFn" [(ngModel)]="selectedCountries">

6
packages/forms/src/directives/select_multiple_control_value_accessor.ts
View File

@ -43,7 +43,8 @@ abstract class HTMLCollection {
/**
* The accessor for writing a value and listening to changes on a select element.
*
* ### Caveat: Options selection
* @usageNotes
* ### Caveat: Options selection
*
* Angular uses object identity to select options. It's possible for the identities of items
* to change while the data does not. This can happen, for example, if the items are produced
@ -54,7 +55,7 @@ abstract class HTMLCollection {
* input. `compareWith` takes a **function** which has two arguments: `option1` and `option2`.
* If `compareWith` is given, Angular selects options by the return value of the function.
*
* #### Syntax
* ### Syntax
*
* ```
* <select multiple [compareWith]="compareFn" [(ngModel)]="selectedCountries">
@ -169,6 +170,7 @@ export class SelectMultipleControlValueAccessor implements ControlValueAccessor
/**
* Marks `<option>` as dynamic, so Angular can be notified when options change.
*
* @usageNotes
* ### Example
*
* ```

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

@ -40,7 +40,7 @@ export type ValidationErrors = {
* providers: [{provide: NG_VALIDATORS, useExisting: CustomValidatorDirective, multi: true}]
* })
* class CustomValidatorDirective implements Validator {
* validate(c: AbstractControl): ValidationErrors|null {
* validate(control: AbstractControl): ValidationErrors|null {
* return {'custom': true};
* }
* }
@ -56,7 +56,7 @@ export interface Validator {
* @returns A map of validation errors if validation fails,
* otherwise null.
*/
validate(c: AbstractControl): ValidationErrors|null;
validate(control: AbstractControl): ValidationErrors|null;
/**
* @description
@ -87,7 +87,7 @@ export interface Validator {
* true}]
* })
* class CustomAsyncValidatorDirective implements AsyncValidator {
* validate(c: AbstractControl): Observable<ValidationErrors|null> {
* validate(control: AbstractControl): Observable<ValidationErrors|null> {
* return observableOf({'custom': true});
* }
* }
@ -105,7 +105,8 @@ export interface AsyncValidator extends Validator {
* @returns A promise or observable that resolves a map of validation errors
* if validation fails, otherwise null.
*/
validate(c: AbstractControl): Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
validate(control: AbstractControl):
Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
}
export const REQUIRED_VALIDATOR: StaticProvider = {
@ -125,6 +126,7 @@ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = {
* A Directive that adds the `required` validator to any controls marked with the
* `required` attribute, via the `NG_VALIDATORS` binding.
*
* @usageNotes
* ### Example
*
* ```
@ -154,8 +156,8 @@ export class RequiredValidator implements Validator {
if (this._onChange) this._onChange();
}
validate(c: AbstractControl): ValidationErrors|null {
return this.required ? Validators.required(c) : null;
validate(control: AbstractControl): ValidationErrors|null {
return this.required ? Validators.required(control) : null;
}
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
@ -166,6 +168,7 @@ export class RequiredValidator implements Validator {
* A Directive that adds the `required` validator to checkbox controls marked with the
* `required` attribute, via the `NG_VALIDATORS` binding.
*
* @usageNotes
* ### Example
*
* ```
@ -183,8 +186,8 @@ export class RequiredValidator implements Validator {
host: {'[attr.required]': 'required ? "" : null'}
})
export class CheckboxRequiredValidator extends RequiredValidator {
validate(c: AbstractControl): ValidationErrors|null {
return this.required ? Validators.requiredTrue(c) : null;
validate(control: AbstractControl): ValidationErrors|null {
return this.required ? Validators.requiredTrue(control) : null;
}
}
@ -201,6 +204,7 @@ export const EMAIL_VALIDATOR: any = {
* A Directive that adds the `email` validator to controls marked with the
* `email` attribute, via the `NG_VALIDATORS` binding.
*
* @usageNotes
* ### Example
*
* ```
@ -229,23 +233,24 @@ export class EmailValidator implements Validator {
if (this._onChange) this._onChange();
}
validate(c: AbstractControl): ValidationErrors|null {
return this._enabled ? Validators.email(c) : null;
validate(control: AbstractControl): ValidationErrors|null {
return this._enabled ? Validators.email(control) : null;
}
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
}
export interface ValidatorFn { (c: AbstractControl): ValidationErrors|null; }
export interface ValidatorFn { (control: AbstractControl): ValidationErrors|null; }
export interface AsyncValidatorFn {
(c: AbstractControl): Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
(control: AbstractControl): Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
}
/**
* Provider which adds `MinLengthValidator` to `NG_VALIDATORS`.
*
* ## Example:
* @usageNotes
* ### Example:
*
* {@example common/forms/ts/validators/validators.ts region='min'}
*/
@ -284,8 +289,8 @@ export class MinLengthValidator implements Validator,
}
}
validate(c: AbstractControl): ValidationErrors|null {
return this.minlength == null ? null : this._validator(c);
validate(control: AbstractControl): ValidationErrors|null {
return this.minlength == null ? null : this._validator(control);
}
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
@ -298,7 +303,8 @@ export class MinLengthValidator implements Validator,
/**
* Provider which adds `MaxLengthValidator` to `NG_VALIDATORS`.
*
* ## Example:
* @usageNotes
* ### Example:
*
* {@example common/forms/ts/validators/validators.ts region='max'}
*/
@ -337,8 +343,8 @@ export class MaxLengthValidator implements Validator,
}
}
validate(c: AbstractControl): ValidationErrors|null {
return this.maxlength != null ? this._validator(c) : null;
validate(control: AbstractControl): ValidationErrors|null {
return this.maxlength != null ? this._validator(control) : null;
}
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
@ -362,6 +368,7 @@ export const PATTERN_VALIDATOR: any = {
* as the regex to validate Control value against. Follows pattern attribute
* semantics; i.e. regex must match entire Control value.
*
* @usageNotes
* ### Example
*
* ```
@ -393,7 +400,7 @@ export class PatternValidator implements Validator,
}
}
validate(c: AbstractControl): ValidationErrors|null { return this._validator(c); }
validate(control: AbstractControl): ValidationErrors|null { return this._validator(control); }
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }

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

@ -599,6 +599,7 @@ export abstract class AbstractControl {
*
* Calling `setErrors` also updates the validity of the parent control.
*
* @usageNotes
* ### Manually set the errors for a control
*
* ```
@ -626,6 +627,7 @@ export abstract class AbstractControl {
* @param path A dot-delimited string or array of string/number values that define the path to the
* control.
*
* @usageNotes
* ### Retrieve a nested control
*
* For example, to get a `name` control nested within a `person` sub-group:
@ -1225,6 +1227,7 @@ export class FormGroup extends AbstractControl {
* Sets the value of the `FormGroup`. It accepts an object that matches
* the structure of the group, with control names as keys.
*
* @usageNotes
* ### Set the complete value for the form group
*
* ```
@ -1237,8 +1240,8 @@ export class FormGroup extends AbstractControl {
*
* form.setValue({first: 'Nancy', last: 'Drew'});
* console.log(form.value); // {first: 'Nancy', last: 'Drew'}
*
* ```
*
* @throws When strict checks fail, such as setting the value of a control
* that doesn't exist or if you excluding the value of a control.
*
@ -1272,19 +1275,19 @@ export class FormGroup extends AbstractControl {
*
* It accepts both super-sets and sub-sets of the group without throwing an error.
*
* @usageNotes
* ### Patch the value for a form group
*
* ```
* const form = new FormGroup({
* first: new FormControl(),
* last: new FormControl()
* });
* console.log(form.value); // {first: null, last: null}
* ```
* const form = new FormGroup({
* first: new FormControl(),
* last: new FormControl()
* });
* console.log(form.value); // {first: null, last: null}
*
* form.patchValue({first: 'Nancy'});
* console.log(form.value); // {first: 'Nancy', last: null}
*
* ```
* form.patchValue({first: 'Nancy'});
* console.log(form.value); // {first: 'Nancy', last: null}
* ```
*
* @param value The object that matches the structure of the group.
* @param options Configuration options that determine how the control propagates changes and
@ -1641,6 +1644,7 @@ export class FormArray extends AbstractControl {
* to set the value of a control that doesn't exist or if you exclude the
* value of a control.
*
* @usageNotes
* ### Set the values for the controls in the form array
*
* ```
@ -1683,6 +1687,7 @@ export class FormArray extends AbstractControl {
*
* It accepts both super-sets and sub-sets of the array without throwing an error.
*
* @usageNotes
* ### Patch the values for controls in a form array
*
* ```
@ -1726,6 +1731,7 @@ export class FormArray extends AbstractControl {
* that matches the structure of the control. The state is a standalone value
* or a form state object with both a value and a disabled status.
*
* @usageNotes
* ### Reset the values in a form array
*
* ```ts

14
packages/forms/src/validators.ts
View File

@ -22,12 +22,12 @@ function isEmptyInputValue(value: any): boolean {
* An `InjectionToken` for registering additional synchronous validators used with `AbstractControl`s.
*
* @see `NG_ASYNC_VALIDATORS`
*
*
* @usageNotes
*
*
* ### Providing a custom validator
*
* The following example registers a custom validator directive. Adding the validator to the
*
* The following example registers a custom validator directive. Adding the validator to the
* existing collection of validators requires the `multi: true` option.
*
* ```typescript
@ -50,7 +50,7 @@ export const NG_VALIDATORS = new InjectionToken<Array<Validator|Function>>('NgVa
* An `InjectionToken` for registering additional asynchronous validators used with `AbstractControl`s.
*
* @see `NG_VALIDATORS`
*
*
*/
export const NG_ASYNC_VALIDATORS =
new InjectionToken<Array<Validator|Function>>('NgAsyncValidators');
@ -64,7 +64,7 @@ const EMAIL_REGEXP =
*
* A validator is a function that processes a `FormControl` or collection of
* controls and returns an error map or null. A null map means that validation has passed.
*
*
* @see [Form Validation](/guide/form-validation)
*
*/
@ -322,7 +322,7 @@ export class Validators {
* @description
* Validator that performs no operation.
*/
static nullValidator(c: AbstractControl): ValidationErrors|null { return null; }
static nullValidator(control: AbstractControl): ValidationErrors|null { return null; }
/**
* @description

22
tools/public_api_guard/forms/forms.d.ts vendored
View File

@ -104,11 +104,11 @@ export declare class AbstractFormGroupDirective extends ControlContainer impleme
/** @experimental */
export interface AsyncValidator extends Validator {
validate(c: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
validate(control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
}
export interface AsyncValidatorFn {
(c: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
(control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
}
export declare class CheckboxControlValueAccessor implements ControlValueAccessor {
@ -123,7 +123,7 @@ export declare class CheckboxControlValueAccessor implements ControlValueAccesso
/** @experimental */
export declare class CheckboxRequiredValidator extends RequiredValidator {
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
/** @experimental */
@ -156,7 +156,7 @@ export declare class DefaultValueAccessor implements ControlValueAccessor {
export declare class EmailValidator implements Validator {
email: boolean | string;
registerOnValidatorChange(fn: () => void): void;
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
export interface Form {
@ -338,14 +338,14 @@ export declare class MaxLengthValidator implements Validator, OnChanges {
maxlength: string;
ngOnChanges(changes: SimpleChanges): void;
registerOnValidatorChange(fn: () => void): void;
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
export declare class MinLengthValidator implements Validator, OnChanges {
minlength: string;
ngOnChanges(changes: SimpleChanges): void;
registerOnValidatorChange(fn: () => void): void;
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
export declare const NG_ASYNC_VALIDATORS: InjectionToken<(Function | Validator)[]>;
@ -444,7 +444,7 @@ export declare class PatternValidator implements Validator, OnChanges {
pattern: string | RegExp;
ngOnChanges(changes: SimpleChanges): void;
registerOnValidatorChange(fn: () => void): void;
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
export declare class RadioControlValueAccessor implements ControlValueAccessor, OnDestroy, OnInit {
@ -471,7 +471,7 @@ export declare class ReactiveFormsModule {
export declare class RequiredValidator implements Validator {
required: boolean | string;
registerOnValidatorChange(fn: () => void): void;
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
export declare class SelectControlValueAccessor implements ControlValueAccessor {
@ -505,11 +505,11 @@ export declare type ValidationErrors = {
export interface Validator {
registerOnValidatorChange?(fn: () => void): void;
validate(c: AbstractControl): ValidationErrors | null;
validate(control: AbstractControl): ValidationErrors | null;
}
export interface ValidatorFn {
(c: AbstractControl): ValidationErrors | null;
(control: AbstractControl): ValidationErrors | null;
}
export declare class Validators {
@ -521,7 +521,7 @@ export declare class Validators {
static maxLength(maxLength: number): ValidatorFn;
static min(min: number): ValidatorFn;
static minLength(minLength: number): ValidatorFn;
static nullValidator(c: AbstractControl): ValidationErrors | null;
static nullValidator(control: AbstractControl): ValidationErrors | null;
static pattern(pattern: string | RegExp): ValidatorFn;
static required(control: AbstractControl): ValidationErrors | null;
static requiredTrue(control: AbstractControl): ValidationErrors | null;