element-verify

前言

本插件基于Vue2.x + typescript（表单校验核心代码）+ vite + vitest这几个技术栈，绝大部分功能和element-verify v0.2.3仓库地址保持一致，表单校验核心代码参照了element-ui-verify官方文档。

和element-form-verify v0.2.3不同的是，当前版本主要解决了如下问题：

1. 校验逻辑支持使用validator.js配置，而不是完全依赖自己写一套，解决校验逻辑不全的问题；
2. 高质量地重构代码，解决代码难以维护和莫名其妙不生效的问题；
3. 规范命名，解决中英夹杂、中式英语的问题；
4. 规范api。

代码地址

仓库地址

支持功能

1. 内置常见校验 √
2. 支持非必须校验(非必填项且有输入时校验) √
3. 支持watch关联校验触发(原trigger实现功能与watch重复，该版本去除trigger) √
4. 支持全局注入校验规则 √
5. 支持校验自定义提示 √

快速使用

使用方法：

import ElementVerify from 'element-verify'
Vue.use(ElementVerify, {
  errorMessageTemplate: yourErrorMessageTemplate,
  fieldChange: 'clear',
})

输入参数选项对象，支持选项如下:

  ________________________________________________________________________________________________
|     参数                   说明                        类型             可选值          默认值   |
|------------------------------------------------------------------------------------------------|
| errorMessageTemplate 必填项校验未通过时的提示文案          object             ——            默认模板 |
|------------------------------------------------------------------------------------------------|
|   fieldChange     当绑定字段变化时，插件的默认行为          string             ——           ’verify’|
|————————————————————————————————————————————————————————————————————————————————————————————————|

errorMessageTemplate 错误提示模板。默认值：默认模板

如要使用自定义模板，模板内容要覆盖 默认模板 中定义的所有字段，否则 getErrorMessage 在获取不到值的时候会抛异常

fieldChange 当绑定字段变化时，插件的默认行为。默认值：’verify’。 注意：在输入框失去焦点时会始终触发校验 verify 当绑定字段变化时会实时触发校验 clear 当绑定字段变化时只清空校验结果，不触发校验

<!-- verify - 表示该表单字段是必填字段 -->
<el-form-item label="示例" prop="name" verify>
  <el-input v-model="form__.name"></el-input>
</el-form-item>

关于插件与原生校验规则优先级问题

插件的校验是非侵入式的，不会影响原生校验规则，总体上其优先级是原生校验规则 > 插件校验规则，两者是可以同时使用的。

插件使用方法

插件的开关和入口（verify）

概述：

1. verify字段是插件的总开关，该字段存在，插件功能才会生效，若要使用本插件，verify 选项是必须的；
2. verify的另一个作用是表示该表单字段是必填字段。

使用实例：

<el-form-item label="示例" prop="name" verify>
  <el-input v-model="form__.name"></el-input>
</el-form-item>

常规校验

概述： 常规校验则是指常见的普通校验，常规校验为校验的核心功能，插件内置了常见场景的校验，后期会随着搜集越来越丰富，也希望大家踊跃提供自己需要的校验场景。

verify字段注明: verify接收类型包括String、Object、Fucntion，空字符串类型表示开关插件以及该表单字段是否必填，Object类型表示需要校验的属性，Function类型时表示自定义的校验方法。

类型相关：检查输入内容类型的校验

数字类型

包括(正、负)整数 && 0 && (正、负)浮点数，使用 :verify="{ type: 'number' }"

<el-form-item label="手机号码" prop="phone" :verify="{ type: 'number' }">
  <el-input v-model="form__.phone"></el-input>
</el-form-item> 

整数类型

包括(正、负、0)整数，使用 :verify="{ type: 'int' }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'int' }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

最多小数位

使用 :verify="{ maxDecimalLength: 2 }"

<el-form-item label="表单项" prop="val" :verify="{ maxDecimalLength: 2 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

正整数类型（不包括0）

使用 :verify="{ type: 'int', gt: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'int',  gt: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

正整数类型（包括0）

使用 :verify="{ type: 'int', gte: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'int', gte: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

负整数类型（不包括0）

