Skip to content

如果你受够了饿了么ElementUI原生的校验方式,那就来试试它吧!一款更懂你的校验插件

Notifications You must be signed in to change notification settings

xiaogeneral/element-ui-verify

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

element-ui-verify

如果你受够了饿了么ElementUI原生的校验方式,那就来试试它吧!

前言

饿了么ElementUI虽好,但表单校验的体验不够理想

如果说产品开发要讲究用户体验,那插件开发也要讲究开发体验,而好的开发体验,要靠好的api设计来保障

本人专注校验插件开发30年,有祖传的校验插件api设计(玩笑)。主要是参考了之前写的vue-verify-pop的api,并加以完善,取值精华,去其糟粕,揉和日月之精华。。。

本插件只是对ElementUI原本的校验方式做了一层封装,核心的校验器仍然是async-validator,非侵入式,完全不会影响你继续使用ElementUI的原生校验

安装

npm install element-ui-verify

使用

环境

VUE版本:2.x webpack模块环境

一,安装

import Vue from 'vue'
import elementUI from 'element-ui'
import elementUIVerify from 'element-ui-verify'

// 这里注意必须得先use elementUI
Vue.use(elementUI)
Vue.use(elementUIVerify)

二,在el-form-item上配置校验规则

<template>
  <el-form :model="model">
    <el-form-item prop="age" verify number>
      <el-input v-model.number="model.age"></el-input>
    </el-form-item>
  </el-form>
</template>
<script>
export default{
  data () {
    return {
      model: {
        age: ''
      }
    }
  }
}
</script>

ok,您已经完成了一个内容不能为空且为数字的基础校验!(欢迎对比官方版的相似例子)

默认支持的校验规则

  • length: 校验文本长度
  • minLength: 校验文本最短长度
  • gt: 校验数字要大于某数
  • gte: 校验数字要大于等于某数
  • lt: 校验数字要小于某数
  • lte: 校验数字要小于等于某数
  • maxDecimalLength: 校验数字最大小数位
  • number: 校验是否为数字
  • int: 校验是否为整数
  • phone: 校验是否为手机号(随着号段的增加,未来可能需要更新)
  • email: 校验是否为电子邮件地址
  • verifyCode: 校验是否为6位数字验证码

配置

errorMessage

错误提示模板。默认值:默认模板

如要使用自定义模板,模板内容要覆盖默认模板中定义的所有字段,否则某些规则可能出空错误提示

fieldChange

当绑定字段变化时,插件的默认行为。默认值:'verify'

注意:在输入框失去焦点时会始终触发校验

verify

当绑定字段变化时会实时触发校验

clear

当绑定字段变化时只清空校验结果,不触发校验

Vue.use(elementUIVerify, {
  errorMessageTemplate: yourErrorMessageTemplate,
  fieldChange: 'clear'
})

重要选项说明

verify

若要使用本插件,verify选项是必须的,换句话说,如果没有配置该选项,那么您仍然可以正常使用ElementUI原生的校验

该选项还可以接收一个函数值,用于自定义校验方法

errorMessage

用于自定义校验不通过提示(空检测和自定义校验方法的错误提示不受该值影响)

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

canBeEmpty

插件默认开启输入内容不为空校验,如果开启该选项,一旦该输入项为空则会忽略该输入项之后所有的校验

该选项一般用于如下情况,比如邀请码这种一般可以为空,不为空又需要校验的输入项

<!--当邀请码不为空时才校验长度是否等于6-->
<el-form-item prop="invitationCode" verify can-be-empty :length="6" error-message="邀请码不正确"></el-form-item>

space

插件执行空检测时默认忽略空格,也就是说某个输入框中如果只输入了空格是过不了空检测的,除非设置该选项

<el-form-item prop="test" verify space></el-form-item>

alias

插件保留Macro

懒人的福音,用于复用错误提示,默认值:"该输入项"。使用场景:

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

{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,很贴心有木有)

fieldChange

参见全局fieldChange配置

watch

监听其他变量,触发自身校验

一个常见例子:密码一致性校验,pass1的变化会触发pass2的校验(欢迎对比官方版的相似例子)

