vee-valida3 基础用法

vee-validate3 中文文档

• vee-validate官方文档

Validation Provider

• 实现原理:ValidationProvider 通过 scoped-slots(作用域插槽) 将包裹的input元素的校验状态注入到slot props(插槽props) 中，使ValidationProvide组件能够读取到input的校验状态.

• 注册一个Validation Provider组件:

  • 组件内注册:

  import { ValidationProvider } from 'vee-validate';
  export default {components: {ValidationProvider}
  };
  

  • 全局注册:

  import { ValidationProvider } from 'vee-validate';
  Vue.component('ValidationProvider', ValidationProvider);
  

• 注册组件完成后,就可以在template模板中使用ValidationProvide组件了。一般来说，需要用ValidationProvider元素包裹住你将要校验的input元素:

  <ValidationProvider v-slot="v"><input type="text" v-model="value">
  </ValidationProvider>
  

  注意，需要校验的input元素务必要用v-model或者v-bind绑定一个响应式数据，用于提示ValidationProvider将要校验VueComponent(组件实例)身上的哪个属性

• 至此，我们可以通过slot props(插槽props)去获取该field(字段) 校验不通过时的错误提示:

  <ValidationProvider v-slot="v"><input v-model="value" type="text"><span>{{ v.errors[0] }}</span>
  </ValidationProvider>
  

Registering the Validation Provider(添加校验规则)

默认情况下,VeeValidate并不会安装任何校验规则以保证包体尽量的精简

• extend函数

  • extend(name,function(value)) 接收两个参数,其中name是规则的名称;function(value)是validator function(校验函数)

    import { extend } from 'vee-validate';
    extend('positive', value => {return value >= 0;
    });
    

    也可以通过ES6语法中的解构赋值,来简化上面的写法

    <ValidationProvider rules="positive" v-slot="{ errors }"><input v-model="value" type="text"><span>{{ errors[0] }}</span>
    </ValidationProvider>
    

    一般情况下,我们会将添加的rules(规则)放到单独的validate.js文件中,然后在入口文件main.js中通过import 'validate'来加载js文件

  • 当想要将多种校验规则同时加到一个input元素时,可以通过|管道符去分离这些rules

    <ValidationProvider rules="positive|odd|prime|fib" v-slot="{ errors }"><input v-model="value" type="number"><span>{{ errors[0] }}</span>
    </ValidationProvider>
    

  • extend函数的第二个参数还可以传入一个对象,extend(name,options)

    import { extend } from 'vee-validate';
    extend('odd', {validate: value => {return value % 2 !== 0;}
    });
    

Rule Arguments(规则参数)

• params参数,该参数是一个数组,可以指定外部传的params参数字段,使用规则时可以在rules属性上通过: 向validate function传递参数,比如rules="max:3",提高规则的复用率

  • 定义规则:

    extend('minmax', {validate(value, { min, max }) {return value.length >= min && value.length <= max;},params: ['min', 'max']
    });
    

  • 使用规则:

    <ValidationProvider rules="minmax:3,8" v-slot="{ errors }"><input v-model="value" type="text"><span>{{ errors[0] }}</span>
    </ValidationProvider>
    

    在rules属性中,给指定的规则后用:来按顺序传递params参数

• 有时候我们需要验证某个字段是否在一个集合中,这时候就可以考虑使用 one_of 规则:

  • 定义规则:

    import { extend } from 'vee-validate';
    extend('one_of', (value, values) => {return values.indexOf(value) !== -1;
    });
    

  • 使用规则:

    <ValidationProvider rules="one_of:1,2,3,4,5,6,7,8,9" v-slot="{ errors }">
    <input v-model="value" type="text">
    <span>{{ errors[0] }}</span>
    </ValidationProvider>
    

Messages(消息)

• VeeValidate 会给要验证的字段生成错误信息,This field is invalid 是所有规则默认返回的错误信息.
• 修改规则的默认错误信息
  • 通过修改validation function返回值来修改默认错误信息

    import { extend } from 'vee-validate';
    extend('positive', value => {if (value >= 0) {return true;}return 'This field must be a positive number';});
    

  • 通过在options配置项中添加message属性来修改默认信息(常用)

    extend('odd', {validate: value => {return value % 2 !== 0;},message:'This field must be an odd number'
    });
    