使用 :verify="{ type: 'int', lt: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'int', lt: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

负整数类型（包括0）

使用 :verify="{ type: 'int', lte: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'int', lte: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

小数类型，包括0 && (正、负)浮点数

使用 :verify="{ type: 'decimal' }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'decimal' }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

正小数类型（不包括0）

使用 :verify="{ type: 'decimal', gt: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'decimal', gt: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

正小数类型（包括0）

使用 :verify="{ type: 'decimal', gte: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'decimal', gte: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

负小数类型（不包括0）

使用 :verify="{ type: 'decimal', lt: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'decimal', lt: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

负小数类型（包括0）

使用 :verify="{ type: 'decimal', lte: 0 }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'decimal', lte: 0 }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

英文字母(包括大小写)

使用 :verify="{type: 'en'}"

<el-form-item label="表单项" prop="val" :verify="{type: 'en'}">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

小写英文字母

使用 :verify="{type: 'en.lower'}"

<el-form-item label="表单项" prop="val" :verify="{type: 'en.lower'}">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

大写英文字母

使用 :verify="{type: 'en.upper'}"

<el-form-item label="表单项" prop="val" :verify="{type: 'en.upper'}">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

中文

使用 :verify="{type: 'cn'}"

<el-form-item label="表单项" prop="val" :verify="{type: 'cn'}">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

特殊字符

