以前带前端小组时定过一条规矩：jQuery代码里凡是操作checkbox，一律用prop，禁止用attr。原因很简单，这个看似只有一行的API背后牵扯到HTML attribute与DOM property两套机制，用错了就是线上bug，而且症状往往不会马上暴露，通常是用户多点了几下、多切换几次状态之后才错乱，后台收到的数据和页面显示的勾选状态完全对不上。
这篇就围绕jQuery操作checkbox这一件事，把读取状态、设置状态、全选联动、事件委托、批量收集选中值这些场景一次讲透，顺便把最容易踩的prop/attr的坑说清楚。内容不绕弯子，都是可以直接抄的代码，适合在维护老jQuery项目的人、后台系统还在用jQuery的开发者，以及刚接手历史代码还没时间全面重构的团队。如果你已经开始用Vue/React，这篇文章也可以当“考古手册”，毕竟存量项目里这类代码还大量存在。
1. 先搞清prop和attr的恩怨：为什么$('#cb').attr('checked')会失灵
1.1 attribute和property是两套机制
很多同学分不清attribute和property，其实只要记住一句话：attribute是HTML源码里写的属性，property是浏览器解析完之后挂在DOM对象上的属性。对于checkbox来说，<input type="checkbox" checked>里的checked是一个attribute，值是一个字符串；而document.getElementById('cb').checked是一个property，值是布尔值true或false。
两者不是一回事。浏览器渲染时，勾选框的状态跟随property，而不是attribute。用户点击一下checkbox，property从true变false，但HTML源码里的attribute不会因此改变。用生活类比：attribute相当于柜台上贴的价签，property相当于收银系统里的实时价格。顾客结账时老板看的是收银系统，不是价签。你手动改了价签，只要收银系统没动，结账价格就不变。
我见过很多新人写代码时习惯性用attr('checked')去做状态判断或状态切换，就是因为没区分这两者。页面上第一次操作倒还正常，一旦用户交互过几次，attribute和property就分离了，代码就会拿到陈旧的值，表现出一堆“看起来是随机出现”的bug。
1.2 jQuery 1.6前后：一次升级引发的“翻车潮”
jQuery在早期只有attr一个方法，那时它对checked等布尔类attribute做了很多跨浏览器的兼容处理，开发者用起来倒也顺手。1.6.0版本正式引入prop方法，开始明确区分attribute和property，同时对attr('checked')的返回行为做了调整。这次调整引发过一轮被称为“升级翻车潮”的兼容问题：很多项目从1.4/1.5升级到1.6后，校验逻辑突然失灵，原因就是代码里到处是if ($('#cb').attr('checked'))这样的判断。
1.6.1针对attr('checked')的返回规则又做了一次修正：当元素HTML上真的有checked这个attribute时返回字符串'checked'，否则返回undefined。看起来更“符合直觉”了，但核心问题没有变：attribute不会跟随用户交互实时更新。一个页面加载时带checked的checkbox，用户手动取消勾选之后，attr('checked')拿到的仍然可能是'checked'。所以无论哪个版本，用attr去判断checkbox是否选中都是不可靠的，这是jQuery社区很早就达成共识的结论。
那attr在checkbox场景里还有用吗？基本只剩一个用途：输出到HTML里的“默认选中”标记。比如服务端渲染模板时，或者用jQuery生成一段HTML字符串时，需要写checked这个attribute，那确实得用attr。运行时的一切状态读取、切换，都应该走prop。
1.3 判断状态到底该用哪个API
把结论放在前面：读状态优先用is(':checked')或prop('checked')，写状态一律prop('checked', true/false)。代码如下：
// 读取 $('#cb').is(':checked'); // 推荐，语义直白 $('#cb').prop('checked'); // 推荐，开销更小 // 写入 $('#cb').prop('checked', true); $('#cb').prop('checked', false);is(':checked')内部要做选择器解析，prop('checked')只是取一个DOM property，所以频繁遍历的场景里prop会更快一点，不过单个控件的判断差距可以忽略。后面我会专门写一节，讲讲批量场景里怎么选。
2. 读取和设置选中状态：这几种写法分别适合什么场景
2.1 读取状态的三类写法
除了一开始说的is和prop，还有一类更直接的写法：在each遍历里直接用原生DOM属性。
$('.row-check').each(function () { if (this.checked) { console.log('已选中', this.value); } });原生的this.checked是最底层、最快的途径，jQuery只是帮你把回调函数绑定好了。如果你已经在用each或map，回调里没必要再包一层$(this).prop('checked')。减少一次jQuery对象的创建和包装，代码也更轻。
那什么时候用is(':checked')？最常见的是单独拿一个元素判断，比如表单提交前校验协议是否勾选：
if ($('#agree').is(':checked')) { // 继续 }什么时候用prop('checked')？需要把结果直接参与逻辑运算，比如同步某个布尔值给其他控件。它返回的就是布尔量，不用再做类型转换。这一段的选择逻辑并不复杂，核心原则是：单个控件怎么方便怎么来，批量遍历里尽量用this.checked。
2.2 设置状态的两类写法
设置状态没有太多花样，prop是王道：
$('#agree').prop('checked', true); $('.row-check').prop('checked', false);jQuery会自动遍历匹配到的所有元素，所以批量勾选一行代码就够了。在each回调里也可以用this.checked直接赋值：
$('.row-check').each(function () { this.checked = true; });还有一种写法见得也不少：attr('checked', 'checked')。我在写代码审查时看到这种写法会直接标红。因为attr改动的是content attribute，浏览器呈现勾选依赖的是property，两者在交互后不同步，运行时用attr改状态很容易出现“点了没反应”或“取消了但数据还在”的诡异现象。如果你是从老项目里翻到这种写法，统一改成prop。
2.3 一个典型的误用场景与完整排查过程
拿一个真实遇到的问题举例。某个后台有一个“同意协议”checkbox，提交逻辑是：
if ($('#agree').attr('checked')) { submitForm(); }现象很迷惑：新打开页面时勾选协议，提交正常；取消勾选后再提交，居然也能正常通过；反过来，如果页面加载时协议没有默认勾选，用户手动勾选后又取消，提交反而被拦截。
排查其实不复杂。在浏览器里打开控制台分别打印：
$('#agree').attr('checked'); $('#agree').prop('checked');会发现attr('checked')始终返回初始HTML里的checked字符串或undefined，完全不随用户点击变化；而prop('checked')每一次点击都正确反馈true/false。问题定位后，把判断改成$('#agree').prop('checked')，故障立刻消失。
这个例子里最有价值的不是那一行修复，而是排查思路：当checkbox状态判断出现“时灵时不灵”的怪症状时，优先怀疑attribute和property的同步问题，然后通过控制台同时打印两边的值做对比，基本五分钟就能定位。
3. 全选、反选与表格批量联动：一个完整的实战场景
3.1 页面结构与基础交互
后台系统里最常见的checkbox场景就是表格复选。一个订单管理列表，通常包含：表头的全选框、每行一行的复选框、一个批量操作按钮区。页面结构如下：
<table id="orderTable"> <thead> <tr> <th><input type="checkbox" id="checkAll" class="check-all"></th> <th>订单号</th> <th>金额</th> </tr> </thead> <tbody> <tr>var $checkAll = $('#checkAll'); var $rowChecks = $('.row-check'); function syncCheckAll() { var total = $rowChecks.length; var checkedCount = $rowChecks.filter(':checked').length; $checkAll.prop('checked', total > 0 && checkedCount === total); $checkAll.prop('indeterminate', checkedCount > 0 && checkedCount < total); } $checkAll.on('change', function () { var isChecked = $(this).prop('checked'); $rowChecks.prop('checked', isChecked); syncCheckAll(); }); $('#orderTable').on('change', '.row-check', syncCheckAll);syncCheckAll里有两个细节值得圈出来：一是判断全选要用“已勾选数等于总数”，同时排除总数0的情况，否则空表格会让表头处于选中态；二是indeterminate只在“部分选中”时置true，全选和全不选时都要置false。
indeterminate是checkbox的第三种视觉状态，看起来是一个横杠，既不是勾选也不是空着。它跟checked是完全独立的两个属性，可以同时存在。很多人误以为半选状态下的checkbox在表单提交时等于选中，其实不会——表单是否提交该控件只取决于checked，半选状态只是视觉提示。设置方式很简单：
$('#checkAll').prop('indeterminate', true);有了半选状态，用户在几十行数据里手动勾了几条，表头立刻显示“部分是选中”，交互反馈一下清晰很多。这个特性是很多后台系统没有做好的一环，但实现成本极低，建议都加上。
3.3 反选、批量操作按钮的动态禁用
反选逻辑本身不复杂，遍历一遍，取反就行：
$('#invertBtn').on('click', function () { $rowChecks.each(function () { this.checked = !this.checked; }); syncCheckAll(); updateToolbar(); });这里直接用this.checked = !this.checked，比$(this).prop('checked', !$(this).prop('checked'))少了一次jQuery包装，代码也干净。反选完成后记得调用syncCheckAll更新表头。
批量操作按钮的动态禁用是另一个容易被忽略的联动需求：一条都没选中时，删除按钮应该是disabled或灰色，一旦有选中行就恢复可用。实现：
function updateToolbar() { var count = $rowChecks.filter(':checked').length; $('#batchDelete').prop('disabled', count === 0); $('#selectedCount').text(count); }这样用户既能看到当前选中了几条，又能通过按钮状态预判是否可以做批量操作，整体体验会自然很多。这些逻辑拆成syncCheckAll和updateToolbar两个小函数，好处是任何位置改了选中状态，只要调用这两个函数就能保持一致，不需要在事件回调里各写一遍。
3.4 点击整行选中时的扩展处理
很多表格还支持点击行切换选中，这就要在tr上做一次委托：
$('#orderTable').on('click', 'tr[data-id]', function (e) { if (e.target.type === 'checkbox') { return; } var $rowCheck = $(this).find('.row-check'); $rowCheck.prop('checked', !$rowCheck.prop('checked')); syncCheckAll(); updateToolbar(); });开头的判断很关键：如果点击的目标本身就是checkbox，就直接返回，避免checkbox自己触发change之后，又被tr的click事件再翻一次，变成“点了反而没选中”。
这个扩展在真实后台里出现频率很高，很多运营用户喜欢点整行，你只给个checkbox他们会觉得“框太小了不好点”。
4. change事件与动态列表：委托监听的正确打开方式
4.1 为什么你的change事件在ajax渲染后失灵
动态表格里最常见的报错现象是：第一次进入页面，行checkbox的change事件一切正常；请求下一页数据、搜索刷新、或者点击某个按钮重新渲染tbody之后，行checkbox全部不听使唤了。
原因其实很直白。直接用$('.row-check').on('change', handler)绑定事件时，jQuery是给“当前存在的、匹配选择器的DOM元素”挨个绑定。ajax重新渲染tbody后，旧DOM被替换成新DOM，新DOM上根本没有绑过事件，自然没有反应。如果代码里没有统一管理，每次渲染后再重新绑一次，还会越绑越多，出现一次点击触发多次事件的并发症。
我见过有人为了避免重复绑定，在渲染前先off('change')，渲染后再on('change')，但是绑定的回调函数名和写错选择器，还是会漏绑或错绑。这类问题的正解只有一个：事件委托。
4.2 用on委托一个change监听解决全表格复选
事件委托的原理基于事件冒泡：事件从目标元素往上冒泡，委托容器上只绑一次监听，用selector参数去过滤目标元素。不管后代checkbox是什么时候生成的，只要满足选择器且冒泡到容器，就会被处理。
$('#orderTable').on('change', '.row-check', function () { syncCheckAll(); updateToolbar(); });这段代码只绑定了一次，但页面上无论怎么刷新tbody、怎么新增删减行，只要行checkbox还在orderTable里面，事件都能被捕捉。委托回去之后，动态渲染相关的的事件问题可以从根源上消失。
委托的容器选择也有讲究。容器应该在事件发生时稳定存在，并且离目标元素不要太高。不要一上来就委托document或body，整个页面所有checkbox的change都要先冒泡到顶层做一次过滤，控件一多会有不必要的性能损耗。比较稳的选择是表格本身、或者列表容器。如果连table都可能整体替换，那就再往上找一层稳定的父节点。
4.3 change与click的取舍
写checkbox交互时，常见到有人用click而不是change：
$('.row-check').on('click', function () { ... });click对checkbox本身当然也能触发，但它和change的语义有细微差别。change的触发时机是“状态改变后”，click则是“点击动作发生后”。通过键盘空格操作checkbox时，多数现代浏览器里click和change都会触发，但老旧的IE环境里，change事件对checkbox可能延迟到失焦才触发，所以老项目为了兼容，会习惯性用click替代change。
如果你维护的项目还在低版本IE上运营，沿用click也不是不行，但要清楚click的触发频率更高——用户快速反复点同一个checkbox，即使状态没有变化，click也会多次触发。而现在主流环境里，change是语义最准确、最不容易出问题的选择。我的建议很简单：能听change就听change，只有明确需要兼容极少见的老IE版本时，才退回去用click。
另外还有一个很常见的误区：通过prop('checked', true)在JS里修改状态，并不会触发change事件。比如全选框点击后，用代码把所有行checkbox的checked改成true，行的change事件根本不会一个个自动触发。这是正常的，不是“jQuery坏了”。如果你需要在那之后执行别的联动逻辑，应该在操作完后手动调用对应函数，或者用.trigger('change')显式触发。明确这一点，就不会写出“为什么全选之后每行的逻辑没跑”的疑问。
4.4 手动改状态不会触发change：一个隐藏的联动坑
承接上面说的手动修改不触发change，再展开说一个我实际踩过的坑。某个页面的行checkbox change事件里，除了同步全选框，还会做金额合计。结果用户全选时，合计金额没有变，单独勾选时反而正常。排查了很久才发现，全选用的是$rowChecks.prop('checked', true)，这一句不会触发任何change事件，合计函数压根没被调用。
正确做法是操作完状态后统一调用一次计算函数：
$checkAll.on('change', function () { $rowChecks.prop('checked', $(this).prop('checked')); calculateTotal(); syncCheckAll(); });这个原则可以推广到一切基于checkbox变化的下游逻辑：状态统一改、逻辑统一调，不要在生效路径上暗暗依赖“某个事件一定会触发”。项目里多人协作时尤其容易出这类问题，一个人改了状态的设置方式，另一个人还默默依赖旧行为，线上就出状况了。
5. 收集选中值：从遍历DOM到表单序列化的三种思路
5.1 最常见的map加get写法
批量删除、批量导出这类功能，最终要的是所有选中行的标识。最推荐、也最通用的写法是：
var ids = $('.row-check:checked').map(function () { return this.value; }).get(); // 结果示例：["1001", "1002", "1003"]map收集到的是一个可链式调用的jQuery对象，.get()把它转成普通数组。如果value是数字字符串，后台一般也认，但如果接口要求数字类型，可以顺手转换并过滤掉无效值：
var ids = $('.row-check:checked').map(function () { return Number(this.value) || 0; }).get().filter(function (v) { return v > 0; });这里有个很常见的坑：很多人会下意识写$('.row-check:checked').val()，以为它能返回所有选中项的值。但val()的语义始终是“第一个匹配元素的值”，checkbox场景下它只会返回第一条选中的值，静默丢掉后面所有项。数据量小的时候不容易察觉，一旦用户勾选多条，提交的数据就错误得莫名其妙。我建议团队代码规范里直接约定：checkbox取值一律用map加get，不要碰val。
5.2 serialize方法：表单里天然过滤未选项
如果这些checkbox本身就在一个大form里，而且name已经规划好，有一个更偷懒的方案：直接表单序列化。
<input type="checkbox" name="orderId" value="1001"> <input type="checkbox" name="orderId" value="1002">$('#bulkForm').serialize(); // "orderId=1001&orderId=1002"serialize()在序列化时会遵循浏览器“成功控件”规则，checkbox只有勾选状态才会被纳入结果，未勾选的天然被过滤，完全不需要你手动判断。还有serializeArray()，返回对象数组：
$('#bulkForm').serializeArray(); // [{name: "orderId", value: "1001"}, {name: "orderId", value: "1002"}]这个方案的好处是省去手动拼接参数，尤其是后面还跟着一堆搜索条件、分页参数时，直接从表单序列化就全带上了。缺点是name必须要和后端约定的参数一致，而且如果同一name的checkbox要做细分语义（比如有的是orderId有的是parentId），需要拆成多个name，或者案头额外用data-*记录类型信息。我一般建议：单纯收集checkbox选中值时用map加get；整个筛选区域要提交时用serialize。
5.3 什么时候应该用原生选择器
项目如果已经完全不需要兼容老IE，或者本来就在大量混用原生API，也可以用原生方式收集：
var ids = Array.from(document.querySelectorAll('.row-check:checked')).map(function (el) { return el.value; });这在性能上通常优于等价的jQuery选择器表达式，因为少了jQuery内部的选择器引擎、对象包装等开销。不过这种优势要在几千个checkbox规模下才体现得出来，日常后台列表用哪种都不会卡。选择原生更多是出于代码风格统一或减少对jQuery的依赖，没必要刻意为了性能去改。
还有一点值得提：无论是$('.row-check:checked')还是document.querySelectorAll('.row-check:checked')，选择器里的:checked都是一个状态过滤选择器，只是基于当前页面状态筛选，不存在“缓存了一个选中集合然后自动跟随变化”的说法。如果你把jQuery选中的结果存到一个变量里，之后交互又改变了勾选状态，这份结果并不会自动更新。记住“先选后查是静态快照”这一点，就不会写出用旧集合去判断新状态的逻辑了。
5.4 三个方案对比与容易踩的val()坑
把三种方案放在一起看：
| 方案 | 核心代码 | 适用场景 | 注意事项 |
|---|---|---|---|
| map + get | $('.row-check:checked').map(...).get() | 通用性最强，任意页面都可用 | 记得转数字时做过滤 |
| serialize | $('#bulkForm').serialize() | checkbox在表单内，且name规划好 | name必须与后端参数一致 |
| 原生选择器 | querySelectorAll('.row-check:checked') | 已混用原生API的项目 | 注意兼容范围 |
val()这个坑在前面已经强调过了，再补一个相关的细节：如果你真的需要“第一个选中项的值”，用val()没问题，很多人把它当成数组获取API才出问题。写代码的人和Review代码的人，看到val()用在checkbox集合上时，都应该下意识停下来想一下：这里到底要的是一个值还是所有值？这个简单的意识，能挡掉很大一部分后台数据错乱问题。
6. 老jQuery项目里的兼容性笔记：版本差异与常见误用
6.1 不同jQuery版本下checkbox的行为差异
老项目维护最怕的不是jQuery本身复杂，而是没有人愿意捋版本之间的差异。针对checkbox这个小功能点，几个关键版本的行为差异如下：
- jQuery 1.6之前：没有prop方法，官方推荐用attr操作checked。在那个时代，
attr('checked', true)是“能用”的，因为jQuery内部做了兼容。 - jQuery 1.6.0：引入prop，attr对checked这类布尔属性行为变化，一度出现“永远返回checked”的段子级bug，1.6.1做了修正。
- jQuery 1.6.1以后到3.x：prop成为操作checked的标准方式，attr读取checked只能拿到HTML初始attribute，不反映交互结果。
- jQuery 2.x之后：放弃老IE浏览器，API行为整体稳定，但用attr('checked')的老写法并不会自动“长对”，该改还是要改。
如果你的项目还在用1.6之前的版本，升级之前一定要先全局搜一遍attr('checked')和attr('checked', ...)类代码，不然线上很容易翻车。升级之后，再按“运行态全部用prop”的约定收归一遍，就能平稳过渡。
6.2 全局替换清单：把attr('checked')清理干净
给一个可以直接用来做代码审查的对照表：
| 误用写法 | 问题表现 | 推荐写法 |
|---|---|---|
| $cb.attr('checked') 判断状态 | 拿到的是HTML初始attribute，不随点击更新 | $cb.is(':checked') 或 $cb.prop('checked') |
| $cb.attr('checked', true) 运行时切换 | 改的不是浏览器渲染依赖的属性，状态可能不同步 | $cb.prop('checked', true) |
| $cb.removeAttr('checked') 重置 | 语义不明确，容易留下状态不一致隐患 | $cb.prop('checked', false) |
| $('.row-check:checked').val() 收集值 | 只返回第一个选中项的值 | map + get |
| $('.row-check').on('change') 动态渲染后失灵 | 新DOM没有绑定事件 | 容器上的on委托 |
这里重点说下removeAttr('checked')。有些人写“取消勾选”时会下意识用removeAttr，这在页面初始化的场景还能看，但在运行时用它重置状态，不会触发任何联动逻辑，还可能连带影响其他依赖attribute的行为。统一用prop('checked', false)看着没“删得干净”那么有仪式感，但它改的正是浏览器真正用到的property，结果才是可靠的。
另外，不要把“默认勾选”这个需求也用prop硬写。如果服务端要输出一个默认勾选的checkbox，直接在HTML模板里写checked attribute才是对的，因为那是初始状态。运行时的状态递进和初始状态，两个概念要分开。
6.3 联动逻辑的代码评审要点与团队约定
最后聊聊协作层面的东西。多人在一个老项目上迭代，checkbox这种小交互特别容易因为在不同文件里用不同风格而变得不可维护。我建议在团队里定几条明确的约定：
一是checkbox的运行态状态读取和设置统一走prop，见attr('checked')就改；二是所有表格复选联动都放到容器上做事件委托，不要在render函数里反复绑事件；三是只要有全选框，必须处理indeterminate半选态；四是所有“操作完checkbox后要同步的下游逻辑”统一抽成函数，显式调用，不依赖change事件自动触发。
这几条约定几乎不需要额外成本，却能在代码审查时快速筛出大量隐形bug。我在实际维护项目时发现，凡是线上出现过checkbox相关问题的模块，最后追根溯源，八成都能落到这四条里的某一条上。把它们写进团队规范，比临时救火要高效得多。
还有一个协作细节：同一个页面里，如果多个脚本文件都要操作同一批checkbox，最好只让一个文件负责状态联动，其他文件只读写数据或通过自定义事件通知。否则两个文件各写一套绑定，很容易出现“这个文件清了状态，那个文件又同时改了状态”的互相打架。把联动的入口收敛住，是处理这类问题最省心的方式。
最后说一个我养成的习惯。接手老项目时，第一件事是在代码库里全局搜attr("checked")和attr('checked')，搜出来多少条，基本上就能预判这个项目埋着多少checkbox相关的雷。逐文件改成prop之后，绝大多数“用户勾选状态时不时错乱”的历史问题，会在之后几周里慢慢消失，而不是等老板报bug才回头找。这个操作成本极低，收益却很直观——如果你正在维护jQuery项目，不妨今天就去试试。
