前端UI组件移动开发【免费下载链接】cube-ui:large_orange_diamond: A fantastic mobile ui lib implement by Vue项目地址https://gitcode.com/gh_mirrors/cu/cube-ui点击查看免费下载导读cube-validator是 cube-ui基于 Vue 的移动端组件库中用于表单数据校验与错误提示的独立组件自 1.5.0 版本起提供。本文以其官方文档为核心结合仓库源码与单元测试系统讲解它的基本用法、内置规则与类型、消息模板机制、异步校验、多表单提交最佳实践以及如何通过addRule、addType、addMessage、addHelper扩展校验能力。读完本文你将能独立为表单实现「实时校验 自定义提示 异步校验 提交联动」的完整方案。组件定位与核心概念Validator 是一个独立于表单的校验组件它不依赖cube-form而是通过model属性与需要校验的表单数据绑定通过rules定义校验规则通过v-model对外输出校验结果true为通过、false为不通过、undefined表示尚未校验/校验中。每个内置规则都带有默认提示消息支持英文和中文你也可以用messages属性自定义。提示本文所有源码引用均来自当前仓库例如组件实现位于 validator.vue校验规则与类型定义位于 src/common/helpers/validator。基本用法Validator 以组件形式直接包裹或并列于表单控件使用。下面是一个校验 E-mail 输入框的完整示例cube-input v-modeltext1 placeholderE-mail/cube-input cube-validator v-modelvalid :modeltext :rulesrules :messagesmessages/cube-validatorexport default { data() { return { text: , valid: undefined, rules: { required: true, type: email, pattern: /didi.com$/, custom: (val) { return val.length 12 } }, messages: { pattern: The E-mail suffix need to be didi.com., custom: The E-mail need contain at least 12 characters. }, } } }要点说明rules中required、type、pattern正则、custom自定义函数可以同时组合使用多条规则会并行校验messages是可选属性key 与规则名一一对应用于覆盖默认提示不传时使用内置默认消息见下文「内置默认消息」valid初始值为undefined表示尚未校验组件内部通过input事件把最新结果写回v-model。从源码看组件对外暴露的关键 props 为model必填、rules默认{}、messages、disabled、immediate见 validator.vue。组件会深度监听targetModel的变化一旦数据变化且未处于 disabled 状态便自动执行validate()并置dirty truevalidator.vue。给表单控件添加警告样式当校验失败时Validator 根元素会获得cube-validator_invalid类名校验成功时为cube-validator_valid异步校验中为cube-validator_validating见 containerClass 计算属性。因此你只要把表单控件放进 Validator 内部再基于cube-validator_invalid选择后代元素即可加警告样式cube-validator :modeltext :rulesrules v-modelvalid cube-input v-modeltext/cube-input /cube-validatorexport default { data() { return { text: , valid: undefined, rules: { required: true, type: email, min: 6 } } } }/* add warning style to input */ .cube-validator_warn input border: solid 1px yellow同时注意组件内部默认渲染的错误消息容器为.cube-validator-msg默认消息文本位于.cube-validator-msg-def模板定义文档中提到的类名在实际实现中为cube-validator_invalid以源码为准。自定义消息插槽message slot默认提示比较简单但你可以通过具名插槽message完全自定义警告模板比如插入图标、图片或遍历所有失败规则。插槽作用域参数如下| 参数 | 含义 | | - | - | |dirty| 表单数据是否被修改过 | |validating| 是否正在校验中 | |validated| 是否已经执行过校验 | |message| 第一条失败规则的提示消息 | |result| 对象包含每条规则的校验结果与消息形如{ required: { valid: false, invalid: true, message: required } }|示例——在警告中同时展示图标和所有失败规则的消息cube-validator v-modelvalid :modeltext :rulesrules :messagesmessages cube-input v-modeltext placeholdercomponent name/cube-input div slotmessage classcustom-msg slot-scopeprops div v-if(props.dirty || props.validated) !valid i classdd-cubeic-important/i {{ props.message }} div span v-for(item, index) in Object.values(props.result) :keyindex v-ifitem.inValid {{ item.message }} /span /div /div /div /cube-validatorexport default { data() { return { valid: undefined, text: , rules: { type: string, pattern: /^cube-/, min: 8, max: 10 }, messages: { pattern: The component name need start with cube- }, } } }.custom-msg color: orange其中result由组件内部的_checkTasks逐条规则生成{ key: { valid, invalid, message } }见 validator.vuemessage则取第一条失败规则的消息。异步校验1.8.0某些校验需要请求后端如验证码、用户名查重。从 1.8.0 起规则函数可以返回一个接收resolve回调的函数调用resolve(true)视为成功否则视为失败一个Promise 对象resolve的值严格等于true视为成功否则视为失败。异步校验过程中会触发validating事件结束后触发validated事件。div classvalidator-item pAsync validate: /p cube-validator v-modelvalid :modelcaptcha :rulesrules :messagesmessages :immediateimmediate validatingvalidatingHandler validatedvalidatedHandler cube-input v-modelcaptcha placeholderPlease input captcha/cube-input /cube-validator /divexport default { data() { return { valid: undefined, captcha: , rules: { type: number, required: true, len: 6, captchaCheck: (val) { return (resolve) { setTimeout(() { resolve(val 123456) }, 1000) } /** or return promise: return new Promise((resolve) { setTimeout(() { resolve(val 123456) }, 1000) }) **/ } }, messages: { captchaCheck: Please input 123456 } } }, methods: { validatingHandler() { console.log(validating) }, validatedHandler() { console.log(validated) } } }这里的captchaCheck就是一个异步规则。从实现看validate()会为每个规则收集任务若规则返回值是带then的对象则走 Promise 分支若是函数则作为「接收 resolve/reject 回调」调用否则按同步结果处理validator.vue。多条规则通过parallel并行执行全部结束后统一汇总只有存在异步任务时才会触发validating事件并在此期间将valid置为undefinedvalidator.vue。单元测试 validator.spec.js 也覆盖了 Promise reject、resolve 回调等异步路径以及校验中容器类名变为cube-validator_validating的行为。提交场景的最佳实践提交按钮通常不在 Validator 内部但校验结果与提交逻辑强相关。推荐做法给每个 Validator 加ref提交时逐个调用validate()方法再对所有结果做every判断cube-input v-modeltext0 placeholderRequired/ cube-validator refvalidator0 v-modelresult[0] :modeltext0 :rulesrules0/ cube-input v-modeltext1 placeholderE-mail/ cube-validator refvalidator1 v-modelresult[1] :modeltext1 :rulesrules1/ cube-input v-modeltext2 placeholderTEL/ cube-validator refvalidator2 v-modelresult[2] :modeltext2 :rulesrules2/ cube-button clicksubmitSubmit/cube-buttonexport default { data() { return { result: [true, true, true], text0: , rules0: { required: true, }, text1: , rules1: { type: email, }, text2: , rules2: { type: tel, }, trigger: false } }, methods: { submit() { this.$refs.validator0.validate() this.$refs.validator1.validate() this.$refs.validator2.validate() if (this.result.every(item item)) { this.$createToast({ type: correct, txt: Submited, time: 1000 }).show() } } } }该模式的优势即使表单数据从未被修改dirty为 false、警告消息默认不展示点击提交时也会强制执行校验避免漏网之鱼同时validate()支持传入回调或返回 Promise便于与异步校验场景衔接。Props 一览| 属性 | 说明 | 类型 | 可选值 | 默认值 | | - | - | - | - | - | | model | 必填要校验的数据 | Any | - | - | | v-model | 校验结果数据是否有效 | Boolean | true/false | true | | rules | 校验规则详见下文 | Object | - | {} | | messages | 对应规则的自定义提示消息 | Object | - | {} | | immediate | 加载后立即校验 | Boolean | true/false | false | | disabled1.7.0 | 是否禁用校验 | Boolean | true/false | false |补充实现细节来自 validator.vue组件还支持modelKey属性可通过modelKey指定从model对象中取具体字段进行校验targetModel计算属性disabled与「没有配置任何规则」都会让组件进入isDisabled状态此时不校验、不加警告样式immediate为true时在created阶段立即执行一次validate()。事件与实例方法事件| 事件名 | 说明 | 参数 | | - | - | - | | validating | 正在校验仅在异步校验时触发 | - | | validated | 校验完成仅在异步校验时触发 | valid校验是否成功 | | msg-click | 点击错误消息元素 | - | | input | 绑定值变化时触发 | 更新后的值 |实例方法| 方法名 | 说明 | 参数 | 返回值 | | - | - | - | - | | validate(cb) | 执行校验 | cb校验完成回调通常用于异步场景参数为valid值 | 若环境支持 Promise则返回 Promise 实例只有 resolved 状态resolved 值为valid否则返回undefined|源码中validate通过cb2PromiseWithResolve(cb)实现回调与 Promise 的双通道且校验结果通过input事件同步给v-modelvalidator.vue。另外组件还内置了reset()方法重置dirty、validated、msg、result与valid测试用例 validator.spec.js 对此有验证。内置规则详解内置规则包括required、type、min、max、len、notWhitespace、pattern、custom其实现位于 rules.js。| 属性 | 说明 | 类型 | 可选值 | 示例 | | - | - | - | - | - | | required | 是否必填 | Boolean | true/false | true | | type | 数据类型 | String | string、number、array、date、email、tel、url | tel | | min | type 为 number/date 时表示不小于该值否则表示长度不小于该值 | Number | - | 6 | | max | type 为 number/date 时表示不大于该值否则表示长度不大于该值 | Number | - | 8 | | len | type 为 number/date 时表示等于该值否则表示长度等于该值 | Number | - | 7 | | notWhitespace | 不允许为空白字符 | Boolean | true/false | true | | pattern | 正则匹配 | RegExp | - | /1$/ | | custom | 自定义校验函数仅当返回值严格等于true时通过 | Function | - | val val.length 7 |关键实现细节required对数组类型校验长度 0对其他类型要求不等于、undefined、nullmin/max在number/date类型下用Number(val)比较数值否则比较val.lengthlen会先判断target.length是否可用对无 length 的对象取Object.keys(target).length否则转为字符串再取长度notWhitespace用/^\s$/判断是否纯空白pattern直接调用pattern.test(val)。内置类型types见 types.js的实现也值得了解例如tel使用^(11|13|14|15|17|18|19)[0-9]{9}$匹配中国大陆手机号date支持时间戳或yyyy-MM-dd/yyyy/MM/dd/yyyy.MM.dd格式字符串email与url均有对应正则。添加自定义规则除了内置规则可以通过addRule注册通用自定义规则并用addMessage注册对应的默认提示import Vue from vue import { Validator } from cube-ui // need use Validator Vue.use(Validator) Validator.addRule(odd, (val, config, type) !config || Number(val) % 2 1) Validator.addMessage(odd, Please input odd.)cube-validator v-modelvalid :modeltext :rulesrule cube-input v-modeltext3 placeholderodd/cube-input /cube-validatorexport default { data() { return { text: 100, valid: undefined, rules: { type: number, odd: true } } } }addRule注册的规则函数签名为(val, config, type)——val是待校验值、config是你在rules中给该规则配置的值如true、type是当前type规则的值。其实现基于createAddAPIrules.js并统一挂载在Validator.addRule上模块入口。添加新的类型通过addType可以新增类型或覆盖内置类型import { Validator } from cube-ui // 新增类型 Validator.addType(yourType, (val) { return typeof val string /^[a-z0-9_-]/i.test(val) }) // 覆盖内置类型 Validator.addType(email, (val) { return typeof val string /^[a-z0-9_-][a-z0-9_-](\.[a-z0-9_-])$/i.test(val) })type规则本身不做正则校验而是委托给types表中的校验函数!types[type] || typestype见 rules.js因此新增类型后即可直接在rules.type中使用。默认消息与模板机制内置默认消息Validator 内置了如下默认消息同时提供英文与中文以下为英文版本const messages { required: Required., type: { string: Please input characters., number: Please input numbers., array: The data type should be array., date: Please select a valid date., email: Please input a valid E-mail., tel: Please input a valid telphone number., url: Please input a valid web site. }, min: { string: Please input at least {{config}} characters., number: The number could not smaller than {{config}}., array: Please select at least {{config}} items., date: Please select a date after {{config | toLocaleDateString(yyyy-MM-dd)}}., email: Please input at least {{config}} characters., tel: Please input at least {{config}} characters., url: Please input at least {{config}} characters. }, max: { string: Please input no more than {{config}} characters., number: The number could not bigger than {{config}}, array: Please select no more than {{config}} items, date: Please select a date before {{config | toLocaleDateString(yyyy-MM-dd)}}., email: Please input no more than {{config}} characters., tel: Please input no more than {{config}} characters., url: Please input no more than {{config}} characters. }, len: { string: Please input {{config}} characters., number: The length should equal {{config}}, array: Please select {{config}} items, date: Please select {{config | toLocaleDateString(yyyy-MM-dd)}}., email: Please input {{config}} characters., tel: Please input {{config}} characters., url: Please input {{config}} characters. }, pattern: The input dont match pattern., custom: Invalid., notWhitespace: Whitespace is invalid. }修改内置消息用addMessage可以覆盖某个规则的默认消息也支持按子类型细化覆盖import Vue from vue import { Validator } from cube-ui // need use Validator Vue.use(Validator) Validator.addMessage(required, Please input this.) // 覆盖 min.date 的消息 Validator.addMessage(min, { date: Please select a date after {{config | toLocaleDateString(yyyy-MM-dd) | tips(Please re-enter)}}. })addMessage的实现会对当前语言下的validator消息命名空间做深合并deepAssign见 messages.js所以可以只覆盖需要的字段。消息模板中的 config 与 helper组件内部解析消息时采用了类似 Vue filter 的管道机制实现见 string-template.jsconfig即你在规则里配置的值。例如规则配置为{ type: date, min: 2018-10-10 }那么min消息模板中的{{config}}就是2018-10-10由于该字段是date类型min的值可以是时间戳也可以是yyyy-MM-dd mm:ss或yyyy/MM/dd mm:ss这类日期字符串。toLocaleDateString内置 helper 函数第一个参数是配置值第二个参数是期望的日期格式如yyyy-MM-dd。它内置在Locale.helpers命名空间中locale/index.js对 Safari 等不支持yyyy-MM-dd格式的环境会自动把-替换为/再格式化。你也可以注册自己的 helperValidator.addHelper(fnName, (result, arg1) { // result - 上一个 helper 的返回值或 config 值如上例中的 2018-10-10 // arg1 - 消息模板中传入的字符串如上例中的 Please re-enter let ret // do your own job ret result arg1 // 必须返回处理后的消息 return ret })注意通过Validator.addHelper注册的工具函数实际挂载在Locale.helpers命名空间下你也可以直接引入Locale模块用Locale.addHelper注册两者指向同一地址validator 模块入口 中Validator.addHelper Locale.addHelper。模板解析时若引用了未注册的 helper会给出告警并输出空字符串string-template.js。小结cube-ui Validator 的核心设计是「数据驱动校验」通过model绑定数据、rules声明规则、v-model回传结果配合插槽、事件与实例方法足以覆盖移动端表单从基础必填到异步校验的绝大多数场景。若需更进一步可以继续阅读仓库内的相关文件组件实现src/components/validator/validator.vue规则与类型定义src/common/helpers/validator/rules.js、src/common/helpers/validator/types.js消息与模板机制src/common/helpers/validator/messages.js、src/common/helpers/string-template.js模块注册src/modules/validator/index.js单元测试test/unit/specs/validator.spec.js中文文档document/components/docs/zh-CN/validator.md赞分享前端UI组件移动开发【免费下载链接】cube-ui:large_orange_diamond: A fantastic mobile ui lib implement by Vue项目地址https://gitcode.com/gh_mirrors/cu/cube-ui点击查看免费下载相关推荐cube-ui Validator 组件完全指南表单校验规则、异步验证与自定义提示实战cube ui Validator 组件完全指南表单校验规则、异步验证与自定义提示实战 导读 cube validator 是 cube uiVue 移动端前端UI组件移动开发Formily 表单校验完全指南内置规则、格式校验、自定义规则与异步/联动校验Formily 表单校验完全指南内置规则、格式校验、自定义规则与异步/联动校验 Formily 的表单校验依托 formily/validator 校验引擎前端UI组件react-jsonschema-form 表单校验完全指南validator 架构、AJV8 预编译验证器与自定义校验规则react jsonschema form 表单校验完全指南validator 架构、AJV8 预编译验证器与自定义校验规则 表单校验是 react json前端UI组件上一篇CANN/GE RunGraph API文档下一篇效率倍增掌握lazygit多工作模式无缝切换的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考