使用 :verify="{type: 'special'}" 注明：特殊字符包括常见的[.,!#$%^&*@_+-/?]

<el-form-item label="表单项" prop="val" :verify="{type: 'special'}">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

自选类型组合

使用 :verify="{ type: 'en|number', includes: 'number' }"

<el-form-item 
  label="用户名" 
  prop="username" 
  :verify="{ type: 'en|number', includes: 'number' }"
>
  <el-input v-model="form__.username"></el-input>
</el-form-item>

注明：

1. 自选类型组合是用来校验内容是几种类型组合的场景，例如用户密码输入。要求用户密码只能由大小写字母、数字、 特殊符号组成，且必须包含大写字母，即可使用规则:verify="{ type: 'en|number|special', includes: 'en.upper' }"。 typeOptions接收一个数组作为参数，数组参数里包含两个变量['可选字符类型', '必须包含的字符类型']，可选字符类型 表示用户可以输入哪些类型的字符，必须包含的字符类型表示用户输入内容必须包含此类型字符，多类型使用|进行分隔；
2. 可选字符类型是必填选项，必须包含的字符类型是选填选项，不填则表示没有必须包含的字符类型；
3. 可选字符类型 / 必须包含的字符类型可填值有如下被支持：

const strategy = {
  'en.upper': 'A-Z',
  'en.lower': 'a-z',
  'en': 'A-Za-z',
  'number': '0-9',
  'cn': '\u4e00-\u9fa5',
  'special': '/./,/!/#/$/%/^/&/*/@/_/+/(/)/-/?',
  '.': '/.',
  ',': '/,',
  '!': '/!',
  '#': '/#',
  '$': '/$',
  '%': '/%',
  '^': '/^',
  '&': '/&',
  '*': '/*',
  '@': '/@',
  '_': '/_',
  '+': '/+',
  '(': '/(',
  ')': '/)',
  '-': '/-',
  '?': '/?',
}

数字比较相关

对输入内容与预期大小比较的校验，只支持数字类型字符。

数字大于

使用 :verify="{ gt: 100 }"

<el-form-item label="价格" prop="price" :verify="{ gt: 100 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

数字大于等于

使用 :verify="{ gte: 100 }"

<el-form-item label="价格" prop="price" :verify="{ gte: 100 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

数字小于

使用 :verify="{ lt: 100 }"

<el-form-item label="价格" prop="price" :verify="{ lt: 100 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

数字小于等于

使用 :verify="{ lte: 100 }"

<el-form-item label="价格" prop="price" :verify="{ lte: 100 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

数字等于

使用 :verify="{ eq: 100 }"

<el-form-item label="价格" prop="price" :verify="{ eq: 100 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

文本相关

对文本长度相关的校验

文本长度

使用 :verify="{ length: 5 }"

<el-form-item label="姓名" prop="name" :verify="{ length: 5 }">
  <el-input v-model="form__.name"></el-input>
</el-form-item>

最小文本长度

使用 :verify="{ minLength: 5 }"

<el-form-item label="价格" prop="price" :verify="{ minLength: 5 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

最大文本长度

使用 :verify="{ maxLength: 5 }"

<el-form-item label="价格" prop="price" :verify="{ maxLength: 5 }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

常用相关：常见相关场景的校验

注明：便于通用选项好记忆，一般w代表弱校验、s代表强校验

手机号一般校验(11位数字、第二位3-9)

使用 :verify="{ type: 'phone' }"

<el-form-item label="价格" prop="price" :verify="{ type: 'phone' }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

手机号强校验(弱校验基础上、号段限制)

使用 :verify="{ type: 'sphone' }"

<el-form-item label="价格" prop="price" :verify="{ type: 'sphone' }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

1. 移动号段有134,135,136,137, 138,139,147,150,151,152,157,158,159,178,182,183,184,187,188。
2. 联通号段有130，131，132，155，156，185，186，145，176。
3. 电信号段有133，153，177，180，181，189。
   这个号段名单随反馈增量更新

座机号码校验

使用 :verify="{ type: 'telephone' }"

<el-form-item label="价格" prop="price" :verify="{ type: 'telephone' }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

注明：

1. 只针对国内座机号；
2. 地区号以0开头；
3. 地区号一般3~4位；
4. 地区号与号码间用-符号连接；
5. 号码一般7~8位。

邮箱（一般校验）

使用 :verify="{ type: 'email' }"

<el-form-item label="价格" prop="price" :verify="{ type: 'email' }">
  <el-input v-model="form__.price"></el-input>
</el-form-item>

邮箱（强校验）

指定固定邮箱列表，使用 :verify="{ semail: ['@qq.com', '@outlook.com', '@gmail.com'] }"

<el-form-item 
  label="价格" 
  prop="price" 
  :verify="{ semail: ['@qq.com', '@outlook.com', '@gmail.com'] }"
>
  <el-input v-model="form__.price"></el-input>
</el-form-item>

注明：semail支持校正指定邮箱列表，接收一个邮箱列表的数组为参数

url链接（一般校验）

使用 :verify="{ type: 'url' }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'url' }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

url链接（强校验）

指定固定url开头链接，使用 :verify="{ surl: 'https://' }"

<el-form-item label="表单项" prop="val" :verify="{ surl: 'https://' }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

身份证校验(支持1/2代身份证)

使用 :verify="{ type: 'idCard' }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'idCard' }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

注明：

1. 对于1代15位身份证号码只会校验区域号 / 出身年月日是否符合规则；
2. 对于2代18位身份证号码除了校验区域号 / 出身年月日，还会最后计算检查最后一位校验位，可以避免90%以上假身份号码错误。

密码选项匹配

使用 :verify="{ password: [最小长度, 最大长度, 可选的选项, 必须存在的选项] }"

<el-form-item 
  label="密码" 
  prop="password" 
  :verify="{ password: [6, 18, 'en|number|special', 'en.upper|special'] }"
>
  <el-input v-model="form__.password"></el-input>
</el-form-item>

以上校验表示，输入一个长度为6 ~ 18位，只能由字母、数字、特殊字符组成，且必须包含大写字母、特殊字符的密码 注明：

1. password专职用于密码校验，使用方法和typeOptions类似，唯一不同是password接收的数组参数包含四个变量[最小长度, 最大长度, 可选字符类型, 必须包含的字符类型]；
2. 可选字符类型 / 必须包含的字符类型可填值有如下被支持：

const strategy = {
  'en.upper': 'A-Z',
  'en.lower': 'a-z',
  'en': 'A-Za-z',
  'number': '0-9',
  'cn': '\u4e00-\u9fa5',
  'special': '/./,/!/#/$/%/^/&/*/@/_/+/(/)/-/?',
  '.': '/.',
  ',': '/,',
  '!': '/!',
  '#': '/#',
  '$': '/$',
  '%': '/%',
  '^': '/^',
  '&': '/&',
  '*': '/*',
  '@': '/@',
  '_': '/_',
  '+': '/+',
  '(': '/(',
  ')': '/)',
  '-': '/-',
  '?': '/?',
}

自定义校验方法

使用示例如下：

<template>
  <el-form :model="model">
    <el-form-item
      label="卡号"
      prop="cardNumber"
      :verify="verifyCardNumber"
      :length="6"
    >
      <el-input v-model="model.cardNumber"></el-input>
    </el-form-item>
  </el-form>
</template>
<script>
  export default {
    data() {
      return {
        model: {
          cardNumber: '',
        },
      }
    },
    methods: {
      // callback形式
      // 校验是否是010，011开头的卡号
      verifyCardNumber(rule, val, callback) {
        // rule: 这个参数很恶心，不经常用到还要放在第一位，不过为了保持async-validator的风格，还是留着它了
        // val: 待校验值
        // callback: 校验结果回调 具体可以点击上文的"校验方法"链接查看
        if (!['010', '011'].includes(val.substr(0, 3)))
          callback(Error('错误的卡号'))
        else callback()
      },
    },
  }
</script>

6位数字验证码

使用 :verify="{ type: 'verifyCode' }"

<el-form-item label="表单项" prop="val" :verify="{ type: 'verifyCode' }">
  <el-input v-model="form__.val"></el-input>
</el-form-item>

使用validator.js配置校验逻辑

使用 :verify="{ validatorjs: ['validator方法名', '校验不通过错误提示标题', 其他参数] }"，由于除了validator方法名，还需要传入其他配置参数等，故validator属性为数组类型。其中validator方法名必填，校验不通过错误提示标题必填，其他参数为选填。

<el-form-item 
  label="validator.js校验必填" 
  prop="validatorVerifyValue" 
  :verify="{ validatorjs: ['isEmail', '邮箱'] }"
> 
  <el-input v-model="form__.validatorVerifyValue"></el-input>
</el-form-item>

<el-form-item 
  label="validator.js校验contains通过" 
  prop="validatorContainsTypeValidValue" 
  :verify="{ 
    validatorjs: [
      'contains',  
      '至少包含2个abc', 
      'abc', 
      { ignoreCase: false, minOccurrences: 2 }
    ] 
  }"