<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>
</template>
<script>
export default{
  data () {
    return {
      model: {
        pass1: '',
        pass2: ''
      }
    }
  },
  methods: {
    verifyPassword (rule, val, callback) {
      if (val !== this.pass1) callback(Error('两次输入密码不一致!'))
      else callback()
    }
  }
}
</script>

再举一个不适合使用该选项的场景,比如下面这个最少最多人数的例子,最少人数变化要触发最多人数的校验:

<template>
  <el-form :model="model">
    <el-form-item label="最少参与人数" prop="minNumber" verify int :gt="0">
      <el-input v-model.number="model.minNumber"></el-input>
    </el-form-item>
    <el-form-item label="最多参与人数" prop="maxNumber" verify int :gt="model.minNumber" :watch="minNumber">
      <el-input v-model.number="model.maxNumber"></el-input>
    </el-form-item>
  </el-form>
</template>

其实watch选项在这里完全没必要,因为插件会响应所有校验参数的变化来触发自身校验,最多参与人数的gt值引用了model.minNumber,一旦model.minNumber变化,就会触发校验

如果你再watch一下,反而会多触发一次。所以这样即可:

<el-form-item label="最多参与人数" prop="maxNumber" verify int :gt="model.minNumber"></el-form-item>

注意事项

  • 所有选项调用不能有大写字母,用中划线分隔,同vue props属性设置规则
  • length,minLength,gt,gte,lt,lte,maxDecimalLength等需要接收数值的选项,该值需为数字(:length="1")
  • verify,canBeEmpty,space,number,int等无须接收值的选项一旦设置了,可以通过赋值为undefined来取消

规则简写

number,int,phone等无须设定值的选项可以直接:

<el-form-item prop="prop" verify number></el-form-item>
<!--不用这么写-->
<el-form-item prop="prop" verify :number="true"></el-form-item>

gt,gte,lt,lte,maxDecimalLength等数字规则无须再写number规则

<!--该输入项内容必须为不大于10的数字-->
<el-form-item prop="prop" verify :lte="10"></el-form-item>
<!--不用这么写-->
<el-form-item prop="prop" verify number :lte="10"></el-form-item>

全局API

addRule (name: string | VerifyRulePropOptions, getter: RuleGetter): RuleGetter

用于自定义校验规则

name: 规则名称

本插件的校验选项基于Vue组件的Prop,故该参数可以是一个类似VueProp的配置项:

{
  name: 'length',
  type: Number,
  validator (v) {
     return v > 0
  }
}

这么做的好处是可以对规则接收值本身也做一些限制,提前规避一些不必要的调用错误,比如:

<el-form-item prop="prop" verify length="哈哈哈"></el-form-item>

上述这种情况,就很有可能使你的校验文本长度规则出现异常。当然了,如果您对调用者比较相信或者是那种无须接收值的规则,也可以省事点直接这样:

import elementUIVerify from 'element-ui-verify'
elementUIVerify.addRule('length', length => SomeRule)

getter: asyncValidatorRule获取方法

该回调可以返回单条规则或规则数组,具体规则需要参见async-validator

// 单条
() => ({type: 'number', message: '请输入数字'})
// 多条
gte => [
  {type: 'number', message: '请输入数字'},
  {type: 'number', min: gte, message: `该数字不能小于${gte}`}
]

如果对上述示例中多条规则重复定义了type有疑问的同学,可以看这里

getRule (name: string): RuleGetter

用于获取校验规则。一般是和自定义校验规则搭配使用,方便已有规则的复用

返回内容即为addRule传入的getter参数

getErrorMessage (name: string, templateData?: any): string

用于从通用错误提示模板中获取错误提示。一般是和自定义校验规则搭配使用

假设错误提示模板为

{
  // 没有Macro
  empty: '该输入项内容不能为空',
  // Macro正好等于RuleName
  length: '该输入项内容长度需要等于{length}',
  // Macro不等于RuleName
  maxDecimalLength: '该输入项最多接受{MDL}位小数'
}

调用示例:

import elementUIVerify from 'element-ui-verify'
// 返回:"该输入项内容不能为空"
elementUIVerify.getErrorMessage('empty')
// 返回:"该输入项内容长度需要等于10"
elementUIVerify.getErrorMessage('length', 10)
// 返回:"该输入项最多接受2位小数"
elementUIVerify.getErrorMessage('maxDecimalLength', {MDL: 2})

