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

docs(forms): update API reference for validator directives (#26926) 

PR Close #26926
This commit is contained in:
Brandon Roberts 2018-11-01 13:51:37 -05:00 committed by Miško Hevery
parent 87d7b747d2
commit a433baf99a
2 changed files with 204 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -15,7 +15,7 @@ import {NG_VALIDATORS, Validators} from '../validators';
/**
* @description
* Defines the map of errors returned from failed validation checks
* Defines the map of errors returned from failed validation checks.
*
* @publicApi
*/
@ -53,7 +53,7 @@ export interface Validator {
* @description
* Method that performs synchronous validation against the provided control.
*
* @param c The control to validate against.
* @param control The control to validate against.
*
* @returns A map of validation errors if validation fails,
* otherwise null.
@ -102,7 +102,7 @@ export interface AsyncValidator extends Validator {
* @description
* Method that performs async validation against the provided control.
*
* @param c The control to validate against.
* @param control The control to validate against.
*
* @returns A promise or observable that resolves a map of validation errors
* if validation fails, otherwise null.
@ -111,12 +111,20 @@ export interface AsyncValidator extends Validator {
Promise<ValidationErrors|null>|Observable<ValidationErrors|null>;
}
/**
* @description
* Provider which adds `RequiredValidator` to the `NG_VALIDATORS` multi-provider list.
*/
export const REQUIRED_VALIDATOR: StaticProvider = {
provide: NG_VALIDATORS,
useExisting: forwardRef(() => RequiredValidator),
multi: true
};
/**
* @description
* Provider which adds `CheckboxRequiredValidator` to the `NG_VALIDATORS` multi-provider list.
*/
export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = {
provide: NG_VALIDATORS,
useExisting: forwardRef(() => CheckboxRequiredValidator),
@ -125,11 +133,15 @@ 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.
* @description
* A directive that adds the `required` validator to any controls marked with the
* `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/form-validation)
*
* @usageNotes
* ### Example
*
* ### Adding a required validator using template-driven forms
*
* ```
* <input name="fullName" ngModel required>
@ -151,6 +163,10 @@ export class RequiredValidator implements Validator {
// TODO(issue/24571): remove '!'.
private _onChange !: () => void;
/**
* @description
* Tracks changes to the required attribute bound to this directive.
*/
@Input()
get required(): boolean|string { return this._required; }
@ -159,21 +175,37 @@ export class RequiredValidator implements Validator {
if (this._onChange) this._onChange();
}
/**
* @description
* Method that validates whether the control is empty.
* Returns the validation result if enabled, otherwise null.
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.required ? Validators.required(control) : null;
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
*/
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
}
/**
* A Directive that adds the `required` validator to checkbox controls marked with the
* `required` attribute, via the `NG_VALIDATORS` binding.
* `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/form-validation)
*
* @usageNotes
* ### Example
*
* ### Adding a required checkbox validator using template-driven forms
*
* The following example shows how to add a checkbox required validator to an input attached to an ngModel binding.
*
* ```
* <input type="checkbox" name="active" ngModel required>
* ```
@ -189,13 +221,19 @@ export class RequiredValidator implements Validator {
host: {'[attr.required]': 'required ? "" : null'}
})
export class CheckboxRequiredValidator extends RequiredValidator {
/**
* @description
* Method that validates whether or not the checkbox has been checked.
* Returns the validation result if enabled, otherwise null.
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.required ? Validators.requiredTrue(control) : null;
}
}
/**
* Provider which adds `EmailValidator` to `NG_VALIDATORS`.
* @description
* Provider which adds `EmailValidator` to the `NG_VALIDATORS` multi-provider list.
*/
export const EMAIL_VALIDATOR: any = {
provide: NG_VALIDATORS,
@ -204,12 +242,17 @@ export const EMAIL_VALIDATOR: any = {
};
/**
* A Directive that adds the `email` validator to controls marked with the
* `email` attribute, via the `NG_VALIDATORS` binding.
* A directive that adds the `email` validator to controls marked with the
* `email` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/form-validation)
*
* @usageNotes
* ### Example
*
* ### Adding an email validator
*
* The following example shows how to add an email validator to an input attached to an ngModel binding.
*
* ```
* <input type="email" name="email" ngModel email>
* <input type="email" name="email" ngModel email="true">
@ -230,25 +273,48 @@ export class EmailValidator implements Validator {
// TODO(issue/24571): remove '!'.
private _onChange !: () => void;
/**
* @description
* Tracks changes to the email attribute bound to this directive.
*/
@Input()
set email(value: boolean|string) {
this._enabled = value === '' || value === true || value === 'true';
if (this._onChange) this._onChange();
}
/**
* @description
* Method that validates whether an email address is valid.
* Returns the validation result if enabled, otherwise null.
*/
validate(control: AbstractControl): ValidationErrors|null {
return this._enabled ? Validators.email(control) : null;
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
*/
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
}
/**
* @description
* A function that receives a control and synchronously returns a map of
* validation errors if present, otherwise null.
*
* @publicApi
*/
export interface ValidatorFn { (control: AbstractControl): ValidationErrors|null; }
/**
* @description
* A function that receives a control and returns a Promise or observable
* that emits validation errors if present, otherwise null.
*
* @publicApi
*/
export interface AsyncValidatorFn {
@ -256,12 +322,8 @@ export interface AsyncValidatorFn {
}
/**
* Provider which adds `MinLengthValidator` to `NG_VALIDATORS`.
*
* @usageNotes
* ### Example:
*
* {@example common/forms/ts/validators/validators.ts region='min'}
* @description
* Provider which adds `MinLengthValidator` to the `NG_VALIDATORS` multi-provider list.
*/
export const MIN_LENGTH_VALIDATOR: any = {
provide: NG_VALIDATORS,
@ -270,11 +332,24 @@ export const MIN_LENGTH_VALIDATOR: any = {
};
/**
* A directive which installs the `MinLengthValidator` for any `formControlName`,
* `formControl`, or control with `ngModel` that also has a `minlength` attribute.
* A directive that adds minimum length validation to controls marked with the
* `minlength` attribute. The directive is provided with the `NG_VALIDATORS` mult-provider list.
*
* @see [Form Validation](guide/form-validation)
*
* @usageNotes
*
* ### Adding a minimum length validator
*
* The following example shows how to add a minimum length validator to an input attached to an
* ngModel binding.
*
* ```html
* <input name="firstName" ngModel minlength="4">
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
@Directive({
@ -289,9 +364,20 @@ export class MinLengthValidator implements Validator,
// TODO(issue/24571): remove '!'.
private _onChange !: () => void;
/**
* @description
* Tracks changes to the the minimum length bound to this directive.
*/
// TODO(issue/24571): remove '!'.
@Input() minlength !: string;
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
ngOnChanges(changes: SimpleChanges): void {
if ('minlength' in changes) {
this._createValidator();
@ -299,10 +385,21 @@ export class MinLengthValidator implements Validator,
}
}
/**
* @description
* Method that validates whether the value meets a minimum length
* requirement. Returns the validation result if enabled, otherwise null.
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.minlength == null ? null : this._validator(control);
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
*/
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
private _createValidator(): void {
@ -311,12 +408,8 @@ export class MinLengthValidator implements Validator,
}
/**
* Provider which adds `MaxLengthValidator` to `NG_VALIDATORS`.
*
* @usageNotes
* ### Example:
*
* {@example common/forms/ts/validators/validators.ts region='max'}
* @description
* Provider which adds `MaxLengthValidator` to the `NG_VALIDATORS` multi-provider list.
*/
export const MAX_LENGTH_VALIDATOR: any = {
provide: NG_VALIDATORS,
@ -325,11 +418,24 @@ export const MAX_LENGTH_VALIDATOR: any = {
};
/**
* A directive which installs the `MaxLengthValidator` for any `formControlName`,
* `formControl`, or control with `ngModel` that also has a `maxlength` attribute.
* A directive that adds max length validation to controls marked with the
* `maxlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/form-validation)
*
* @usageNotes
*
* ### Adding a maximum length validator
*
* The following example shows how to add a maximum length validator to an input attached to an
* ngModel binding.
*
* ```html
* <input name="firstName" ngModel maxlength="25">
* ```
*
* @ngModule FormsModule
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
@Directive({
@ -344,9 +450,20 @@ export class MaxLengthValidator implements Validator,
// TODO(issue/24571): remove '!'.
private _onChange !: () => void;
/**
* @description
* Tracks changes to the the maximum length bound to this directive.
*/
// TODO(issue/24571): remove '!'.
@Input() maxlength !: string;
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
ngOnChanges(changes: SimpleChanges): void {
if ('maxlength' in changes) {
this._createValidator();
@ -354,10 +471,21 @@ export class MaxLengthValidator implements Validator,
}
}
/**
* @description
* Method that validates whether the value exceeds
* the maximum length requirement.
*/
validate(control: AbstractControl): ValidationErrors|null {
return this.maxlength != null ? this._validator(control) : null;
}
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
*/
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
private _createValidator(): void {
@ -365,7 +493,10 @@ export class MaxLengthValidator implements Validator,
}
}
/**
* @description
* Provider which adds `PatternValidator` to the `NG_VALIDATORS` multi-provider list.
*/
export const PATTERN_VALIDATOR: any = {
provide: NG_VALIDATORS,
useExisting: forwardRef(() => PatternValidator),
@ -374,20 +505,26 @@ export const PATTERN_VALIDATOR: any = {
/**
* A Directive that adds the `pattern` validator to any controls marked with the
* `pattern` attribute, via the `NG_VALIDATORS` binding. Uses attribute value
* as the regex to validate Control value against. Follows pattern attribute
* semantics; i.e. regex must match entire Control value.
* @description
* A directive that adds regex pattern validation to controls marked with the
* `pattern` attribute. The regex must match the entire control value.
* The directive is provided with the `NG_VALIDATORS` multi-provider list.
*
* @see [Form Validation](guide/form-validation)
*
* @usageNotes
* ### Example
*
* ```
* <input [name]="fullName" pattern="[a-zA-Z ]*" ngModel>
* ```
* ### Adding a pattern validator
*
* @ngModule FormsModule
* The following example shows how to add a pattern validator to an input attached to an
* ngModel binding.
*
* ```html
* <input name="firstName" ngModel pattern="[a-zA-Z ]*">
* ```
*
* @ngModule ReactiveFormsModule
* @ngModule FormsModule
* @publicApi
*/
@Directive({
@ -402,9 +539,20 @@ export class PatternValidator implements Validator,
// TODO(issue/24571): remove '!'.
private _onChange !: () => void;
/**
* @description
* Tracks changes to the pattern bound to this directive.
*/
// TODO(issue/24571): remove '!'.
@Input() pattern !: string | RegExp;
/**
* @description
* A lifecycle method called when the directive's inputs change. For internal use
* only.
*
* @param changes A object of key/value pairs for the set of changed inputs.
*/
ngOnChanges(changes: SimpleChanges): void {
if ('pattern' in changes) {
this._createValidator();
@ -412,8 +560,19 @@ export class PatternValidator implements Validator,
}
}
/**
* @description
* Method that validates whether the value matches the
* the pattern requirement.
*/
validate(control: AbstractControl): ValidationErrors|null { return this._validator(control); }
/**
* @description
* Registers a callback function to call when the validator inputs change.
*
* @param fn The callback function
*/
registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
private _createValidator(): void { this._validator = Validators.pattern(this.pattern); }

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

@ -97,14 +97,17 @@ export type FormHooks = 'change' | 'blur' | 'submit';
*/
export interface AbstractControlOptions {
/**
* List of validators applied to control.
* @description
* The list of validators applied to a control.
*/
validators?: ValidatorFn|ValidatorFn[]|null;
/**
* List of async validators applied to control.
* @description
* The list of async validators applied to control.
*/
asyncValidators?: AsyncValidatorFn|AsyncValidatorFn[]|null;
/**
* @description
* The event name for control to update upon.
*/
updateOn?: 'change'|'blur'|'submit';