Thymeleaf中th:checked生效但th:field绑定复选框失败如何解决

问题根因 #

• 表单内重复定义了两个name、id完全相同的permitirAcesso复选框：HTML规范要求id全局唯一，同name的复选框提交时会传递多个参数值，Spring MVC做布尔类型绑定时遇到多值参数会触发转换失败，直接导致双向绑定逻辑异常。
• 手动给th:field绑定的标签写name、id属性会干扰Thymeleaf的内置渲染逻辑：th:field处理布尔类型复选框时，会自动生成id、name、value属性，还会自动追加一个_字段名的隐藏域解决复选框未勾选时不传值的问题，手动写重复属性会打断这个流程。
• 实体类实现UserDetails接口时重写的isEnabled()方法直接返回permitirAcesso字段值，部分版本的Thymeleaf Spring模块做JavaBean属性解析时，会优先匹配is开头的属性，把enabled属性和permitirAcesso属性的解析逻辑混淆，进一步导致绑定失败。

修复步骤 #

1. 直接删除用th:checked绑定的第二个重复复选框，同一个布尔字段在表单里只需要保留一个输入控件，不需要重复定义。
2. 修正复选框代码，删掉手动写的name、id属性，交给Thymeleaf自动生成，正确写法：

   <input type="checkbox" th:field="*{permitirAcesso}" />
   

3. 调整实体类逻辑：如果业务没有强要求，不要把isEnabled()的返回值直接和permitirAcesso字段绑定，建议单独新增enabled字段存储账号启用状态，从根源上避免JavaBean属性解析冲突。如果暂时不想修改实体结构，可以在绑定的时候显式指定value属性避免类型识别偏差：

   <input type="checkbox" th:field="*{permitirAcesso}" th:value="true"/>
   

4. 不要手动添加和permitirAcesso相关的隐藏域，Thymeleaf渲染th:field复选框时会自动生成对应的隐藏提交标签，手动添加会造成参数重复。

校验标准 #

页面渲染完成后查看网页源码，正常的绑定代码会生成如下结构：

<input type="checkbox" id="permitirAcesso" name="permitirAcesso" value="true" checked="checked"/>
<input type="hidden" name="_permitirAcesso" value="on"/>

• 字段值为true时，checkbox标签会自动带上checked="checked"属性，不需要额外写th:checked
• 提交表单时，勾选状态传permitirAcesso=true&_permitirAcesso=on，未勾选状态只传_permitirAcesso=on，Spring会自动将未勾选状态转换为false绑定到实体字段

内容的提问来源于stack exchange，提问作者KenobiBastila