VeeValidate 中文文档-API

  1. 本篇总结 API
  2. v-validate directive
  3. v-validate 指令是验证我们的 inputs 输入框的主要方式,该指令接受一个字符串或对象作为值。
  4. 如果传递了一个字符串,它必须是一个有效的 rules 字符串,由 '|' 分隔的验证规则。
  5. <input v-validate="'required|email'" name="field" type="text">
  6. 如果传递了一个对象,它必须包含要使用的 rules 的属性,rules 的值是数组格式的参数或单个值参数(如果规则接收单个参数)。
  7. // 字符串
  8. const expression = 'required|regex:^[0-9]+';
  9. const expression = {
  10. // 无参数的规则使用 boolean
  11. required: true,
  12. // 单个参数的规则使用单个值
  13. regex: /.(js|ts)$/,
  14. // 多个参数的规则使用数组
  15. in: [1, 2, 3]
  16. };
  17. 指令参数
  18. 指令还接受一个 arg,表示要验证的 vue model 的名称,或计算属性。
  19. <input v-model="email" v-validate:email="'required|email'" name="field" type="text">
  20. export default {
  21. data: () => ({
  22. email: ''
  23. })
  24. };
  25. 然而,arg 完全是可选的。此外,v-validate 检查 input 输入框/组件 是否分配了 v-model,并将 v-model 表达式视为 arg。但请记住,arg 必须是一个简单的 dot notation string(点符号字符串),并且它必须存在于 vue 实例上。
  26. PS:
  27. dot notation string 查看了下,就是可以使用 '点语法' 的字符串,例如:'String'.upper()
  28. 提示:
  29. 你可能会问什么时候使用 arg?前提是可以检测到 v-model。一个有效的情况是当我们需要验证计算属性时,就需要使用 arg。
  30. 指令修饰符
  31. immediate
  32. 我们可以使用 .immediate 修饰符,在页面加载后立即验证字段。
  33. <template>
  34. <input v-model="email" v-validate.immediate="'required|email'" name="field" type="text">
  35. </template>
  36. <script>
  37. export default {
  38. data: () => ({
  39. email: ''
  40. })
  41. };
  42. </script>
  43. continues
  44. 默认情况下,vee-validate 在验证字段规则时,使用 fastExit 策略。意味着当第一个规则验证失败时,它将停止,且不会验证其余规则。我们可以使用 .continues 修饰符,来强制验证所有规则,而不管这些规则的验证结果。
  45. 下面的代码段使用 .continues 修饰符,来显示字段的所有错误,这是一种常见的 UI 实践。
  46. <template>
  47. <div>
  48. <input v-model="email" v-validate.continues="'required|email'" name="field" type="text">
  49. <ul>
  50. <li v-for="error in errors.collect('field')">{{ error }}</li>
  51. </ul>
  52. </div>
  53. </template>
  54. <script>
  55. export default {
  56. data: () => ({
  57. email: ''
  58. })
  59. };
  60. </script>
  61. 我们可以配置 fastExit 选项为 false,来对所有字段启用 '.continues' 修饰符的行为。
  62. 提示:
  63. .continues 修饰符还有另一个用途,它禁用了 required 规则的检查,意味着,没有 required 规则但是值为空的字段,将不会被跳过。因此,确保我们的自定义规则也能够处理空值。
  64. bails
  65. 反过来,如果我们已经配置了 fastExit 为 false,那么我们可以在特定字段上使用 .bail,在第一次验证失败后停止对其他规则的验证。
  66. <template>
  67. <div>
  68. <input v-model="email" v-validate.bails="'required|email'" name="field" type="text">
  69. <span>{{ errors.first('email') }}</span>
  70. </div>
  71. </template>
  72. <script>
  73. export default {
  74. data: () => ({
  75. email: ''
  76. })
  77. };
  78. </script>
  79. Mixin
  80. VeeValidate 注入了一个混入(mixin),通过以下属性来增强我们的 Vue 实例:
  81. $validator - 一个 Validator 实例
  82. errors - 一个 ErrorBag 实例
  83. fields - 一个包含了所有已验证字段的状态标志的对象
  84. 提示:
  85. 我们可以设置 inject 配置选项为 false,来选择不自动在我们的实例中注入这些属性,但是我们将需要自己管理,提供 $validator 实例,来保证指令正常工作,参阅 '组件注入' 章节。
  86. data-* Attributes
  87. data-* 属性为插件提供了一个可选的接口,用来指定应该发生什么,提供了一个简单的、Vue 版本兼容的 API。如果我们不喜欢将复杂的表达式传递给指令,它们将非常有用。
  88. 属性 - 描述
  89. data-vv-as - 为字段指定一个漂亮的名称
  90. data-vv-delay - 为触发验证指定的延迟时间(单位是毫秒)
  91. data-vv-name - 为字段指定一个名称,用于组件验证并作为 inputs 输入框的回退名称
  92. data-vv-scope - 为字段指定一个作用域。
  93. data-vv-value-path - 指定组件 $data 中的 value 路径,用于检索组件当前值。仅用于组件。
  94. data-vv-validate-on - 用于指定由 '|' 分隔的事件名称列表, 默认值因 inputs 输入框类型而异。
  95. ErrorBag
  96. ErrorBag 类是一个数组包装器,是一个集合对象(估计和 Laravel 一样),它是独立的、没有任何依赖关系,我们可以在代码中任意使用它:
  97. import { ErrorBag } from 'vee-validate';
  98. const bag = new ErrorBag();
  99. // 例如,我们可能想要添加一个验证相关的错误
  100. bag.add({
  101. field: 'auth',
  102. msg: 'Wrong Credentials'
  103. });
  104. // 像这样显示它
  105. bag.first('auth');
  106. 单个错误对象如下所示:
  107. const error = {
  108. field: 'Field name',
  109. msg: 'Error message',
  110. rule: 'Rule Name', // optional
  111. scope: 'Scope Name', // optional
  112. regenerate: () => 'some string', // optional
  113. id: 'uniqueId' // optional
  114. };
  115. API
  116. 方法 - 返回值 - 描述
  117. add(error: ErrorObject) - void - 将错误添加到错误包中, 错误对象必须符合上面提到的对象结构
  118. all(scope ?: string) - Array - 获取数组中的所有错误消息, 可以指定一个作用域,将检索该作用域内的所有消息
  119. any(scope ?: string) - boolean - 检查是否存在任何错误, 可以指定一个作用域,将检查该作用域内是否存在任何错误
  120. clear(scope ?: string) - void - 清除所有错误,可以指定一个作用域,将只会清除该作用域内的所有错误
  121. collect(field ?: string, scope ?: string, mapped ?: boolean) - Array|Object - 收集指定字段关联的错误。不传递字段名,将会按字段名对所有错误进行分组。指定一个作用域,将收集行为限制在该作用域内。我们可以选择性地指定是否将错误对象映射到错误消息,提供 false 则返回一个 '包含了有关错误的完整信息' 的对象。
  122. count() - number - 返回集合中当前的错误个数
  123. first(field: string, scope ?: string) - string|null - 返回与特定字段关联或由选择器指定的第一条错误消息,可以指定一个作用域,将会在该作用域内查找错误。
  124. firstById(id: string) - string|null - 返回给定 ID 的字段的第一条错误消息
  125. firstByRule(field: string, rule: string, scope ?: string) - string|null - 返回与指定字段和规则关联的第一条错误消息,指定一个作用域,将会在该作用域内查找错误
  126. has(field: string, scope ?: string) - boolean - 检查是否存在,与特定字段关联或由选择器指定的错误消息,可以指定一个作用域,将会在该作用域内查找错误。
  127. remove(field: string, scope ?: string) - void - 移除与特定字段关联的所有错误,可以指定一个作用域,将只会移除该字段和该作用域的消息。
  128. removeById(id: string) - void - 删除与提供的 ID 匹配的字段。
  129. update(id: string, diff ?: ErrorObject) - void - 更新指定字段的错误消息数据,在内部使用这些数据,来保持字段错误作用域的最新。
  130. Field
  131. VeeValidate 将要验证的 HTML 元素和 Vue 组件,映射为 fields 实例,虽然这个类没有被公开使用,但我们可以发现,如果计划执行一些更底层的操作,它的 API 非常有用。
  132. 警告:
  133. 任何未记录的属性/方法都不应用于公共用途。
  134. 获取字段实例
  135. 获取字段实例非常简单,我们可以使用 Validator.fields.find 方法获取字段实例。
  136. // 查找匹配到 "email" 名称的字段
  137. const field = this.$validator.fields.find({ name: 'email' }));
  138. // 查找匹配到 'email' 名称、且在 'newsletter' 作用域下的字段
  139. const field = this.$validator.fields.find({ name: 'email', scope: 'newsletter' });
  140. // 或者使用 id 来查找字段,如果它是你知道的
  141. const field = this.$validator.fields.find({ id: 'fieldId' });
  142. API
  143. 警告:
  144. 使用字段 API 时要小心,因为它可能会中断验证器操作,并可能产生意外的结果。
  145. 构造器
  146. 属性
  147. 名称 - 类型 - 默认值 - 描述
  148. id - string - null - 字段 ID(自动生成)
  149. el - HTMLElement - null - 要验证的 HTML inputs 输入框元素或组件根元素
  150. updated - boolean - false - 表示是否应重新扫描字段以更新其属性(例如:验证规则)。
  151. watchers - Watcher[] - [] - 字段实例正在使用的事件监听包装器数组
  152. events - string[] - [] - 触发验证的事件列表
  153. rules - { [string]: Object } - {} - 用来验证字段的规则/参数映射对象
  154. validity - boolean - false - 是否应使用 HTML Constrained API 来应用错误消息
  155. aria - boolean - true - 验证后是否应设置/更新 aria-required 和 aria-invalid 属性
  156. vm - Vue instance - null - 在其模板中使用指令的上下文组件
  157. components - Vue instance - null - 正在验证的组件(如果它是一个组件)
  158. ctorConfig - VeeValidateConfig - null - 字段的作用域配置
  159. flags - { [string]: Object } - {} - 字段当前标志状态的字符串/布尔映射
  160. alias - string - null - 字段的别名,是一个只读的属性
  161. getter - () => any - null - 返回当前字段值的 getter 函数
  162. name - string - null - 字段名
  163. scope - string - null - 字段作用域
  164. targetOf - string - null - 有些字段,是根据目标字母的值来进行验证的,这里表示的是目标字段的 ID(confirmed|before|after 验证规则,都需要目标字段)
  165. initial - boolean - false - 字段是否应该在创建后就进行验证
  166. classes - boolean - false - 是否应在 HTML input 输入框应用基于标志的类
  167. classNames - Object - {} - 一个基于标志应用的、包含了标志名称/类名称的映射
  168. delay - number - 0 - 用于该字段事件触发器的延迟秒数
  169. listen - boolean - true - 是否该字段应该有监听器
  170. model - { expression: string, lazy: boolean } - null - 包含了使用 v-model 绑定到该字段的模型的相关信息
  171. value - any - () => undefined - getter 属性的只读版本
  172. isRequired - boolean - true|false - 字段是否是 required(是否设置了 required 规则)
  173. isDisabled - boolean - true|false - 字段是否是 disabled(如果是 disabled,则跳过验证)
  174. validator - Validator - null - 创建了该字段的认证实例的只读引用
  175. rejectsFalse - boolean - false - 如果设置为 false,则 required 规则无效
  176. 方法
  177. 名称 - 返回类型 - 描述
  178. matches(options: FieldMatchOptions) - boolean -
  179. update(options: FieldOptions) - void - 更新字段属性,并重新添加监听器,以及同步应用的类
  180. reset() - void - 将字段标志重置到它们的初始状态
  181. setFlags(flags: { [string]: boolean }) - void - 更新字段标志,也更新指定的字段对应项,例如:valid/invalid。
  182. unwatch(tag ?: RegExp) - void - 删除匹配到的监听器,如果没有传递参数,则删除所有的监听器
  183. updateClasses() - void - 如果启用,则使用标志将应用于元素上的类同步(应该是上面的 classes 设置为 true)
  184. updateAriaAttrs() - void - 如果启用,则使用标志将应用于元素上的 aria 属性同步(应该是上面的 aria 设置为 true)
  185. updateCustomValidity() - void - 将受约束的 API 验证消息与字段的第一条错误消息同步
  186. destroy() - void - 删除字段所有的监听器和依赖
  187. Validator API
  188. 验证器提供了一个 API 来添加新字段和触发验证。
  189. API
  190. 属性
  191. 名称 - 类型 - 描述
  192. errors - ErrorBag - ErrorBag 类实例,用来管理错误
  193. fields - FieldBag - FieldBag 类实例,用来管理字段
  194. locale - string - 当前使用的语言设置
  195. 方法
  196. 名称 - 返回类型 - 描述
  197. attach(field: FieldOptions) - Field - 将一个新字段附加到验证器上
  198. validate(descriptor ?: String, value ?: any, options ?: Object) - Promise<boolean> - 验证提供的 'descriptor' 参数值匹配到的字段。当验证结束,Promise 返回一个布尔值,表示验证的字段是否有效
  199. validateAll(fields ?: String or Object) - Promise<boolean> - 根据相应的字段验证规则,验证每个值
  200. pause() - void - 禁用认证
  201. resume() - void - 启用认证
  202. verify(value: any, rules: string) - Object - { errors: string[], valid: boolean}
  203. detach(name: string, scope ?: string) - void - 将匹配到的字段(通过 name 和 scope 提供的值进行匹配)从验证器上分离
  204. extend(name: string, rule: Rule, options ?: ExtendOptions) - void - 添加一个新的验证规则。提供的规则参数必须是一个有效的 Rule 函数或对象
  205. reset(matcher ?: Object) - void - 重置所有作用域字段的字段标志。如果未提供作用域,则重置所有字段。
  206. 作用域的 reset() 使用
  207. let matcher = {
  208. scope: 'form-1',
  209. vmId: this.$validator.id
  210. }
  211. this.$validator.reset(matcher);
  212. 验证 API
  213. validate 方法是触发验证的主要方法,所有参数都是可选的,但是根据我们提供的参数不同,会产生不同的结果。
  214. 字段描述符(descriptor)
  215. 字段描述符是一个字符串, 可以具有以下形式:
  216. // 验证所有字段
  217. validator.validate();
  218. // 验证一个 'name 与提供的选择器相匹配' 的字段
  219. validator.validate('field');
  220. // 验证作用域内的某个字段
  221. validator.validate('scope.field');
  222. // 验证作用域内的所有字段
  223. validator.validate('scope.*');
  224. // 验证没有作用域的所有字段
  225. validator.validate('*');
  226. 值(value)
  227. value 参数是可选的,如果没有给 validate() 方法传递 value,validate() 方法将尝试使用内部的值解析算法来解析 value。当传递了 value,则会跳过该算法,并使用该 value 来替代。
  228. 验证选项(validation options)
  229. 我们可以传递选项来修改验证行为,这些选项是一个可以包含以下内容的对象:
  230. 属性 - 类型 - 默认值 - 描述
  231. silent - Boolean - false - 如果设置为 true,validate() 方法将返回验证结果,而不修改错误和标志。
  232. initial - Boolean - false - 如果设置为 true,在此调用期间,将跳过标记为 non-immediate 的规则,用于防止初始验证触发后端调用
  233. Verify
  234. Validator.verify() 方法根据指定的规则验证某个值,允许我们在代码中,编程式地使用 validator,而无需使用 v-validate 指令注册字段。如果我们想要验证值而不是 inputs 输入框字段时,这非常有用,例如,在 Vuex 的 action 中使用:
  235. import { Validator } from 'vee-validate';
  236. const v = new Validator();
  237. const { valid, errors } = await v.verify('test', 'max:3');
  238. // valid 属性表示验证的结果
  239. console.log(valid); // false
  240. // errors 是一个错误字符串数组
  241. console.log(errors); // ["The {field} field may not be greater than 3 characters."]
  242. 提示:
  243. 注意,返回的消息中的 {field} 代表验证的字段名,如果我们需要,我们可以轻松替换它。
  244. Verify Options
  245. verify() 接收第三个参数,用于配置验证和消息
  246. v.verify(value, rules, opts);
  247. 属性 - 类型 - 默认值 - 描述
  248. name - string - {field} - 一个字符串, 表示错误消息中使用的字段名称。
  249. bails - boolean - true - 如果为 true,第一次验证失败后,停止之后的验证
  250. values - object - {} - 一个对象,映射了跨字段规则所需的其他字段的值
  251. Cross-Field Rules
  252. 也可以使用目标依赖规则,我们需要在第三个参数中传递 values 对象,对象的键是 '目标字段' 的名称,对象的值是 '目标字段的值'
  253. v.verify('pass', 'confirmed:conf', {
  254. values: {
  255. // 目标字段
  256. conf: 'p@$$'
  257. }
  258. });

 

出处:https://blog.csdn.net/beyond__devil/article/details/84956923
posted @ 2021-02-08 21:48  十点书屋  阅读(1117)  评论(0)    收藏  举报