VeeValidate 中文文档-API

本篇总结 API

v-validate directive
	v-validate 指令是验证我们的 inputs 输入框的主要方式，该指令接受一个字符串或对象作为值。

	如果传递了一个字符串，它必须是一个有效的 rules 字符串，由 '|' 分隔的验证规则。

		

	如果传递了一个对象，它必须包含要使用的 rules 的属性，rules 的值是数组格式的参数或单个值参数(如果规则接收单个参数)。

		// 字符串
		const expression = 'required|regex:^[0-9]+';

		const expression = {
		  // 无参数的规则使用 boolean
		  required: true,
		  // 单个参数的规则使用单个值
		  regex: /.(js|ts)$/,
		  // 多个参数的规则使用数组
		  in: [1, 2, 3]
		};

	指令参数
		指令还接受一个 arg，表示要验证的 vue model 的名称，或计算属性。

			

			export default {
				data: () => ({
				    email: ''
				})
			};

		然而，arg 完全是可选的。此外，v-validate 检查 input 输入框/组件 是否分配了 v-model，并将 v-model 表达式视为 arg。但请记住，arg 必须是一个简单的 dot notation string(点符号字符串)，并且它必须存在于 vue 实例上。

		PS：
			dot notation string 查看了下，就是可以使用 '点语法' 的字符串，例如：'String'.upper()

		提示：
			你可能会问什么时候使用 arg？前提是可以检测到 v-model。一个有效的情况是当我们需要验证计算属性时，就需要使用 arg。

	指令修饰符
		immediate
			我们可以使用 .immediate 修饰符，在页面加载后立即验证字段。

				

				

		continues
			默认情况下，vee-validate 在验证字段规则时，使用 fastExit 策略。意味着当第一个规则验证失败时，它将停止，且不会验证其余规则。我们可以使用 .continues 修饰符，来强制验证所有规则，而不管这些规则的验证结果。

			下面的代码段使用 .continues 修饰符，来显示字段的所有错误，这是一种常见的 UI 实践。

				

				

			我们可以配置 fastExit 选项为 false，来对所有字段启用 '.continues' 修饰符的行为。

			提示：
				.continues 修饰符还有另一个用途，它禁用了 required 规则的检查，意味着，没有 required 规则但是值为空的字段，将不会被跳过。因此，确保我们的自定义规则也能够处理空值。

		bails
			反过来，如果我们已经配置了 fastExit 为 false，那么我们可以在特定字段上使用 .bail，在第一次验证失败后停止对其他规则的验证。

				

				

Mixin
	VeeValidate 注入了一个混入(mixin)，通过以下属性来增强我们的 Vue 实例：
		$validator - 一个 Validator 实例
		errors - 一个 ErrorBag 实例
		fields - 一个包含了所有已验证字段的状态标志的对象

	提示：
		我们可以设置 inject 配置选项为 false，来选择不自动在我们的实例中注入这些属性，但是我们将需要自己管理，提供 $validator 实例，来保证指令正常工作，参阅 '组件注入' 章节。

data-* Attributes
	data-* 属性为插件提供了一个可选的接口，用来指定应该发生什么，提供了一个简单的、Vue 版本兼容的 API。如果我们不喜欢将复杂的表达式传递给指令，它们将非常有用。

		属性 - 描述
		data-vv-as - 为字段指定一个漂亮的名称
		data-vv-delay - 为触发验证指定的延迟时间(单位是毫秒)
		data-vv-name - 为字段指定一个名称，用于组件验证并作为 inputs 输入框的回退名称
		data-vv-scope - 为字段指定一个作用域。
		data-vv-value-path - 指定组件 $data 中的 value 路径，用于检索组件当前值。仅用于组件。
		data-vv-validate-on - 用于指定由 '|' 分隔的事件名称列表, 默认值因 inputs 输入框类型而异。

