|
| 1 | +--- |
| 2 | +title: Intro |
| 3 | +order: 10 |
| 4 | +--- |
| 5 | + |
| 6 | +An Angular 7+ form validator library, may be the best angular validator library in the world. |
| 7 | + |
| 8 | +> handle validation messages easy and automatic, don't need to manually write error tips templates, just configure validation rules, and support extensive custom feedback strategy. |
| 9 | +
|
| 10 | +## Installation |
| 11 | + |
| 12 | +``` |
| 13 | +npm install @why520crazy/ngx-validator --save |
| 14 | +# or |
| 15 | +yarn add @why520crazy/ngx-validator |
| 16 | +``` |
| 17 | + |
| 18 | +## Getting Started |
| 19 | + |
| 20 | + |
| 21 | +### import NgxValidatorModule |
| 22 | +Loading the module in the any module (AppModule or Feature module). |
| 23 | + |
| 24 | +```ts |
| 25 | +import { NgxValidatorModule, ValidationFeedbackStrategyBuilder } from '@why520crazy/ngx-validator'; |
| 26 | + |
| 27 | +@NgModule({ |
| 28 | + imports: [ |
| 29 | + CommonModule, |
| 30 | + NgxValidatorModule.forRoot({ |
| 31 | + validationFeedbackStrategy: ValidationFeedbackStrategyBuilder.bootstrap(), // default is bootstrap 4 style |
| 32 | + validationMessages: { |
| 33 | + username: { |
| 34 | + required: 'Username is required.', |
| 35 | + pattern: 'Incorrect username format.' |
| 36 | + } |
| 37 | + }, |
| 38 | + validateOn: 'submit' | 'blur' // default is submit |
| 39 | + }) |
| 40 | + ] |
| 41 | +}) |
| 42 | +class AppModule {} |
| 43 | +``` |
| 44 | + |
| 45 | +### Add directives to form elements |
| 46 | + |
| 47 | +add `ngxFormValidator` directive to form element and add `ngxFormSubmit` directive handle submit event. |
| 48 | + |
| 49 | +```html |
| 50 | + <form name="exampleForm" novalidate [ngxFormValidator]="validatorConfig"> |
| 51 | + <div class="form-group"> |
| 52 | + <label for="email1">Email address</label> |
| 53 | + <input type="email" email class="form-control" name="email" id="email1" |
| 54 | + [(ngModel)]="model.email" required placeholder="Enter email" /> |
| 55 | + </div> |
| 56 | + <button type="button" (ngxFormSubmit)="submit()" class="btn btn-primary">Submit</button> |
| 57 | + <form> |
| 58 | +``` |
| 59 | + |
| 60 | +```ts |
| 61 | +// .ts |
| 62 | +validatorConfig: NgxValidatorConfig = { |
| 63 | + validationMessages: { |
| 64 | + username: { |
| 65 | + required: '用户名不能为空', |
| 66 | + pattern: '用户名格式不正确，以字母，数字，下划线组成，首字母不能为数字，必须是2-20个字符', |
| 67 | + ngxUniqueCheck: '输入的用户名已经存在，请重新输入' |
| 68 | + } |
| 69 | + }, |
| 70 | + validateOn: 'blur' | 'submit' |
| 71 | +}; |
| 72 | + |
| 73 | +submit() { |
| 74 | + // handle submit event |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +## Global configuration |
| 79 | + |
| 80 | +Global configuration can be set by `NgxValidatorModule.forRoot(config)`, or by injecting `NgxValidatorLoader` service at runtime. |
| 81 | + |
| 82 | +| Name | Type | Description | |
| 83 | +| ------------ | ------------------- | --------------- | |
| 84 | +| validationMessages | {[controlName: string]: {[validatorErrorKey: string]: string}} | validation Rules | |
| 85 | +| validationFeedbackStrategy | ValidationFeedbackStrategy | validation feedback strategy which contains error show and hide | |
| 86 | +| globalValidationMessages | {[validatorErrorKey: string]: string} | validator default validation rules | |
| 87 | +| validateOn | 'submit' \| 'blur' | validate trigger | |
| 88 | + |
| 89 | +<br > |
| 90 | + |
| 91 | +Default `globalValidationMessages` rules as below: |
| 92 | + |
| 93 | +``` |
| 94 | +{ |
| 95 | + required: '该选项不能为空', |
| 96 | + maxlength: '该选项输入值长度不能大于{requiredLength}', |
| 97 | + minlength: '该选项输入值长度不能小于{requiredLength}', |
| 98 | + ngxUniqueCheck: '输入值已经存在，请重新输入', |
| 99 | + email: '输入邮件的格式不正确', |
| 100 | + repeat: '两次输入不一致', |
| 101 | + pattern: '该选项输入格式不正确', |
| 102 | + number: '必须输入数字', |
| 103 | + url: '输入URL格式不正确', |
| 104 | + max: '该选项输入值不能大于{max}', |
| 105 | + min: '该选项输入值不能小于{min}' |
| 106 | +}; |
| 107 | +``` |
| 108 | + |
| 109 | +The priority of ngx-form's `validationMessages` config is greater than `validationMessages`, |
| 110 | +it will use `globalValidationMessages` when an element doesn't match form config `validationMessages` or global config validationMessages |
| 111 | + |
| 112 | +## Extensions |
| 113 | + |
| 114 | +Get `formValidator` directive by `<form #formValidator="ngxFormValidator">` or `ViewChild` |
| 115 | + |
| 116 | +1. `formValidator.validator.validateControl(name: string)` validate an control individually |
| 117 | +2. `formValidator.validator.markControlAsError(name: string, errorMessage: string)` show error by server's error code for an control |
| 118 | + |
| 119 | + |
| 120 | +## Custom Feedback Strategy |
| 121 | + |
| 122 | +```ts |
| 123 | +const CUSTOM_INVALID_CLASS = 'custom-invalid'; |
| 124 | +const CUSTOM_INVALID_FEEDBACK_CLASS = 'custom-invalid-feedback'; |
| 125 | + |
| 126 | +export class CustomValidationFeedbackStrategy implements ValidationFeedbackStrategy { |
| 127 | + showError(element: HTMLElement, errorMessages: string[]): void { |
| 128 | + element.classList.add(CUSTOM_INVALID_CLASS); |
| 129 | + // add element show error message |
| 130 | + } |
| 131 | + |
| 132 | + removeError(element: HTMLElement): void { |
| 133 | + element.classList.remove(CUSTOM_INVALID_CLASS); |
| 134 | + // remove element error message |
| 135 | + } |
| 136 | +} |
| 137 | + |
| 138 | +NgxValidatorModule.forRoot({ |
| 139 | + ... |
| 140 | + validationFeedbackStrategy: new CustomValidationFeedbackStrategy(), |
| 141 | + ... |
| 142 | +}) |
| 143 | +``` |
0 commit comments