表单验证

Validator 是表单校验模块，它只负责读取表单字段、执行规则校验、写入失败状态和错误提示节点。

示例

导入

JavaScript
import { createValidator } from 'vanilla-jui';

基础用法

使用 createValidator 创建 Validator 实例：

JavaScript
const validator = createValidator(form, {  rules: {    email: { required: true, email: true },    password: { required: true, minLength: 6 },    plan: { selected: true },  },  messages: {    email: { required: 'Email required', email: 'Invalid email' },    password: { minLength: 'Password too short' },    plan: { selected: 'Plan required' },  },  vanilla: false,  onSubmit: (validator) => {    console.log(validator.runtime.valid);  },});

参数

createValidator(element, props, bindEvents)

element

第一个参数 element 必须可解析为 HTMLFormElement，否则会抛出错误。

props

第二个参数 props 是校验配置对象，包含校验规则、错误提示等。

• vanilla: false 是默认行为，会把表单的 noValidate 设置为 true。即使字段上渲染了 required、type="email" 等原生约束，也不会触发浏览器原生校验气泡；提交时只执行 Validator 自己的 rules。
• 需要启用浏览器原生表单验证能力时，设置 vanilla: true。将自动跳过 rules 自身的校验规则。
• destroy() 会恢复创建实例前的 noValidate 状态。

bindEvents

第三个参数 bindEvents 为 Boolean 类型，默认值为 false。

• false: 用户需手动调用 validate 方法进行校验。优点：自定义验证交互，如“通过 toast 等其他交互提示错误”。
• true: 自动绑定表单的 submit 和 reset 事件，submit 会阻止默认提交并自动执行 validate() 验证方法。

实例属性

destroy() 后，element 和 props 都会变为 null，事件监听和校验提示会被清理。

实例方法

validate()

执行表单校验，并返回是否通过。只会校验有 name 且在 props.rules 中配置了规则的字段。所有字段通过后会调用 props.onSubmit(validator)。

JavaScript
if (validator.validate()) {  // passed}

reset(options)

重置校验状态。

JavaScript
validator.reset();validator.reset({ native: false });

destroy()

销毁 Validator 实例：解绑事件、清理校验提示、释放表单引用，并将实例标记为 destroyed。

JavaScript
validator.destroy();

内置规则

文本字段

Select

Radio

Validator 当前没有 radio 专用内置规则。需要校验 radio 分组时，可以使用 validate 自定义规则读取同名 radio 的选中状态。

Checkbox

JavaScript
const validator = createValidator('#form', {  rules: {    features: { min: 2, max: 3 },  },  messages: {    features: {      min: '至少选择 2 项',      max: '最多选择 3 项',    },  },});

Switch

文件字段

自定义规则

JavaScript
const validator = createValidator('#form', {  rules: {    username: {      validate: (element, validator) => {        if (element.value.includes('admin')) return '不能包含 admin';        return true;      },    },  },});

validate 函数接收字段元素和当前 Validator 实例，返回：

错误提示 DOM

Validator 优先使用最近的 [data-field-control] 作为字段容器；如果找不到，则使用字段的直接父元素。错误提示节点会写入当前字段容器：

HTML
<div data-field-control="email">  <input name="email" />  <div class="help-block" data-validator-help="email" data-valid="false">    Email required  </div></div>

• 属性选择器：Validator 依赖属性名作为交互选择器。已有的 [data-field-help] 静态帮助文案不会被覆盖，动态错误提示只通过 [data-validator-help] 创建和删除。
• 校验交互：校验失败时，错误字段会被标记 [data-validator-help] 和 [data-valid]，校验通过后会移除标记。
• 自动校验：提交或手动调用 validate() 且校验失败后，Validator 会根据 runtime.error 存储的错误字段的 input / change 事件进行自动重验。runtime.error 错误记录清空后，自动校验事件也会清空。
• 自定义错误样式：你可以利用 className 配置，来自定义错误提示样式。