ErrorBag
	ErrorBag 类是一个数组包装器，是一个集合对象(估计和 Laravel 一样)，它是独立的、没有任何依赖关系，我们可以在代码中任意使用它:

		import { ErrorBag } from 'vee-validate';

		const bag = new ErrorBag();

		// 例如，我们可能想要添加一个验证相关的错误
		bag.add({
		  	field: 'auth',
		  	msg: 'Wrong Credentials'
		});

		// 像这样显示它
		bag.first('auth');

	单个错误对象如下所示：

		const error = {
			field: 'Field name',
			msg: 'Error message',
			rule: 'Rule Name', // optional
			scope: 'Scope Name', // optional
			regenerate: () => 'some string', // optional
			id: 'uniqueId' // optional
		};

	API
		方法 - 返回值 - 描述
		add(error: ErrorObject) - void - 将错误添加到错误包中, 错误对象必须符合上面提到的对象结构

		all(scope ?: string) - Array - 获取数组中的所有错误消息, 可以指定一个作用域，将检索该作用域内的所有消息

		any(scope ?: string) - boolean - 检查是否存在任何错误, 可以指定一个作用域，将检查该作用域内是否存在任何错误

		clear(scope ?: string) - void - 清除所有错误，可以指定一个作用域，将只会清除该作用域内的所有错误

		collect(field ?: string, scope ?: string, mapped ?: boolean) - Array|Object - 收集指定字段关联的错误。不传递字段名，将会按字段名对所有错误进行分组。指定一个作用域，将收集行为限制在该作用域内。我们可以选择性地指定是否将错误对象映射到错误消息，提供 false 则返回一个 '包含了有关错误的完整信息' 的对象。

		count() - number - 返回集合中当前的错误个数

		first(field: string, scope ?: string) - string|null - 返回与特定字段关联或由选择器指定的第一条错误消息，可以指定一个作用域，将会在该作用域内查找错误。

		firstById(id: string) - string|null - 返回给定 ID 的字段的第一条错误消息

		firstByRule(field: string, rule: string, scope ?: string) - string|null - 返回与指定字段和规则关联的第一条错误消息，指定一个作用域，将会在该作用域内查找错误

		has(field: string, scope ?: string) - boolean - 检查是否存在，与特定字段关联或由选择器指定的错误消息，可以指定一个作用域，将会在该作用域内查找错误。

		remove(field: string, scope ?: string) - void - 移除与特定字段关联的所有错误，可以指定一个作用域，将只会移除该字段和该作用域的消息。

		removeById(id: string) - void - 删除与提供的 ID 匹配的字段。

		update(id: string,  diff ?: ErrorObject) - void - 更新指定字段的错误消息数据，在内部使用这些数据，来保持字段错误作用域的最新。

Field
	VeeValidate 将要验证的 HTML 元素和 Vue 组件，映射为 fields 实例，虽然这个类没有被公开使用，但我们可以发现，如果计划执行一些更底层的操作，它的 API 非常有用。

	警告：
		任何未记录的属性/方法都不应用于公共用途。

	获取字段实例
		获取字段实例非常简单，我们可以使用 Validator.fields.find 方法获取字段实例。

			// 查找匹配到 "email" 名称的字段
			const field = this.$validator.fields.find({ name: 'email' }));

			// 查找匹配到 'email' 名称、且在 'newsletter' 作用域下的字段
			const field = this.$validator.fields.find({ name: 'email', scope: 'newsletter' });

			// 或者使用 id 来查找字段，如果它是你知道的
			const field = this.$validator.fields.find({ id: 'fieldId' });

	API
		警告：
			使用字段 API 时要小心，因为它可能会中断验证器操作，并可能产生意外的结果。

		构造器

		属性
			名称 - 类型 - 默认值 - 描述
			id - string - null - 字段 ID(自动生成)
			el - HTMLElement - null - 要验证的 HTML inputs 输入框元素或组件根元素
			updated - boolean - false - 表示是否应重新扫描字段以更新其属性(例如：验证规则)。
			watchers - Watcher[] - [] - 字段实例正在使用的事件监听包装器数组
			events - string[] - [] - 触发验证的事件列表
			rules - { [string]: Object } - {} - 用来验证字段的规则/参数映射对象
			validity - boolean - false - 是否应使用 HTML Constrained API 来应用错误消息
			aria - boolean - true - 验证后是否应设置/更新 aria-required 和 aria-invalid 属性
			vm - Vue instance - null - 在其模板中使用指令的上下文组件
			components - Vue instance - null - 正在验证的组件(如果它是一个组件)
			ctorConfig - VeeValidateConfig  - null - 字段的作用域配置
			flags - { [string]: Object } - {} - 字段当前标志状态的字符串/布尔映射
			alias - string - null - 字段的别名，是一个只读的属性
			getter - () => any - null - 返回当前字段值的 getter 函数
			name - string - null - 字段名
			scope - string - null - 字段作用域
			targetOf - string - null - 有些字段，是根据目标字母的值来进行验证的，这里表示的是目标字段的 ID(confirmed|before|after 验证规则，都需要目标字段)
			initial - boolean - false - 字段是否应该在创建后就进行验证
			classes - boolean - false - 是否应在 HTML input 输入框应用基于标志的类
			classNames - Object - {} - 一个基于标志应用的、包含了标志名称/类名称的映射
			delay - number - 0 - 用于该字段事件触发器的延迟秒数
			listen - boolean - true - 是否该字段应该有监听器
			model - { expression: string, lazy: boolean } - null - 包含了使用 v-model 绑定到该字段的模型的相关信息
			value - any - () => undefined - getter 属性的只读版本
			isRequired - boolean - true|false - 字段是否是 required(是否设置了 required 规则)
			isDisabled - boolean - true|false - 字段是否是 disabled(如果是 disabled，则跳过验证)
			validator - Validator - null - 创建了该字段的认证实例的只读引用
			rejectsFalse - boolean - false - 如果设置为 false，则 required 规则无效

		方法
			名称 - 返回类型 - 描述
			matches(options: FieldMatchOptions) - boolean - 
			update(options: FieldOptions) - void - 更新字段属性，并重新添加监听器，以及同步应用的类
			reset() - void - 将字段标志重置到它们的初始状态
			setFlags(flags: { [string]: boolean }) - void - 更新字段标志，也更新指定的字段对应项，例如：valid/invalid。
			unwatch(tag ?: RegExp) - void - 删除匹配到的监听器，如果没有传递参数，则删除所有的监听器
			updateClasses() - void - 如果启用，则使用标志将应用于元素上的类同步(应该是上面的 classes 设置为 true)
			updateAriaAttrs() - void - 如果启用，则使用标志将应用于元素上的 aria 属性同步(应该是上面的 aria 设置为 true)
			updateCustomValidity() - void - 将受约束的 API 验证消息与字段的第一条错误消息同步
			destroy() - void - 删除字段所有的监听器和依赖

