Angular 表單驗證類庫 ngx-validator 1.0 正式釋出

why520crazy發表於2019-05-16
Angular

背景介紹

之前寫了一篇 《如何優雅的使用 Angular 表單驗證》，結尾處介紹了統一驗證反饋的類庫 ngx-validator ，由於這段時間一直在新模組做微前端以及相關業務元件庫，工具等開發，一直拖到現在，目前正式版 1.0 終於可以釋出了。 可能有些人沒有閱讀過那篇部落格，我這裡簡單介紹下 ngx-validator 主要的功能。

  1. 統一驗證規則和錯誤反饋策略，通過響應式（配置的方式）設定每個元素對應每個驗證器的錯誤提示文案以及統一錯誤資訊反饋，避免手動寫重複的模版實現錯誤提示，讓開發人員專心寫業務即可；
  2. 擴充套件一些 Angular 本身沒有提供驗證器和模版驅動的驗證指令，比如 ngxUniqueCheck、ngxMax、ngxMin;
  3. 支援模版驅動和響應式驅動表單的驗證。

從上次 0.0.1 版本到 1.0.0 正式釋出新增了的功能有：

  1. 新增了 validateOn 支援 submit 和 blur 游標移走驗證，之前只有點選按鈕提交才會驗證
  2. 對響應式表單支援的完善；
  3. 測試和 Demo 的完善；
  4. 重構了程式碼，新增了自動生成 changelog 和 husky 鉤子做 commit message 規範檢查和自動格式化（這些和庫的功能無關，與開發者有關）

使用方式

如果你不想聽我廢話，可以直接看 示例 ，其中包括模版驅動和響應式驅動表單實現驗證的全部程式碼。

安裝

在你的專案中執行命令 npm install @why520crazy/ngx-validator --save 進行模組的安裝

引入模組

在啟動模組 AppModule 中直接引入 NgxValidatorModule，當然引入的時候可以通過 NgxValidatorModule.forRoot 進行一些全域性引數的配置，配置包含全域性的驗證錯誤資訊，錯誤反饋方式，目前反饋方式支援 boostrap4 的表單錯誤樣式和 noop（什麼都不提示），當然你可以擴充套件自己的錯誤反饋策略。

import { NgxValidatorModule, ValidationFeedbackStrategyBuilder } from '@why520crazy/ngx-validator';

@NgModule({
  imports: [
    CommonModule,
    NgxValidatorModule.forRoot({
         validationFeedbackStrategy: ValidationFeedbackStrategyBuilder.bootstrap(),
        validationMessages: {
            username: {
                required: 'Username is required.',
                pattern: 'Incorrect username format.'
            }
        }
    })
  ]
})
class AppModule {}
複製程式碼

模版驅動表單驗證

在 form 表單元素上新增 ngxFormValidator 指令，配置的引數和全域性配置的引數類似，此處單獨配置只會對當前 Form 有效。 由於 ngxFormValidator 採用的驗證器，以及元素是否驗證通過完全讀取的是 Angular 表單提供的資訊，所以模版驅動表單必須遵循 Angular 表單的一些規則：

  1. 表單元素必須設定一個 name，這個 name 會和 ngForm controls 中的物件對應;
  2. 表單元素必須設定 ngModel，當提交表單時通過 ngModel 這隻的變數獲取使用者輸入的資料；
  3. 驗證器直接設定到表單元素上，比如 Angular 內建的 required、email、pattern、maxlength、minlength 以及 ngx-validator 類庫提供的 ngxMax、 ngxMin、ngxUniqueCheck。

最後在提交按鈕上繫結 ngxFormSubmit 事件，當按鈕點選後會觸發表單驗證，驗證不通過會根據每個表單元素配置的提示資訊反饋錯誤，如果使用的預設的 bootstrap4 的反饋策略，會在表單元素上加 is-invalid class 樣式，同時在表單元素後追加 <div class="invalid-feedback">{相關的錯誤提示資訊}</div>

 <form name="exampleForm" [ngxFormValidator]="validatorConfig">
   <div class="form-group">
       <label for="email1">Email address</label>
        <input type="email" email class="form-control" name="email" id="email1"
                [(ngModel)]="model.email" required placeholder="Enter email" />
    </div>
    <button type="button" (ngxFormSubmit)="submit()" class="btn btn-primary">Submit</button>
 <form>
