1. 概述
本文将介绍如何在 Thymeleaf 中为 HTML5 标签定义自定义属性。Thymeleaf 是一个模板引擎框架，它允许使用纯 HTML 页面来展示动态数据，同时保持良好的可读性和开发体验。
如果你对 Thymeleaf 基础或其与 Spring 的集成还不熟悉，可以先参考这篇入门文章：Thymeleaf 与 Spring MVC 集成指南。
2. HTML5 中的自定义属性
前端开发中，我们经常需要在 HTML 元素上附加一些额外信息，用于客户端逻辑处理。比如：
- 在表单的
input字段中存储元数据，供 AJAX 提交时使用 - 为表单字段绑定自定义校验规则或错误提示信息
✅ 解决这类需求的标准做法是使用 HTML5 的自定义数据属性（Custom Data Attributes），也就是以 data- 开头的属性：
<div data-user-id="123" data-role="student"></div>
这些属性不会影响页面渲染，但可以通过 JavaScript 轻松读取，非常适合做“轻量级数据挂载”。
⚠️ 注意：自定义属性必须以 data- 开头，否则不符合 HTML5 规范，可能导致不可预知的问题。
3. 在 Thymeleaf 中定义自定义 HTML 属性
Thymeleaf 原生支持生成带有动态值的 data-* 属性，语法非常直观：
th:data-<属性名>="<表达式>"
我们通过一个学生选课注册表单的例子来演示实际用法。
示例：带前端校验的课程选择表单
假设有一个简单的表单，用户需选择一门课程后提交：
<form action="#" th:action="@{/registerCourse}" th:object="${course}"
method="post" onsubmit="return validateForm();">
<span id="errormesg" style="color: red"></span>
<span style="font-weight: bold" th:text="${successMessage}"></span>
<table>
<tr>
<td>
<label th:text="#{msg.courseName}+': '"></label>
</td>
<td>
<select id="course" th:field="*{name}">
<option th:value="''" th:text="'Select'"></option>
<option th:value="'Mathematics'" th:text="'Mathematics'"></option>
<option th:value="'History'" th:text="'History'"></option>
</select>
</td>
</tr>
<tr>
<td><input type="submit" value="Submit" /></td>
</tr>
</table>
</form>
现在我们希望：当用户未选择课程直接提交时，显示一条本地化的错误提示。
解法：用 th:data-* 挂载校验消息
我们可以在 <select> 标签上通过 th:data-validation-message 添加自定义属性，值从资源文件中读取：
<select
id="course"
th:field="*{name}"
th:data-validation-message="#{msg.courseName.mandatory}">
其中 #{msg.courseName.mandatory} 是国际化消息，例如在 messages.properties 中定义为：
msg.courseName.mandatory=Please select a course.
前端校验逻辑
接下来，用一段简单的 JavaScript 读取该属性并提示用户：
function validateForm() {
var e = document.getElementById("course");
var value = e.options[e.selectedIndex].value;
if (value == '') {
var error = document.getElementById("errormesg");
error.textContent = e.getAttribute('data-validation-message');
return false;
}
return true;
}
✅ 这样做的好处：
- 错误信息由后端统一管理（i18n 支持）
- 前端无需硬编码提示语
- 结构清晰，易于维护
扩展用法
你完全可以为同一个元素添加多个 data-* 属性，Thymeleaf 都支持：
<input
type="text"
th:data-max-length="${maxLength}"
th:data-validation-rule="required"
th:data-error-msg="#{msg.field.required}" />
生成的 HTML 类似：
<input
type="text"
data-max-length="50"
data-validation-rule="required"
data-error-msg="This field is required." />
简单粗暴，但非常实用。
4. 总结
Thymeleaf 对 HTML5 自定义属性的支持非常友好，尤其是结合 th:data-* 语法，能轻松实现前后端数据传递的“隐形桥梁”。
无论是表单校验、动态配置还是行为绑定，这种模式都能有效解耦逻辑与模板，提升开发效率。
✅ 推荐场景：
- 国际化错误提示
- JS 行为驱动的元数据注入
- 动态配置前端组件参数
代码示例已托管至 GitHub：https://github.com/eugenp/tutorials/tree/master/spring-web-modules/spring-thymeleaf-2
建议集合，踩坑少走弯路。