Validator API
	验证器提供了一个 API 来添加新字段和触发验证。

	API
		属性
			名称 - 类型 - 描述
			errors - ErrorBag - ErrorBag 类实例，用来管理错误
			fields - FieldBag - FieldBag 类实例，用来管理字段
			locale - string - 当前使用的语言设置

		方法
			名称 - 返回类型 - 描述
			attach(field: FieldOptions) - Field - 将一个新字段附加到验证器上

			validate(descriptor ?: String, value ?: any, options ?: Object) - Promise - 验证提供的 'descriptor' 参数值匹配到的字段。当验证结束，Promise 返回一个布尔值，表示验证的字段是否有效

			validateAll(fields ?: String or Object) - Promise - 根据相应的字段验证规则，验证每个值

			pause() - void - 禁用认证

			resume() - void - 启用认证

			verify(value: any, rules: string) - Object - { errors: string[], valid: boolean}

			detach(name: string, scope ?: string) - void - 将匹配到的字段(通过 name 和 scope 提供的值进行匹配)从验证器上分离

			extend(name: string, rule: Rule, options ?: ExtendOptions) - void - 添加一个新的验证规则。提供的规则参数必须是一个有效的 Rule 函数或对象

			reset(matcher ?: Object) - void - 重置所有作用域字段的字段标志。如果未提供作用域，则重置所有字段。

			作用域的 reset() 使用
				let matcher = {
				    scope: 'form-1',
				    vmId: this.$validator.id
				}

				this.$validator.reset(matcher);

		验证 API
			validate 方法是触发验证的主要方法，所有参数都是可选的，但是根据我们提供的参数不同，会产生不同的结果。

			字段描述符(descriptor)
				字段描述符是一个字符串, 可以具有以下形式:

					// 验证所有字段
					validator.validate();

					// 验证一个 'name 与提供的选择器相匹配' 的字段
					validator.validate('field');

					// 验证作用域内的某个字段
					validator.validate('scope.field');

					// 验证作用域内的所有字段
					validator.validate('scope.*');

					// 验证没有作用域的所有字段
					validator.validate('*');

			值(value)
				value 参数是可选的，如果没有给 validate() 方法传递 value，validate() 方法将尝试使用内部的值解析算法来解析 value。当传递了 value，则会跳过该算法，并使用该 value 来替代。

			验证选项(validation options)
				我们可以传递选项来修改验证行为，这些选项是一个可以包含以下内容的对象：

					属性 - 类型 - 默认值 - 描述
					silent - Boolean - false - 如果设置为 true，validate() 方法将返回验证结果，而不修改错误和标志。

					initial - Boolean - false - 如果设置为 true，在此调用期间，将跳过标记为 non-immediate 的规则，用于防止初始验证触发后端调用

		Verify
			Validator.verify() 方法根据指定的规则验证某个值，允许我们在代码中，编程式地使用 validator，而无需使用 v-validate 指令注册字段。如果我们想要验证值而不是 inputs 输入框字段时，这非常有用，例如，在 Vuex 的 action 中使用：

				import { Validator } from 'vee-validate';

				const v = new Validator();
				const { valid, errors } = await v.verify('test', 'max:3');

				// valid 属性表示验证的结果
				console.log(valid); // false

				// errors 是一个错误字符串数组
				console.log(errors); // ["The {field} field may not be greater than 3 characters."]

				提示：
					注意，返回的消息中的 {field} 代表验证的字段名，如果我们需要，我们可以轻松替换它。

			Verify Options
				verify() 接收第三个参数，用于配置验证和消息

					v.verify(value, rules, opts);

				属性 - 类型 - 默认值 - 描述
				name - string - {field} - 一个字符串, 表示错误消息中使用的字段名称。
				bails - boolean - true - 如果为 true，第一次验证失败后，停止之后的验证
				values - object - {} - 一个对象，映射了跨字段规则所需的其他字段的值

			Cross-Field Rules
				也可以使用目标依赖规则，我们需要在第三个参数中传递 values 对象，对象的键是 '目标字段' 的名称，对象的值是 '目标字段的值'

					v.verify('pass', 'confirmed:conf', {
					  	values: {
					    	// 目标字段
					    	conf: 'p@$$'
					  	}
					});