★ FEATURED ARTICLE 前端【免费下载链接】formjQuery Form Plugin项目地址https://gitcode.com/gh_mirrors/fo/form点击查看免费下载本篇基于 jQuery Form Plugin 的文档 docs/form-fields.md 展开系统讲解插件中两个面向“字段集合”的工具方法fieldValue获取字段当前值与fieldSerialize将表单的一部分序列化为查询字符串。读完本文你不仅掌握这两个方法的标准用法与successful参数的语义还能结合 src/jquery.form.js 的源码实现与 test/test.js 中的测试断言准确预测各种控件checkbox、radio、select-multiple 等在不同状态下的返回值与序列化结果并在局部提交、局部取数等场景中放心使用它们。方法定位fieldValue 与 fieldSerialize 在插件 API 中的角色jQuery Form Plugin 的核心目标是把普通 HTML 表单升级为可 AJAX 提交README.md 中的ajaxForm/ajaxSubmit。围绕表单数据处理插件提供了几个层次的序列化/取值方法理解它们的分工是正确使用本文两个方法的前提方法作用对象返回值说明formSerialize整个form元素查询字符串name1value1name2value2整个表单序列化fieldSerialize任意字段元素集合jQuery 对象查询字符串只序列化选中的一部分字段fieldValue任意字段元素集合jQuery 对象数组始终返回数组只取值的“原料”不做编码resetForm/clearForm/clearFieldsform / 字段集合jQuery 对象重置与清空与 docs/api.md 中的 API 描述一致fieldSerialize返回 StringfieldValue返回数组二者都不可链式调用。它们的关键差异在于粒度——formSerialize面向表单整体而fieldSerialize与fieldValue面向“匹配集”内的字段子集这正是文档开篇所强调的场景“This is useful when you need to process only certain fields.”从源码调用链看fieldValue并不只是独立的工具方法formToArray整表序列化的底层实现在处理每个普通字段时内部正是调用$.fieldValue(el, true)来取值的见 src/jquery.form.js。也就是说ajaxForm/ajaxSubmit提交时收集到的数据其取值规则与本文讨论的规则完全同源——理解fieldValue的语义也就理解了插件提交数据的底层行为。fieldValue获取字段当前值基本用法fieldValue用于读取匹配集中字段元素的当前值。文档给出的典型示例是取出 id 为myForm的表单中密码输入框的值var pwd $(#myForm :password).fieldValue()[0];必须牢记的契约是该方法始终返回数组。无法确定有效值时返回空数组否则包含一个或多个值// 匹配到一个 text 输入框值为 abc $(#myForm :text).fieldValue(); // [abc] // 匹配到没有任何选中项的 checkbox 集合 $(#myUncheckedBoxes).fieldValue(); // []docs/api.md 中的示例同样演示了这一取法// get the value of the password input var value $(#myFormId :password).fieldValue(); alert(The password is: value[0]);返回值随控件类型而不同结合源码注释src/jquery.form.js给出的示例场景可以归纳出各控件类型在“成功控件”模式下的返回形态// 两个同 name 的 text 输入框始终返回各自的值未输入则为 var v $(input[typetext]).fieldValue(); // 未输入时 v [,]输入 foo 和 bar 时 v [foo,bar] // 未勾选的 checkbox 集合空数组 var v $(input[typecheckbox]).fieldValue(); // 两个都勾选时 v [B1,B2] // radio 组只有被选中的那一个返回 var v $(input[typeradio]).fieldValue(); // 均未选中时 v []选中第一个时 v [C1]对于select元素单选select返回单个选中项的 value带multiple的select返回所有被选中且未禁用选项的 value 数组若没有任何选项被选中selectedIndex -1则视为无效值返回null最终被fieldValue过滤掉。对于 textarea、text、hidden、password 等常规控件返回的是$(el).val()的字符串值。successful 参数与“成功控件”语义fieldValue接受一个可选参数successful控制“字段是否必须处于成功控件successful control状态才算有效”。默认值为true即与浏览器原生构建表单数据集时的行为保持一致未勾选的 checkbox、未被点中的 submit 按钮、无 name 的控件、disabled 的控件等都不会产生值。文档中的演示对一个未勾选的 checkbox// value will be an empty array if checkbox is not checked: var value $(#myUncheckedCheckbox).fieldValue(); // value.length 0但如果你确实想在 checkbox 未勾选时仍然拿到它的value属性可以显式传入false// value will hold the checkbox value even if its not checked: var value $(#myUncheckedCheckbox).fieldValue(false); // value.length 1源码src/jquery.form.js对这一判定给出了完整依据。$.fieldValue(el, successful)在未显式传参时将successful置为true随后执行如下过滤——命中任意一条即返回nullif (typeof successful undefined) { successful true; } if (successful (!n || el.disabled || t reset || t button || (t checkbox || t radio) !el.checked || (t submit || t image) el.form el.form.clk ! el || tag select el.selectedIndex -1)) { return null; }翻译成规则表successful true时生效判定条件结果无name属性无值null控件disabled无值type为reset或button无值checkbox/radio且未checked无值submit/image且不是本次点击的按钮form.clk ! el无值select且selectedIndex -1无任何选中项无值这解释了两个常见“意外”其一reset按钮的 value 永远取不到其二fieldValue作用在全部 submit 按钮上时只有模拟“被点击”的那个才有效——这与formToArray中对form.clk被点击的图片/提交按钮坐标的特殊处理相呼应。源码实现细节合并、过滤与换行规范化jQuery 方法层$.fn.fieldValue的实现src/jquery.form.js遍历匹配集中的每个元素调用底层$.fieldValue并按类型合并结果$.fn.fieldValue function(successful) { for (var val [], i 0, max this.length; i max; i) { var el this[i]; var v $.fieldValue(el, successful); if (v null || typeof v undefined || (v.constructor Array !v.length)) { continue; // 无效值null/undefined/空数组直接跳过 } if (v.constructor Array) { $.merge(val, v); // select-multiple 的数组结果并入总数组 } else { val.push(v); } } return val; };要点有二无效值被静默过滤单个元素返回null、undefined或空数组时直接continue所以“始终返回数组”且数组里不会出现空槽。多值控件展开合并一个select multiple产生的数组会被$.merge平铺进总结果多个 checkbox/radio 的值按元素顺序依次追加。对 select 分支源码src/jquery.form.js区分了单选与多选单选只遍历被选中的一项并直接返回其 value多选则遍历全部选项收集“selected且未disabled”的选项。其中还有一段针对旧版 IE 的兜底当选项未显式指定value属性时回退使用op.text。对除 select 外的控件最终取值为src/jquery.form.jsreturn $(el).val().replace(rCRLF, \r\n);其中rCRLF /\r?\n/g定义于 src/jquery.form.js。这个替换的作用是把 textarea 中的换行统一规范为 CRLF避免在 Windows 文本域中产生的\r\n与类 Unix 环境产生的\n混用时出现“双回车”问题——这是从源码结构看一个容易被忽略但很实用的细节。fieldSerialize只序列化表单的一部分基本用法fieldSerialize把匹配集中的字段元素序列化为查询字符串格式为name1value1name2value2。当只需要提交/处理表单中的某些字段时它比formSerialize更合适。文档示例——只序列化表单中的 text 输入var queryString $(#myForm :text).fieldSerialize();docs/api.md 与 README.md 给出的另一种典型用法是按 CSS 类名选取“特殊字段组”var queryString $(#myFormId .specialFields).fieldSerialize();序列化结果可以直接交给$.get/$.post/$.ajax完成部分字段提交而无需触发整个表单。序列化规则无 name 即跳过数组展开$.param 编码源码实现src/jquery.form.js非常直白/** * Serializes all field elements in the jQuery object into a query string. * This method will return a string in the format: name1value1amp;name2value2 */ $.fn.fieldSerialize function(successful) { var a []; this.each(function() { var n this.name; if (!n) { return; // 无 name 的字段直接跳过 } var v $.fieldValue(this, successful); if (v v.constructor Array) { for (var i 0, max v.length; i max; i) { a.push({name: n, value: v[i]}); // 多值控件展开为多个同名键 } } else if (v ! null typeof v ! undefined) { a.push({name: this.name, value: v}); } }); // hand off to jQuery.param for proper encoding return $.param(a); };三个规则值得强调无name的字段被静默跳过不会在结果中留下null...之类的脏数据多值控件checkbox 组、select multiple展开为多个同名键值对例如两个勾选的F复选框会产出F8F10编码完全委托给jQuery.param保证空格、中文等特殊字符被正确 URL 编码。这与formSerialize的做法一致$.param(this.formToArray(semantic))见 src/jquery.form.js。与fieldValue一样fieldSerialize也接受successful参数默认行为只序列化“成功控件”。二者的关系可以理解为fieldSerializefieldValue的取值规则 同名键展开 $.param编码。测试套件中的行为验证仓库的 QUnit 测试test/test.js围绕 test/test.html 中的隐藏测试表单#fieldTest对这两个方法做了成对断言非常适合用来核对心智模型!-- test/test.html 中的 #fieldTest 表单节选 -- select nameA...选中 value1 select nameB multiplemultiple...选中 3 和 4 input nameC typehidden value5 input nameD typetext value6 textarea nameE7/textarea input nameF typecheckbox value8 checkedchecked input nameF typecheckbox value9 input nameF typecheckbox value10 checkedchecked input nameG typeradio value11 input nameG typeradio value12 checkedchecked input nameG typeradio value13 input nameH typepassword value14 input nameI typesubmit value15 input nameJ typereset value16对应的断言结论摘自 test/test.js调用期望结果验证的规则$(#fieldTest :checkbox).fieldValue(true)[8,10]成功模式下未勾选的 value9 被排除$(#fieldTest :checkbox).fieldValue(false)[8,9,10]false模式下所有 checkbox 的 value 都返回$(#fieldTest :radio).fieldValue(false)[11,12,13]radio 组在非成功模式下整组返回$(#fieldTest [nameB]).fieldValue(true)[3,4]select-multiple 只返回被选中项$(#fieldTest :radio).fieldSerialize(true)G12radio 组只序列化被选中项$(#fieldTest :radio).fieldSerialize(false)G11G12G13非成功模式下整组序列化$(#fieldTest input).fieldSerialize(true)C5...H14submit(I) 与 reset(J) 在成功模式下不出现$(#fieldTest :input).fieldSerialize(false)额外包含I15J16false模式下 submit/reset 按钮的 value 也被序列化这些用例把successful参数对 checkbox、radio、submit、reset 四类控件的差异影响验证得非常完整。阅读测试表单 test/test.html 与断言 test/test.js 是快速校准“我的用法会得到什么结果”的最可靠途径。综合测试表单一次覆盖所有控件类型docs/form-fields.md 附带了一个交互演示页输入任意 jQuery 选择器如:text、:radio、textarea、[typehidden]、:checkbox等即可对下方测试表单运行fieldValue与fieldSerialize并可勾选“仅成功控件”开关切换successful参数。该演示表单覆盖了各类控件这里完整保留方便本地搭建自己的验证页面form idtest actiondummy.php methodpost strongTest Form/strong table trtdlt;input typehidden nameHidden valuesecretgt;/td tdinput typehidden nameHidden valuesecret/td/tr trtdlt;input nameName typetext valueMyName1gt;/td tdinput nameName typetext valueMyName1/td/tr trtdlt;input namePassword typepasswordgt;/td tdinput namePassword typepassword value/td/tr trtdlt;select nameMultiple multiplemultiplegt;/td tdselect nameMultiple multiplemultiple option valueone selectedselectedOne/option option valuetwoTwo/option option valuethreeThree/option /select/td/tr trtdlt;select nameSinglegt;/td tdselect nameSingle option valueone selectedselectedOne/option option valuetwoTwo/option option valuethreeThree/option /select/td/tr trtd colspan2input typecheckbox nameCheck value1 input typecheckbox nameCheck value2 input typecheckbox nameCheck value3 input typecheckbox nameCheck2 value4 input typecheckbox nameCheck2 value5 input typecheckbox nameCheck3/td/tr trtd colspan2input typeradio nameRadio value1 input typeradio nameRadio value2 input typeradio nameRadio value3 input typeradio nameRadio2 value4 input typeradio nameRadio2 value5/td/tr trtdlt;textarea nameText rows2 cols20gt;lt;/textareagt;/td tdtextarea nameText rows2 cols20/textarea/td/tr trtdlt;input typereset nameresetButton valueResetgt;/td tdinput typereset nameresetButton valueReset/td/tr trtdlt;input typesubmit namesub valueSubmitgt;/td tdinput typesubmit namesubmitButton valueSubmit/td/tr /table /form注意其中nameCheck的三个 checkbox 与未带 value 的Check3前者用于观察同名多值的展开后者用于观察“无 value 属性时 checkbox 取什么值”这类边界行为。实战要点与常见误区局部提交的标准姿势。表单很大但服务端只关心部分字段时// 只提交 .specialFields 组内的字段 var queryString $(#myFormId .specialFields).fieldSerialize(); $.post(myscript.php, queryString);选择器本身:text、:input、属性选择器、类名等就是“字段子集”的定义灵活性远高于formSerialize。fieldValue 是纯取值fieldSerialize 才做编码。需要拿到原始值数组做前端校验/展示时用fieldValue需要把数据发出去时用fieldSerialize或$.param自行组装。不要假设未勾选的 checkbox 有值。默认successful为 true时未勾选的 checkbox 既不产生fieldValue结果也不会出现在fieldSerialize字符串中——这与浏览器原生提交行为一致。若后端期望“未勾选时也传一个标记值”应改用fieldValue(false)/fieldSerialize(false)或提交前显式补一个隐藏字段。radio 组在false模式下的语义要当心fieldSerialize(false)会把组内所有 radio含未选中的都序列化进去测试断言G11G12G13这与原生表单语义差异很大通常只用于调试或需要完整快照的场景。submit/image 按钮值只在“被点击”时有效。成功模式下只有form.clk本次点击的按钮才取值reset、button类型则恒无值。从源码结构看这与formToArray里对form.clk_x/form.clk_y坐标的特殊处理共同构成了图片按钮提交的完整支持。textarea 换行会被规范化为\r\nrCRLF替换跨平台拼接多行文本时可以放心使用fieldValue的结果。小结fieldValue与fieldSerialize是 jQuery Form Plugin 中字段级数据访问的基石前者以“始终返回数组”的契约提供各控件类型的当前值后者把字段子集编码为可直接传输的查询字符串。二者共用successful参数来对齐浏览器“成功控件”语义并共享同一套底层取值逻辑$.fieldValue这套逻辑同样服务于formToArray→ajaxForm/ajaxSubmit的提交流程。遇到取值或序列化结果“不符合预期”时按“是否无 name / 是否 disabled / 勾选状态 / 按钮是否被点击 / select 是否有选中项”这条判定链逐一排查并对照 test/test.js 的断言预期基本都能快速定位原因。赞分享前端【免费下载链接】formjQuery Form Plugin项目地址https://gitcode.com/gh_mirrors/fo/form点击查看免费下载相关推荐jQuery Form终极指南5个fieldValue方法技巧轻松获取表单字段值jQuery Form终极指南5个fieldValue方法技巧轻松获取表单字段值 jQuery Form插件是一个强大的JavaScript库专门用于简化H前端jQuery Form数据序列化终极指南formSerialize与fieldSerialize使用技巧jQuery Form数据序列化终极指南formSerialize与fieldSerialize使用技巧 jQuery Form插件是前端开发中处理表单AJA前端jQuery Form Plugin API 深度解析ajaxForm、ajaxSubmit 与表单序列化方法全解jQuery Form Plugin API 深度解析ajaxForm、ajaxSubmit 与表单序列化方法全解 jQuery Form Plugin 的核前端上一篇GetQzonehistory 实操免费完整导出 QQ 空间历史说说、评论与高清图下一篇MuJoCo 刚柔耦合仿真完整指南flexcomp 柔体建模与弹性参数调优创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
