Parsley.js 2.9 表单前端校验实战指南：不写一行 JavaScript 也能完成表单验证

前端【免费下载链接】Parsley.jsValidate your forms, frontend, without writing a single line of javascript项目地址https://gitcode.com/gh_mirrors/pa/Parsley.js点击查看免费下载Parsley.js 是一款基于 jQuery 的前端表单校验库其核心卖点是Validate your forms, frontend, without writing a single line of javascript——借助data-parsley-*系列 HTML 属性Data Attributes DOM API开发者无需编写任何 JavaScript 配置代码即可完成从必填、长度、类型到远程 AJAX 校验的完整表单验证。本文以 README.md 为主线结合仓库内的官方文档doc/index.html与核心源码src/parsley/系统讲解 Parsley.js 2.9.2 的安装引入、配置体系、内置/自定义校验器、UI/UX 行为、事件系统、远程校验、多语言以及本地开发测试流程帮助你快速在项目中落地一套可维护、可扩展的前端校验方案。项目概览稳定维护中的 Parsley.js 2.9.2README 明确说明该项目已进入稳定维护状态不再规划新特性no new features are planned由 marcandre 进行最小化维护高质量修复 Bug 的 PR 会被合并开发新功能前需要先沟通确认。当前仓库版本为2.9.2见 package.json 中的version: 2.9.2。从仓库源码结构看Parsley.js 采用高度解耦的模块化设计核心代码位于src/parsley/目录模块文件职责main.js入口jQuery 版本检测、全局window.Parsley、自动绑定逻辑factory.js工厂根据元素类型创建 Form / Field / FieldMultiple 实例form.js表单实例管理表单内所有字段field.js字段实例单个输入控件的校验逻辑multiple.js多值字段radio / checkbox / 多选 selectdefaults.js全局默认配置validator_registry.js校验器注册表内置校验器与类型检测remote.js远程 AJAX 校验器ui.jsUI/UX错误类名、错误消息、焦点管理base.js基类事件订阅on/off/trigger与选项继承官方文档doc/index.html指出前端校验不能替代后端强校验Parsley 的价值在于让你把后端已定义好的校验规则平移到前端同时最大程度尊重用户体验最佳实践。环境要求与引入方式依赖要求README 明确列出两项依赖jQuery 1.8兼容 jQuery 2.x 和 3.0。Parsley 依赖 jQuery 的事件、AJAX 与 DOM 操作能力必须先于Parsley 引入。es5-shim仅当需要支持 IE8 时引入Parsley 内部使用了 ES5 API如Object.assign、Array.forEach。源码层面main.js 会在加载时主动做版本检查解析$.fn.jquery若主版本 ≤ 1 且次版本 8直接抛出The loaded version of jQuery is too old. Please upgrade to 1.8.x or better.若环境缺少 ES5 能力则通过Utils.warn提示引入 es5-shim。基础安装纯 HTML 方式script srcjquery.js/script script srcparsley.min.js/script form>script srcjquery.js/script script srcparsley.min.js/script form idform ... /form script $(#form).parsley(); // jQuery 插件方式 // 或 new Parsley(#form, options); /script注意官方文档的明确警告如果你手动绑定了表单就不要再给它加data-parsley-validate属性否则文档加载时会被自动绑定一次。并且一旦表单/字段已被绑定再次调用$(#form).parsley(options)只会更新已有选项而非重建实例见 factory.js 中已绑定实例的复用逻辑。jQuery API 返回值速查表官方文档doc/index.html给出了$(...).parsley(options)的完整返回值约定$ API返回$(#existingForm).parsley(options)parsleyFormInstance表单实例$(#existingInput).parsley(options)parsleyFieldInstance字段实例$(#notExistingDOMElement).parsley(options)undefined元素不存在$(.multipleElements).parsley(options)Array[Instances]多个元素返回实例数组这一行为由 main.js 实现多个元素时逐个绑定并收集为数组元素不存在时返回undefined单个元素则new Factory(this[0], options)。核心机制Data Attributes DOM API 与选项继承什么是data-parsley-*Parsley 的默认 DOM API 命名空间是data-parsley-。配置文档里看到的任何foo属性都可以直接用data-parsley-foovalue在 DOM 上设置无需写任何 JavaScript。例如maxlength配置对应data-parsley-maxlength10。复合命名属性会自动 camelCase 映射到 JavaScript 选项值也会自动做类型转换布尔、整数等。官方文档示例doc/index.htmlinput>Parsley.options.maxlength 42; // 全局配置 var formInstance $(form).parsley(); var field $(input).parsley(); console.log(field.options.maxlength); // 42继承全局 Parsley.options.maxlength 30; console.log(field.options.maxlength); // 自动变为 30 formInstance.options.maxlength; console.log(field.options.maxlength); // 自动变为 31校验前的动态刷新官方文档强调Parsley 在每次需要校验字段时都会先从 data 属性重新同步选项actualize。因此运行时动态修改data-parsley-*属性会立即生效例如var instance $(#first).parsley(); console.log(instance.isValid()); // maxlength 是 42字段有效 $(#first).attr(data-parsley-maxlength, 4); console.log(instance.isValid()); // maxlength 变为 4不再有效 instance.options.maxlength; // JS 侧也能直接覆盖 console.log(instance.isValid()); // maxlength 变为 5恢复有效核心配置项详解以下配置项均可用data-parsley-*属性在 DOM 中设置也与 defaults.js 中的默认值一一对应。表单级Form选项属性默认值说明data-parsley-namespacedata-parsley-Parsley DOM API 使用的命名空间data-parsley-validate—文档加载时自动绑定表单无默认值属性存在即生效data-parsley-priority-enabledtruetrue时按优先级依次校验、遇首个失败即停false时同时校验全部约束并展示所有失败项data-parsley-inputsinput, textarea, select表单内查找字段所用的选择器找到后再用excluded过滤data-parsley-excludedinput[typebutton], input[typesubmit], input[typereset], input[typehidden]不参与校验的字段。如需追加 disabled 与隐藏字段可写data-parsley-excludedinput[typebutton], input[typesubmit], input[typereset], input[typehidden], [disabled], :hidden表单级Form方法方法返回说明whenValid({group, force})promise表单有效才 resolve 的 jQuery Promise不影响 UI、不触发事件group限定只校验某分组force强制校验非必填字段isValid({group, force})boolean 或 null同whenValid但已 resolve 返回true、已 reject 返回false、仍在校验中返回nullwhenValidate({group, force})promise校验表单并阻止无效提交触发事件、影响 UIvalidate({group, force})boolean 或 null同whenValidate返回布尔值或nullrefresh()—强制刷新表单及其字段如动态添加带校验的输入、修改inputs/excluded后需要立即生效时使用reset()—重置该表单及其字段的 UIdestroy()—销毁该表单及其字段的 Parsley 绑定字段级Field选项属性说明data-parsley-value指定用于校验的字段值与真实值解耦如data-parsley-valuefooJS API 还支持传入函数$(input typetext).appendTo($(form)).parsley({value: function(parsley) { return foo; }})data-parsley-group给字段分组以支持分组校验如data-parsley-groupsignup可传多个data-parsley-group[foo, bar]data-parsley-multiple将不共享name的 radio/checkbox 关联成一组data-parsley-multiplemymultiplelinkdata-parsley-validate-if-empty默认非必填且为空的字段不校验加上此属性后即使为空也执行校验适合空值也有特殊含义的自定义校验器data-parsley-whitespace仅针对校验用的值处理空白字符不会修改输入框真实内容trim去除首尾空白squish将连续多个空白合并为一个并去除首尾空白data-parsley-ui-enabled设为false时该字段不做任何 UI 变更data-parsley-errors-messages-disabled只添加parsley-success/parsley-error类不显示错误消息文本data-parsley-excluded设为true时绑定表单时会忽略该字段data-parsley-debounce延迟指定毫秒后执行校验用户停止输入才开始计时如data-parsley-debounce500适合远程校验等昂贵场景字段级Field方法方法返回说明isValid({force})true/null/[Violation, ...]判断字段是否有效不影响 UI、不触发事件validate({force, group})同上校验字段触发事件、影响 UIgetErrorsMessages()array返回字段的错误消息数组reset()—重置字段 UIdestroy()—销毁字段绑定关于 checkbox / radio / 多选 select官方文档特别提示radio、checkbox、多选 select 必须有name或id属性才能被正确绑定和校验否则会被忽略并在控制台输出警告。这与 factory.js 的isMultiple/handleMultiple逻辑一致多个 radio/checkbox 会通过name或data-parsley-multiple聚合成一个FieldMultiple实例统一校验。内置校验器大全Parsley 内置了一批常用校验器源码见 validator_registry.js多数支持原生 HTML5 属性直通。官方文档doc/index.html的完整清单如下名称API 写法说明Requiredrequired/data-parsley-required/data-parsley-requiredtrue/data-parsley-requiredfalse必填校验值必须为非空白内容false时禁用该校验器EmailtypeemailHTML5/data-parsley-typeemail校验合法邮箱地址Numberdata-parsley-typenumber按step、min和原始值校验数字。⚠️ HTML5 默认step1过于反直觉Parsley 对data-parsley-typenumber使用默认stepany且支持typenumber的浏览器在非法输入时 JS 拿到的值是永远不会报错除非同时必填IntegertypenumberHTML5/data-parsley-typeinteger校验整数Digitsdata-parsley-typedigits校验纯数字字符串Alphanumdata-parsley-typealphanum校验字母数字字符串UrltypeurlHTML5/data-parsley-typeurl校验合法 URLMinlengthminlength6HTML5/data-parsley-minlength6字符串长度下限Maxlengthmaxlength10HTML5/data-parsley-maxlength10字符串长度上限Lengthminlength6 maxlength10HTML5/data-parsley-length[6, 10]长度区间同时指定两个 HTML5 属性即启用本校验器Minmin6HTML5/data-parsley-min6数字或日期 ≥ 最小值Maxmax10HTML5/data-parsley-max10数字或日期 ≤ 最大值RangetyperangeHTML5/data-parsley-range[6, 10]数字或日期在区间内Patternpattern\dHTML5/data-parsley-pattern\d正则匹配默认锚定全串匹配形如/pattern/flags的写法会被当作字面正则而不锚定MinCheckdata-parsley-mincheck3一组 checkbox 中至少勾选 N 个MaxCheckdata-parsley-maxcheck3一组 checkbox 中至多勾选 N 个Checkdata-parsley-check[1, 3]勾选数量在区间内Equaltodata-parsley-equalto#anotherfield与另一字段值完全一致如密码确认内置校验器的优先级与空值策略源码揭示了两个重要设计优先级required为 512、type为 256、pattern为 64、minlength/maxlength/length/min/max/range等为 30notblank为 2。priorityEnabled: true时高优先级约束先校验失败即停保证一次只展示最重要的一条错误。空值宽容除required外所有内置校验器对空字符串直接返回true如type、pattern、minlength、length的validateString中均有if (!value) return true;这与非必填且为空不校验的默认策略一致。类型检测正则定义在 validator_registry.js 的typeTesters中其中number遵循 HTML5 浮点数规范/^-?(\d*\.)?\d(e[-]?\d)?$/idate通过Utils.parse.date解析标准日期字符串如2017-02-28URL 正则支持协议可省略、IP、端口与资源路径。自定义校验器零门槛扩展内置校验器不够用时Parsley 提供非常简洁的自定义 API。官方文档的标准示例doc/index.htmlinput typetext>// 字段级监听 $(#some-input).parsley().on(field:success, function() { // 这里的 this 是 #some-input 的 parsley 实例 }); // 全局监听任意字段失败都会触发 window.Parsley.on(field:error, function() { console.log(Validation failed for: , this.$element); });官方文档的事件完整清单事件实例触发者说明form:initParsleyFormnew Parsley()表单首次绑定form:validateParsleyForm.validate()表单校验前form:successParsleyForm.validate()表单校验成功后form:errorParsleyForm.validate()表单校验失败后form:validatedParsleyForm.validate()表单校验结束无论成败form:submitParsleyFormsubmit()校验成功、实际提交前返回false可中断提交field:initParsleyFieldnew Parsley()字段首次绑定field:validateParsleyField.validate()字段校验前field:successParsleyField.validate()字段校验成功field:errorParsleyField.validate()字段校验失败field:validatedParsleyField.validate()字段校验结束无论成败事件回调返回false会中断整个回调链trigger中if (result false) return result;form:submit正是利用这一点拦截表单提交。Parsley Remote开箱即用的 AJAX 异步校验data-parsley-remote是官方文档重点介绍的开箱即用异步校验器源码见 remote.js。选项名称API说明远程校验器data-parsley-remotehttp://url.ext校验内容时调用的 URL。若 URL 含{value}占位符则替换为当前值适合 RESTful API否则值作为 data 参数传递键为输入框的name或id反向data-parsley-remote-reverse默认 2xx 视为有效、其余为失败设true后反转——200 视为错误、404 视为正确典型场景检查邮箱/用户名是否已被占用透传 AJAX 选项data-parsley-remote-options传给$.ajax()的 JSON 对象如data-parsley-remote-options{ type: POST, dataType: jsonp, data: { token: value } }。⚠️ JSON 字符串的所有键/值必须用双引号包裹否则$.parseJSON()解析失败指定校验器data-parsley-remote-validator使用特定异步校验器。内置两个default与reversedata-parsley-remote-reverse是remote-validatorreverse的别名。函数内部this指向对应ParsleyField实例底层实现要点从 remote.js 的validateString可以看到完整调用链先确定校验器default/reverse/自定义→ 决定 URL 拼接方式{value}替换或作为 data 参数→ 合并data-parsley-remote-options与自定义校验器的 options → 触发field:ajaxoptions事件可在此拦截修改 AJAX 参数→ 用$.param(ajaxOptions)作为缓存 key对相同请求做缓存去重Parsley._remoteCache并在form:submit时清空缓存。默认异步校验器default判定xhr.status 200 xhr.status 300为有效reverse恰好相反。事件与方法事件field:ajaxoptions字段实例由whenIsValid等触发——在 AJAX 请求发出前触发可通过第二个参数调整传给$.ajax的选项。方法Parsley.addAsyncValidator(name, fn)——注册自定义异步校验器。自定义远程校验器input nameq typetext>$(form).parsley().whenValidate({ group: 2 }).done(function() { // 触发步骤切换 });多语言支持LocalizationParsley 内置校验器的错误消息默认是英文但仓库在 src/i18n/ 提供了数十种语言的翻译文件fr、it、de、zh_cn、zh_tw、ja、ko、ar、ru 等 60 语言部分带.extra.js扩展校验器翻译。引入方式在 Parsley 之后引入翻译文件最后加载的语言自动成为当前 localescript srcjquery.js/script script srcparsley.min.js/script script srci18n/fr.js/script script srci18n/it.js/script上面示例同时加载法语和意大利语最终使用意大利语。构建时gulpfile.babel.js的copyI18n任务会把 src/i18n/*.js 复制到dist/i18n/。运行时也可用window.Parsley.setLocale(zh_cn)或addCatalog动态切换语言。Extras社区贡献的扩展校验器官方文档指出 src/extra/ 目录存放社区贡献的更多或更少有用的校验器包括名称API说明Greater thandata-parsley-gt#anotherfield/data-parsley-gt6大于另一字段值或某严格最小值Greater than or equal todata-parsley-gte#anotherfield/data-parsley-gte6大于等于Less thandata-parsley-lt#anotherfield/data-parsley-lt6小于Less than or equal todata-parsley-lte#anotherfield/data-parsley-lte6小于等于Minwordsdata-parsley-minwords200至少 N 个词Maxwordsdata-parsley-maxwords200至多 N 个词Wordsdata-parsley-words[200, 600]词数在区间内实现位于 src/extra/validator/comparison.js 与 src/extra/validator/words.js。此外 src/extra/validator/ 还提供date、dateiso、luhn、notequalto等校验器以及 src/extra/plugin/bind.js 这类插件示例。生态集成README 列出了社区维护的各类框架集成均为独立仓库Parsley 主仓库只收录链接CakePHP helper、Django 的 django-parsley、Rails 的 parsley-rails、Drupal 的 parsley 模块等。如果你要为其他框架编写集成README 建议创建独立仓库并通过 PR 把链接加入 README 的 Integrations 列表。本地开发安装环境、构建与测试安装开发环境README 给出的开发环境安装步骤需要先安装 npmnpm install -g gulp # 首次安装全局安装 gulp npm install # 安装项目依赖 gulp test # 运行测试构建dist/与doc/annotated-sourcegulp buildgulp build定义见 gulpfile.babel.js会并行执行源码构建Rollup Babel ESLint产物为dist/parsley.js与dist/parsley.min.js、i18n 复制、docco 注解文档生成并回写版本号。Rollup 配置见 rollup.config.js 与 tools/rollup_options.jsUMD 格式、外部依赖jquery、sourcemap 等。运行测试浏览器方式gulp test-browser启动服务器后在浏览器打开 test/runner.html终端方式gulp test。package.jsonpackage.json中 npm scripts 已封装npm test等价gulp、npm run test-browser、npm run build、npm run coverage。单元测试位于 test/unit/field、form、multiple、remote、ui、utils、validator 等均有独立测试文件测试框架为 Mocha expect.js sinon环境搭建见 test/setup/。疑问与参与贡献提问README 建议到 StackOverflow 提问并加上parsley.js标签务必提供可复现的示例官方推荐从一个 jsfiddle 模板开始。贡献详见 CONTRIBUTING.md。因项目已进入稳定维护期新功能需先沟通确认。安全仓库附带 SECURITY.md 安全说明。许可证Parsley.js 以MIT License发布详见仓库 LICENSE 文件。小结Parsley.js 2.9.2 的定位非常清晰——用data-parsley-*声明式属性把校验规则写进 HTML配合三层原型链选项继承、21 个内置校验器、可扩展的自定义/远程校验器、完备的事件系统与多语言支持让前端校验既零 JavaScript又高度可定制。本文涉及的完整文档可在仓库的 doc/index.html 中继续阅读逐行源码注解见 doc/annotated-source/。赞分享前端【免费下载链接】Parsley.jsValidate your forms, frontend, without writing a single line of javascript项目地址https://gitcode.com/gh_mirrors/pa/Parsley.js点击查看免费下载相关推荐CANN/ops-math Sign符号算子Sign 产品支持情况 | 产品 | 是否支持 | | : | : : | | term Ascend 950PR/Ascend 950DT/term |算子库人工智能CANN使用 JavaScript Constraint Validation API 实现实时表单校验curriculum 前端验证实战指南使用 JavaScript Constraint Validation API 实现实时表单校验curriculum 前端验证实战指南 表单是绝大多数网站的核文档教程教育Fcitx故障排除解决常见安装和配置问题的10个技巧Fcitx故障排除解决常见安装和配置问题的10个技巧 Fcitx是一款功能强大的Linux输入法框架支持多种输入法引擎和语言。对于新手用户来说安装和配置F桌面应用上一篇3个关键步骤让你轻松实现B站视频永久保存下一篇媒体全解码经典 UI 一键还原Thorium 上手笔记创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考