> 
  <el-input v-model="form__.validatorContainsTypeValidValue"></el-input>
</el-form-item>

空检测错误提示

使用实例：

<el-form-item prop="head" verify empty-message="请上传头像"></el-form-item>

非必须校验器

使用 :verify="{ required: false }" 概述： “required: false”意指可以为空，但不是不校验的意思. 当表单字段内容为空时不进行校验放行，当表单字段内容不为空时进行校验。

使用场景： 非必须校验的使用场景虽然不是很常用，但是也是不少见的. eg: 手机号码字段，如果该字段不是很重要，既可以设置成非必填字段，但是一旦用户输入，手机号码本身存在规则(只有11位、全是数字等)，此时是需要进行校验的，非必须校验器就比较适合了。

使用实例：

<el-form-item 
  label="手机号码" 
  prop="phone" 
  :verify="{ required: false, type: 'phone' }"
>
  <el-input v-model="form__.phone"></el-input>
</el-form-item>      

自定义校验不通过提示errorMessage

自定义校验方法的错误提示不受该值影响。

<el-form-item
  prop="numberProp"
  verify
  number
  error-message="请输入正确的数字"
></el-form-item>

alias

懒人的福音，用于复用错误提示，默认值：”该输入项”。使用场景：

假设你的空检测错误提示模板为：

{empty: '{alias}不能为空'}

<el-form-item prop="unknown" verify></el-form-item>
<el-form-item alias="姓名" prop="name" verify></el-form-item>
<el-form-item label="地址" prop="address" verify></el-form-item>

当unknown输入框为空时，会提示”该输入项不能为空”（alias 值默认为”该输入项”） 当姓名输入框为空时，会提示”姓名不能为空”（显式设置了 alias 值时，提示内容自然会以该值去替换模板) 当地址输入框为空时，会提示”地址不能为空”（大部分 el-form-item 都需要设置一个 label 项，而 label 项往往就代表该输入项的 alias，因此插件会取该值直接作为 alias，很贴心有木有）。