自定义校验方法

如果自带的校验规则满足不了您的需求,可以在校验规则中插入您自己的校验方法

自定义校验方法在校验规则都通过后才会执行

<template>
  <el-form :model="model">
    <el-form-item label="卡号" prop="cardNumber" :verify="verifyCardNumber" :length="6">
      <el-input v-model.number="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'].indexOf(val.substr(0, 3)) === -1) callback(Error('错误的卡号'))
      else callback()
    }
  }
}
</script>

自定义校验规则

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

前言已经说过,本插件的核心校验器来自async-validator,故校验规则需要您先参考它的文档

示例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 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 :int-length="10"></el-form-item>

更多示例您可以直接翻看本插件源码中默认规则的添加

插件的默认校验不通过提示模版

{
  empty: '请补充该项内容',
  length: '请输入{length}位字符',
  minLength: '输入内容至少{minLength}位',
  number: '请输入数字',
  int: '请输入整数',
  lt: '输入数字应小于{lt}',
  lte: '输入数字不能大于{lte}',
  gt: '输入数字应大于{gt}',
  gte: '输入数字不能小于{gte}',
  maxDecimalLength: '该输入项最多接受{maxDecimalLength}位小数',
  phone: '请输入正确的手机号',
  email: '请输入正确的邮箱',
  verifyCode: '请输入正确的验证码'
}

常见问题

为什么不把prop配置项干掉?每次都要写校验规则都要写它好烦!

我也烦。但本插件是基于ElementUI的,所以很多地方会受到原始校验机制的限制,还要尽可能不对它产生影响。比如这个prop选项,如果把它干掉,会影响到el-form的校验,因为ElementUI以prop作为uid来存储校验队列

如何切换校验类型?比如某个输入框可能输入手机号也可能输入邮箱

<el-form-item prop="prop" verify phone v-if="isPhone"></el-form-item>
<el-form-item prop="prop" verify email v-else></el-form-item>

在规则变化不多的情况下也可以这样(该种方式切换类型时会立即触发校验)

<el-form-item prop="prop" verify :phone="isPhone ? true : undefined" :email="isPhone ? undefined : true"></el-form-item>

其他

在写gte规则的时候,我首先引用了async-validator的数字类型规则,然后再引用了它的Range规则, 而它的Range规则同时支持字符串和数字,所以针对数字的校验需要显式再设置一遍type: number,这虽然会导致gte规则可能会校验两遍类型是否为数字,不过性能影响不大

// 这里的min显然是要校验数字的
[
  {type: 'number'},
  {min: 3}
]
// 然而你必须得写成
[
  {type: 'number'},
  {type: 'number', min: 3}
]
// 当然了你也可以通过写自定义校验函数来规避此问题,不过此问题没这个必要
[
  {type: 'number'},
  {
    validator (rule, val, callback) {
      if (val < 3) callback(Error('不能小于3'))
    }
  }
]

也不能算是async-validator的缺点吧,基于它当前的规则约定如果做规则推断的话收益不大,还会增加校验规则的不确定性,给调用者造成困惑。不过只针对本需求的话可以考虑把文本和数字的range规则给分开

这里可能你会问那为什么不直接用单条规则?

{type: 'number', min: 3, errorMessage: 'xxxx'}

如果这么写了,输入非数字的错误提示会是原始错误提示模板中的内容。为了不破坏ElementUI的原生校验(修改原始错误提示模板)和最大化复用async-validator内置的校验,只得通过拆分规则来让校验错误提示更具体

之后您在自定义校验规则的时候,如遇类似问题也可考虑通过规则拆分来让错误提示更具体

后话

由于本插件的校验选项是基于VueProp,有如下缺点:

  • 随着ElementUI的更新,未来有可能会和它的某些新增选项产生冲突
  • 难以做到按照校验规则的书写顺序来执行校验,目前的大顺序是:空检测 > 通用规则 > 自定义校验方法。不过该条的影响不是很大,现有规则下的大部分场景不需要考虑规则顺序

About

如果你受够了饿了么ElementUI原生的校验方式,那就来试试它吧!一款更懂你的校验插件

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 100.0%