複製程式碼

email-address-error.png

email-address-error-dom.png

響應式驅動表單驗證

響應式表單驗證和模版驅動類似，區別就是不需要給每個元素加 ngModel 和 驗證器，直接使用 formControlName 指令指定名稱, 然後在元件中通過 FormBuilder 生成 group 即可，基本沒有特殊配置，參考 Angular 官網的響應式表單驗證示例即可。

APIs

ngxFormValidator 表單配置

屬性名 型別 備註
validationMessages {[controlName: string]: {[validatorErrorKey: string]: string}} 表單元素驗證規則
validationFeedbackStrategy IValidationFeedbackStrategy 沒有配置，以全域性配置的驗證反饋策略為主
validateOn 'submit' | 'blur' 沒有配置，以全域性配置的 validateOn 為主 
validatorConfig: NgxValidatorConfig = {
    validationMessages: {
        username: {
            required: '使用者名稱不能為空',
            pattern: '使用者名稱格式不正確，以字母，數字，下劃線組成，首字母不能為數字，必須是2-20個字元',
            ngxUniqueCheck: '輸入的使用者名稱已經存在，請重新輸入'
        }
    },
    validateOn: 'submit'
};
複製程式碼

全域性配置

全域性配置可以通過引入 NgxValidatorModule.forRoot(config) 進行設定，也可以在執行時注入 NgxValidatorLoader 服務進行配置

屬性名 型別 備註
validationMessages {[controlName: string]: {[validatorErrorKey: string]: string}} 表單元素驗證規則
validationFeedbackStrategy IValidationFeedbackStrategy 預設以 bootstrap 4 的表單錯誤提示展示
globalValidationMessages {[validatorErrorKey: string]: string} 每個驗證器全域性的預設驗證規則
validateOn 'submit' | 'blur' 觸發驗證，是提交觸發驗證還是游標移走觸發驗證

globalValidationMessages 預設規則如下，當某個表單元素比如 username 在表單和全域性的 validationMessages 都沒有被設定，驗證不通過會直接顯示 globalValidationMessages 中的 required 提示資訊

{
    required: '該選項不能為空',
    maxlength: '該選項輸入值長度不能大於{requiredLength}',
    minlength: '該選項輸入值長度不能小於{requiredLength}',
    ngxUniqueCheck: '輸入值已經存在，請重新輸入',
    email: '輸入郵件的格式不正確',
    repeat: '兩次輸入不一致',
    pattern: '該選項輸入格式不正確',
    number: '必須輸入數字',
    url: '輸入URL格式不正確',
    max: '該選項輸入值不能大於{max}',
    min: '該選項輸入值不能小於{min}'
};
複製程式碼

擴充套件方法

  1. 單獨驗證某一個表單元素, 獲取到 NgxFormValidatorDirective 例項 ngxFormValidator: NgxFormValidatorDirective，通過呼叫 ngxFormValidator.validator.validateControl(name: string) 方法單獨驗證；
  2. 根據服務端返回的錯誤，設定某個表單元素錯誤提示資訊，呼叫 ngxFormValidator.validator.markControlAsError(name: string, errorMessage: string)

自定義反饋策略

如果你的專案不是使用 bootstrap4，而是其他 UI 庫，那麼可以通過擴充套件自己的錯誤反饋策略，然後在全域性設定中配置一次後所有的表單驗證都會使用配置之後的策略，以下是一個自定義反饋策略的示例：

const CUSTOM_INVALID_CLASS = 'custom-invalid';
const CUSTOM_INVALID_FEEDBACK_CLASS = 'custom-invalid-feedback';

export class CustomValidationFeedbackStrategy implements IValidationFeedbackStrategy {
    showError(element: HTMLElement, errorMessages: string[]): void {
        element.classList.add(CUSTOM_INVALID_CLASS);
        // add element show error message
    }

    removeError(element: HTMLElement): void {
        element.classList.remove(CUSTOM_INVALID_CLASS);
       // remove element error message
    }
}
複製程式碼

原文地址：zhuanlan.zhihu.com/p/65972116

相關文章