Angular 表单验证类库 ngx-validator 1.0 正式发布

背景介绍

以前写了一篇 《如何优雅的使用 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 样式，同时在表单元素后追加 {相关的错误提示信息}

Email address
        
    
    Submit

响应式驱动表单验证

响应式表单验证和模版驱动相似，区别就是不须要给每一个元素加 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	没有配置，以全局配置的验证反馈策略为主
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
    }
}

Worktile 官网：worktile.com

本文做者：徐海峰

文章首发于「Worktile官方博客」，转载请注明出处。