• 有时候我们需要在使用规则时再决定错误信息的内容,这时候可以考虑使用vee-validate提供的简单插值语法{_field_}来修改错误信息内容
  • 定义规则:

    extend('odd', {
    validate: value => {return value % 2 !== 0;
    },
    message: 'This {_field_} must be an odd number'
    });
    

  • 使用规则:

    <ValidationProvider name="age" rules="positive" v-slot="{ errors }"><input v-model="value" type="text"><span>{{ errors[0] }}</span>
    </ValidationProvider>
    

    使用name属性插入到{field}中
    如果ValidationProvider中没有指定name属性,vee-validate就会使用其所包裹的元素中的name或id属性作为{_field_}的值
• message可以使用params参数作为占位符placeholders{}的值

  extend('min', {validate(value, { length }) {return value.length >= length;},params: ['length'],message: 'The {_field_} field must have at least {length} characters'
  });
  

• 将message写成函数
  • 第一个参数 fieldName,该参数是ValidationProvider的name属性的值
  • 第二个参数 placeholders,占位符,该参数是一个对象,包含params参数以及_field_,_value_,_rule_其三分别表示 字段名，已验证的字段值，触发此消息的规则名

    extend('minmax', {validate(value, { min, max }) {return value.length >= min && value.length <= max;},params: ['min', 'max'],message: (fieldName, placeholders) => {return `The ${fieldName} field must have at least ${placeholders.min} characters and ${placeholders.max} characters at most`;
    }
    });
    

• 关于mutiple message(多消息)
  • 你可能想知道为什么errors是一个数组而不是一个字符串,这是因为虽然每条规则都只会生成一条message(消息),但一个input也可能同时需要多条规则进行校验,vee-validate就会把所有rules产生的message都存到errors数组中

Available Rules(可用的规则)

• 默认情况下，vee-validate并不会安装这些可用规则,需要自行安装

• Importing The Rules(按需引入)

  • Validation rules(验证规则)都会在vee-validate/dist/rules文件中暴露
    • 定义规则:

      import { extend } from 'vee-validate';
      import { required, email } from 'vee-validate/dist/rules';// No message specified.
      extend('email', email);// Override the default message.
      extend('required', {...required,message: 'This field is required'
      });
      

    • 使用规则:

      <ValidationProvider name="email" rules="required|email" v-slot="{ errors }"><input v-model="email" type="text"><span>{{ errors[0] }}</span>
      </ValidationProvider>
      

• Installing All Rules(安装所有规则) 不推荐

  • import * as rules from 'vee-validate/dist/rules'导入所有规则后,通过Object.keys遍历出所有规则名,最后用extend定义所有vee-validate提供的默认规则

    import { extend } from 'vee-validate';
    import * as rules from 'vee-validate/dist/rules';Object.keys(rules).forEach(rule => {extend(rule, rules[rule]);
    });
    

  • 另一种方法是导入vee-validate的完整包,其包含所有校验规则和英文消息’:
    import { ValidationProvider } from 'vee-validate/dist/vee-validate.full.esm';

• Rules(规则)

  • 各种可用规则的详情校验规则转至Rules
  • 这里仅介绍5个常用的可用规则:

    • regex (验证字段必须匹配正则表达式)

      <ValidationProvider :rules="{ regex: /^[0-9]+$/ }" v-slot="{ errors }"><input type="text" v-model="value"><span>{{ errors[0] }}</span>
      </ValidationProvider>
      

    • between (验证字段必须在一个区间内)

      <ValidationProvider rules="between:1,11" v-slot="{ errors }"><input v-model="value" type="text"><span>{{ errors[0] }}</span>
      </ValidationProvider>
      

    • comfirmed (验证字段必须与确认字段相同)

      <ValidationProvider v-slot="{ errors }" vid="confirmation"><input v-model="confirmation" type="text"><span>{{ errors[0] }}</span>
      </ValidationProvider><ValidationProvider rules="confirmed:confirmation" v-slot="{ errors }"><input v-model="value" type="text"><span>{{ errors[0] }}</span>
      </ValidationProvider>
      

      

    • is (验证下的字段必须匹配给定的值,使用严格的相等)

      <ValidationProvider rules="is:hello" v-slot="{ errors }"><input type="text" v-model="value"><span>{{ errors[0] }}</span>
      </ValidationProvider>
      

    • required (验证的字段必须非空.默认情况下,空字符串、空数组、null、undefinded都属于空值)

      <ValidationProvider rules="required" v-slot="{ errors }"><input type="text" v-model="value"><span>{{ errors[0] }}</span>
      </ValidationProvider>
      