联动校验器(watch)

概述： 联动校验意指一个表单字段的变化引起另一个字段校验的触发。 使用场景：联动校验的使用场景比较业务型，大多是基于业务来考虑。 watch eg: 商品的原价不低于售卖价格

<template>
  <el-form :model="model">
    <el-form-item label="密码" prop="pass1" verify>
      <el-input v-model="model.pass1"></el-input>
    </el-form-item>
    <el-form-item
      label="确认密码"
      prop="pass2"
      :verify="verifyPassword"
      :watch="model.pass1"
    >
      <el-input v-model="model.pass2"></el-input>
    </el-form-item>
    <el-form-item label="账号" prop="userName" verify>
      <el-input v-model="model.userName"></el-input>
    </el-form-item>  
  </el-form>
</template>

<script>
  export default {
    name: 'WatchComponent',
    data() {
      return {
        model: {
          pass1: '',
          pass2: '',
          userName: ''
        },
      }
    },
    methods: {
      verifyPassword(rule, val, callback) {
        if (val !== this.model.pass1) callback(Error('两次输入密码不一致!'))
        else callback()
      },
    } 
  }
</script>

效果：当售价字段内容被改变时，会触发原价字段进行价格比价的校验，达到提醒售价设置不能低于原价的场景。

全局注入选项

概述： 全局注入选项是插件在注入Vue时提供的部分全局功能支持选项。

和自定义校验方法的区别是这个适用于全局，等于增加插件自带的校验规则。

示例 1：新增一个校验是否为 10 位整数的规则。

import elementUIVerify from 'element-ui-verify'
// 通过getRule方法复用已有的int规则
const intRuleGetter = elementUIVerify.getRule('int')
elementUIVerify.addRule('int10', () => [
  // 首先校验是否为整数
  intRuleGetter(),
  // 再校验是否为10位
  {
    validator(rule, val, callback) {
      if ((val + '').length !== 10) {
        // 尽量将出错提示定义在错误模板中（假设为{int10: '该输入项为10位整数'}）
        const errorMessage = elementUIVerify.getErrorMessage('int10')
        callback(Error(errorMessage))
      } else callback()
    },
  },
])

这样就完成了一个简单的规则拓展，你就可以在任何地方像使用默认规则那样来调用你的自定义规则，如下：

<el-form-item prop="prop" :verify="{ type: 'int10' }"></el-form-item>

示例 2：新增一个校验是否为任意位整数的规则，与上面不同的是该规则需要接收一个规则参数

import elementUIVerify from 'element-ui-verify'
const intRuleGetter = elementUIVerify.getRule('int')
// 这里最好不要再直接传入'intLength'了，而是一个类似VueProp的配置项，来对规则参数稍作限制
elementUIVerify.addRule({ name: 'intLength', type: Number }, (intLength) => [
  intRuleGetter(),
  // 校验整数长度是否符合规则
  {
    validator(rule, val, callback) {
      if ((val + '').length !== intLength) {
        // 假设出错模板为{intLength: '该输入项为{intLength}位整数'}
        const errorMessage = elementUIVerify.getErrorMessage(
          'intLength',
          intLength,
        )
        callback(Error(errorMessage))
      } else callback()
    },
  },
])

调用:

<el-form-item prop="prop" :verify="{ intLength: 10 }"></el-form-item>

Q&A一些常见问题

1. 如何才能修改错误提示？
  答: 当前版本提出的解决方案如下:
    a. 使用errorMessageTemplate
    b.使用自定义校验方法
    c. 使用全局方法addRule，这样就可以自己定义规则和错误提示

2. 如何自定义校验规则？
  答：插件留给使用者自定义校验规则有以下两种方式:
      a. 使用自定义校验方法
      b. 使用全局方法addRule

单元测试

单元测试使用vitest，vitest对node和vite版本要求如下： "node": ">=14", "vite": ">= 2.7.10"

单元测试基础功能已调通，但是如果引入ElementFormVerify，跑单元测试报错，后期会解决这个问题。

目前使用手动测试，执行npm run dev即可全面测试。