当前位置：首页 > news >正文

Thymeleaf 表单绑定与验证详解

news 2025/7/18 5:47:43

关键词：Thymeleaf、Spring Boot、表单绑定、数据绑定、后端验证、@Valid、BindingResult、错误提示

✅ 引言

在 Web 开发中，表单提交与数据验证是用户交互中最常见的场景之一。Thymeleaf 作为 Spring Boot 默认支持的模板引擎，提供了强大的表单绑定机制和错误提示功能，能够无缝对接 Spring MVC 的后端验证逻辑。

本文将围绕 Thymeleaf 表单绑定与验证 进行系统讲解，涵盖：

表单绑定（Form Binding）
后端验证（Validation）
错误提示展示
使用 @Valid 和 BindingResult 处理验证失败
国际化错误信息支持

并为每个小节提供完整的 HTML 页面 + Spring Boot 后端 Java 示例代码，帮助你掌握 Thymeleaf 在真实项目中的高级用法。

📌 一、表单绑定基础：使用 `th:object` 与 `th:field`

1.1 定义模型类（User）

// User.java
public class User {private String name;private String email;private Integer age;// Getter & Setter
}

1.2 HTML 表单绑定（form.html）

<!-- templates/form.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><meta charset="UTF-8"><title>用户注册</title>
</head>
<body><h2>注册用户</h2><form th:action="@{/submit}" th:object="${user}" method="post"><label>姓名：<input type="text" th:field="*{name}" /></label><br><br><label>邮箱：<input type="email" th:field="*{email}" /></label><br><br><label>年龄：<input type="number" th:field="*{age}" /></label><br><br><button type="submit">提交</button></form></body>
</html>

1.3 控制器接收数据（UserController.java）

@Controller
public class UserController {@GetMapping("/register")public String showForm(Model model) {model.addAttribute("user", new User());return "form";}@PostMapping("/submit")public String submitForm(@ModelAttribute("user") User user) {System.out.println("接收到的用户：" + user);return "redirect:/success";}
}

📌 输出效果：

页面加载时显示空表单。
提交后，控制台输出类似：

接收到的用户：User{name='张三', email='zhangsan@example.com', age=25}

📌 二、表单验证：使用 Bean Validation 注解

2.1 修改模型类添加验证规则（User.java）

import javax.validation.constraints.*;public class User {@NotBlank(message = "姓名不能为空")private String name;@Email(message = "请输入有效的邮箱地址")private String email;@Min(value = 0, message = "年龄不能小于0")@Max(value = 120, message = "年龄不能超过120")private Integer age;// Getter & Setter
}

2.2 控制器中使用 `@Valid` 验证

@PostMapping("/submit")
public String submitForm(@Valid @ModelAttribute("user") User user,BindingResult result,Model model) {if (result.hasErrors()) {return "form"; // 返回表单页面，显示错误}// 正常处理逻辑return "redirect:/success";
}

📌 三、在 Thymeleaf 中显示验证错误信息

3.1 修改 form.html 显示字段错误信息

<form th:action="@{/submit}" th:object="${user}" method="post"><label>姓名：<input type="text" th:field="*{name}" /><span th:if="${#fields.hasErrors('name')}" th:errors="*{name}" style="color:red"></span></label><br><br><label>邮箱：<input type="email" th:field="*{email}" /><span th:if="${#fields.hasErrors('email')}" th:errors="*{email}" style="color:red"></span></label><br><br><label>年龄：<input type="number" th:field="*{age}" /><span th:if="${#fields.hasErrors('age')}" th:errors="*{age}" style="color:red"></span></label><br><br><button type="submit">提交</button></form>

📌 效果说明：

若未填写姓名，会显示红色错误提示：“姓名不能为空”
邮箱格式错误，提示“请输入有效的邮箱地址”
年龄不在 0~120 范围内，提示“年龄不能小于0”或“年龄不能超过120”

📌 四、全局错误信息与非字段错误

4.1 添加自定义业务验证逻辑

@PostMapping("/submit")
public String submitForm(@Valid @ModelAttribute("user") User user,BindingResult result,Model model) {if (user.getEmail().contains("blocked")) {result.rejectValue("email", "error.email", "该邮箱被禁止注册");}if (result.hasErrors()) {return "form";}return "redirect:/success";
}

4.2 显示全局错误信息

<div th:if="${#fields.hasGlobalErrors()}"><p style="color:red" th:each="error : ${#fields.globalErrors}" th:text="${error}"></p>
</div>

📌 示例输出：

该邮箱被禁止注册

📌 五、国际化错误信息支持（i18n）

5.1 创建消息属性文件

src/main/resources/messages.properties
src/main/resources/messages_zh_CN.properties

示例内容（messages_zh_CN.properties）：

NotBlank.user.name=姓名不能为空
Email.user.email=请输入有效的邮箱地址
Min.user.age=年龄不能小于0
Max.user.age=年龄不能超过120
error.email=该邮箱被禁止注册

5.2 Thymeleaf 自动识别国际化信息

无需额外配置，Thymeleaf 会根据浏览器语言自动选择对应的消息文件。

✅ 总结

功能	属性/注解	用途
表单绑定	`th:object`, `th:field`	绑定模型对象到表单字段
数据验证	`@NotBlank`, `@Email`, `@Min`, `@Max`	校验字段合法性
验证结果	`@Valid`, `BindingResult`	接收验证结果并处理
错误提示	`th:errors`, `th:if`	显示字段错误信息
全局错误	`rejectValue`, `globalErrors`	处理非字段级错误
国际化	`messages_*.properties`	支持多语言错误提示