Validation State(校验状态)

• 在之前的示例中,我们只用过slot props中的errors来显示错误消息,但errors其实只是Validation State中的一部分.
• Flags(标记)
  • Validation Flags(校验标记) 是一个boolean值,用于获取校验字段的状态信息,以下是vee-validate官方文档罗列出所有可访问的flags:
    

Handling Forms(处理表单)

• 到这里,我们已经学习了利用ValidationProvider去校验input元素中的字段是否通过某规则,但整体上我们并没有学习如何校验表单元素.

• 对于表单元素form ,我们可以使用ValidationObserver组件去校验表单.

• 我们可以把ValidationProvider组件当作一个单独的field字段,把ValidationObserver当作form表单,那么ValidationObserver就是每个子组件ValidationProvider的聚合器(aggregator)或者说领队(leader),这个聚合器会暴露所有字段的校验状态(Validation State)

• 基本示例

  • 假如你有一个基本的form表单,想在表单其他字段校验通过之前,将提交按钮disable(禁止),你可以使用ValidationObserver中暴露给slot props的Validation State中的invalid标记.

     <ValidationObserver v-slot="{ invalid }"><form @submit.prevent="onSubmit"><ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }"><input v-model="email" type="email"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }"><input v-model="firstName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }"><input v-model="lastName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><button type="submit" :disabled="invalid">Submit</button></form></ValidationObserver>
    

    当所有input元素中的invalid标记都为false时,ValidationObserver的invalid才会为false

• Validate Before Submit(提交前验证)

  • ValidationObserver 提供了handleSubmit函数,这个函数需要我们传入一个回调函数,这个回调会在用户提交有效表单的时候调用.

    <ValidationObserver v-slot="{ handleSubmit }"><!--用户提交有效表单时才会调用onSubmit--><form @submit.prevent="handleSubmit(onSubmit)"><ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }"><input v-model="email" type="email"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }"><input v-model="firstName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }"><input v-model="lastName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><button type="submit">Submit</button></form>
    </ValidationObserver>
    

• Resetting Forms(重置表单)

  • 在成功提交表单后,如果你想重置表单,可以使用ValidationObserver提供的reset函数,该函数会将Validation State校验状态重置到初始状态(包括错误信息errors):

    <!--使用ES6语法从slot props中解构出handlSubmit和reset函数-->
    <ValidationObserver v-slot="{ handleSubmit, reset }"><form @submit.prevent="handleSubmit(onSubmit)" @reset.prevent="reset"><ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }"><input v-model="email" type="email"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }"><input v-model="firstName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }"><input v-model="lastName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><button type="submit">Submit</button><button type="reset">Reset</button></form>
    </ValidationObserver>
    

    使用ValidationObserver提供的reset函数对校验状态进行重置

• Programmatic Access with $refs(使用$refs进行编程式访问,简单来说就是使用vue中的$ref获取Dom元素从而在js中也能访问校验信息)

   <ValidationObserver ref="form"><form @submit.prevent="onSubmit"><ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }"><input v-model="email" type="email"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }"><input v-model="firstName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }"><input v-model="lastName" type="text"><span>{{ errors[0] }}</span></ValidationProvider><button type="submit">Submit</button></form></ValidationObserver><script>export default {data: () => ({firstName: '',lastName: '',email: ''}),methods: {onSubmit () {this.$refs.form.validate().then(success => {if (!success) {return;}alert('Form has been submitted!');// Resetting Valuesthis.firstName = this.lastName = this.email = '';// Wait until the models are updated in the UIthis.$nextTick(() => {this.$refs.form.reset();});});}}};
  </script>
  

  通过$refs获取dom元素,其元素会被注入validate函数,使用函数对form表单进行校验,关于validate函数会在后面API详细说明

• Initial State Validation(初始状态校验)

  • ValidationProvider默认初始状态不会校验字段,可以使用immediate属性在渲染时立刻对字段进行校验:

    <ValidationProvider rules="required" immediate v-slot="{ errors }"><!-- -->
    </ValidationProvider>
    

    渲染时立刻对字段进行校验

• Persisting Provider State(ValidationProvider组件校验状态持久化)

  • 首先我们要知道,ValidationObserver只能监测到当前已经渲染的ValidationProvider的组件实例,任何被v-if隐藏或者v-for移除的Provider会排除在Observer的校验状态之外.简而言之就是不会参与到表单的验证.
  • 如果希望Observer保存已销毁的provider校验状态,比如该表单的填写需要路由跳转时,需要保存provider的校验状态,但我们知道,默认情况下的路由跳转,会销毁路由跳转前的组件导致校验状态丢失,这时候我们就需要用到vue中的keep-alive标签以保证第一次创建provider组件时将组件实例缓存下来.(有关keep-alive)

    <ValidationObserver ref="form"><form @submit.prevent="onSubmit"><!--fieldset是嵌套Observer的写法--><fieldset><legend >Step {{ currentStep }}</legend><keep-alive><ValidationProvider v-if="currentStep === 1" name="email" rules="required|email" v-slot="{ errors }"><input v-model="email" type="text" placeholder="Your email"><span>{{ errors[0] }}</span></ValidationProvider></keep-alive><keep-alive><ValidationProvider v-if="currentStep === 2" name="first name" rules="required" v-slot="{ errors }"><input v-model="fname" type="text" placeholder="Your first name"><span>{{ errors[0] }}</span></ValidationProvider></keep-alive><keep-alive><ValidationProvider v-if="currentStep === 2" name="last name" rules="required" v-slot="{ errors }"><input v-model="lname" type="text" placeholder="Your last name"><span>{{ errors[0] }}</span></ValidationProvider></keep-alive><keep-alive><ValidationProvider v-if="currentStep === 3" name="address" rules="required|min:5" v-slot="{ errors }"><textarea v-model="address" type="text" placeholder="Your address"></textarea><span>{{ errors[0] }}</span></ValidationProvider></keep-alive></fieldset><button type="button" @click="goToStep(currentStep - 1)">Previous</button><button type="button" @click="goToStep(currentStep + 1)">{{ currentStep === 3 ? 'Submit' : 'Next' }}</button></form>
    </ValidationObserver>
    

    使用Keep-alive标签缓存组件,保存provider校验状态
    注意,即使字段被隐藏/卸载，只要它们被keep-alive包裹，它们的状态也会受到validate和reset调用的影响.

Localization(本地化) 常用

• vee-validate 内置了校验信息的支持,本地化配置是可选的,且默认不配置本地化.

• Using the default i18n(使用默认的i18n)

  • vee-validate 配备了小型的i18n词典已应对i18n的基本需求.
  • Adding messages(添加校验消息)
    • vee-validate默认语言是en,首先需要导入localize函数,localize函数需要传入一个配置对象,你可以像这样添加校验消息:

      import { localize } from 'vee-validate';localize({en: {messages: {required: 'this field is required',min: 'this field must have no less than {length} characters',max: (_, { length }) => `this field must have no more than ${length} characters`}}
      });
      

      message对象的Key值是规则的名称,Value值是校验消息的内容,可以是字符串、模板字符串或者消息生成函数

• Installing locales(安装本地化)

  • 本地化资源默认只有en,我们可以按需引入本地化资源,其默认的校验消息也已自动本地化:

    import { localize } from 'vee-validate';
    import en from 'vee-validate/dist/locale/en';
    import zh_CN from 'vee-validate/dist/locale/zh_CN';// Install English and Chinese locales.
    localize({en,zh_CN
    });
    

• Setting the locale(设置本地化环境)

  • 你可以同时激活和添加新校验消息:

    import { localize } from 'vee-validate';
    import zh_CN from 'vee-validate/dist/locale/zh_CN';// Install and Activate the Chinese locale.
    localize('zh_CN', zh_CN);
    

• Localized field names(本地化字段的name属性)

  • 首先我们知道,form表单中,form元素的子元素的name值会在form触发Submit事件中,作为queryString的Key值发往action属性值的地址.
  • 有时候我们希望在表单校验通过后,对name属性值做一个本地化映射,比如name="email"在校验通过后希望映射为name="邮箱"发请求给服务器,这时候我们就需要给locale的配置对象添加names属性进行配置:

    import { localize } from 'vee-validate';localize({zh_CN: {names: {email: '邮箱',}}
    })
    

    如此配置后,当input使用name="email"且校验通过时,就会被vee-validate替换成本地化的name="邮箱"发往服务器

• Custom messages per field(给每个字段自定义校验消息)

  • 我们可以通过给locale对象添加field属性来给每个规则的指定字段提供一个自定义消息:

    import { localize } from 'vee-validate';localize({en: {messages: {// generic rule messages...},fields: {password: {required: 'Password cannot be empty!',max: 'Are you really going to remember that?',min: 'Too few, you want to get doxed?'}}}
    });
    

    修改en环境下的password字段的required、max、min规则的校验消息

• Lazily importing locales(本地化资源懒加载)

  • 利用ES2020的动态导入语法import(),实现资源的懒加载:

    import { localize } from 'vee-validate';function loadLocale(code) {return import(`vee-validate/dist/locale/${code}.json`).then(locale => {localize(code, locale);});
    }
    

    import()会返回一个promise对象,我们可以指定回调实现注册本地化资源的功能,当我们执行loadLocale()时才会加载本地化资源模块

Interaction and UX(交互和用户体验)

• vee-validate对于何时进行校验有多种策略,最常见的有以下四种:

  • Aggressive : 当用户在input框中一输入值就触发校验.
  • Passive : 当表单提交时才触发校验.
  • Lazy : 当input框失去焦点或者改变焦点时触发校验.
  • Eager : 该策略结合了Aggressive和Lazy.当input框失去焦点时会触发第一次校验,第一次校验如果不通过后续校验就会表现出Aggressive策略,直到校验合法了才会表现出Lazy策略.

• Interaction Modes(交互模式)

  • vee-validate 提供了多种常见的校验策略,我们称这些校验策略称之为interaction modes(交互模式).
  • Setting The Interaction Mode Globally(设置全局交互模式)

    import { setInteractionMode } from 'vee-validate';setInteractionMode('lazy');
    

  • Setting The Interaction Mode Per Component(设置单个组件的交互模式)

    <ValidationProvider mode="lazy" rules="required" v-slot="{ errors }"><!-- Some input -->
    </ValidationProvider>
    

    使用mode属性将交互模式设置为lazy模式
    至此,你已经掌握了vee-validate的基本使用方法,如果你想了解更多关于vee-validate的知识,务必阅读以下对核心API的介绍以及查阅vee-validate官方文档

Core Validation API(核心校验API)

The Validate Function

• 你可以从vee-validate中导入validate函数,用ValidationProvider相同的方式直接对字段进行校验:

  import { validate } from 'vee-validate';validate('somval', 'required|min:3').then(result => {if (result.valid) {// Do something}
  });
  

  validate函数继承Promise类,且该函数会返回一个关于校验结果的对象

• validate的函数签名大概如下:

  interface Result {valid: boolean;errors: string[];failedRules: {[x: string]: string;};
  }interface validate {(value: any, rules: string | Record<string, any>,  options?: ValidationOptions): Result;
  }
  

  • 可以看到result对象接口中有三个常用属性值:

    • valid : 校验通过为true,否则为falsa
    • errors : 校验失败时的错误消息列表
    • failedRules : 校验失败对象,其中key为规则名,value为错误消息

  • validation(rules,value,options?),该函数需要传入三个参数:

    • value : 要校验的值
    • rules : 校验规则
    • options : ValidationOptions配置项

• Validation Options(校验配置项)

  • ValidationOption接口如下:

    interface ValidationOptions {name?: string;values?: { [k: string]: any };names?: { [k: string]: string };bails?: boolean;skipOptional:? boolean;isInitial?: boolean;customMessages?: { [k: string]: string };
    }
    

  • Property	Type	Description
    name	string	要校验的字段名
    values	[x: string]: string	其他字段的值(用于跨域校验)
    names	{ { [k: string]: string }	其他字段名(用于跨域校验)
    bails	boolean	如果为true,校验将会在第一个校验失败的规则停下(用于多规则校验)
    skipOptional	boolean	如果为true,当值为空时,会跳过可选字段的校验
    isInitial	boolean	如果为true,会在第一次尝试校验时,跳过所有规则
    customMessages	{ [k: string]: string }	自定义错误消息,key是规则名

• 如果你只需要简单的校验,可以直接使用validate函数:

  let password = 'my password';
  let confirmation = '????';validate(password, 'required|confirmed:@confirmation', {name: 'Password',values: {confirmation}
  }).then(result => {if (result.valid) {// Do something!}
  });