Thymeleaf 核心语法详解

一、常用标签

标签	作用	示例
th:id	替换id	<input th:id="${user.id}"/>
th:text	文本替换	<p text:="${user.name}">bigsai</p>
th:utext	支持html的文本替换	<p utext:="${htmlcontent}">content</p>
th:object	替换对象	<div th:object="${user}"></div>
th:value	替换值	<input th:value="${user.name}" >
th:each	迭代	<tr th:each="student:${user}" >
th:href	替换超链接	<a th:href="@{index.html}">超链接</a>
th:src	替换资源	<script type="text/javascript" th:src="@{index.js}"></script>

二、简单表达式

表达式	名称	核心作用	适用场景
`${...}`	变量表达式	直接获取上下文（Model/Request）中的变量值	最常用，获取后端传递的普通变量、对象属性
`*{...}`	选择变量表达式	基于`th:object`选定的对象，访问其内部属性	简化对象属性的重复书写，配合`th:object`使用
`#{...}`	消息表达式	读取国际化（i18n）配置文件中的文本	多语言页面、统一文案管理
`@{...}`	链接 URL 表达式	处理页面链接（自动补全项目上下文路径）	超链接、CSS/JS 引用、表单提交地址
`~{...}`	片段表达式	引用 / 复用页面中的公共代码片段	抽取页眉、页脚、导航栏等公共组件

1. `${...}` 变量表达式（最常用）

核心作用 ：直接访问 Spring MVC Model、Request、Session 等上下文中的变量，相当于 JSP 的${}。

java 复制代码

<!-- 后端：req.setAttribute("username", "张三"); -->
<p th:text="${username}"></p>  <!-- 渲染为：<p>张三</p> -->

<!-- 访问对象属性 -->
<!-- 后端：req.setAttribute("user", new User("张三", 25)); -->
<p th:text="${user.name}"></p>  <!-- 渲染：张三 -->
<p th:text="${user.age}"></p>   <!-- 渲染：25 -->

<!-- 调用方法、做运算 -->
<p th:text="${#strings.toUpperCase(user.name)}"></p>  <!-- 转大写：张三 → 张三（中文不变） -->
<p th:text="${user.age + 1}"></p>  <!-- 运算：25 → 26 -->

2. `*{...}` 选择变量表达式

核心作用 ：必须配合th:object使用，先选定一个根对象，后续*{...}直接访问该对象的属性，简化代码。

html 复制代码

<!-- 不使用*{...}的写法（冗余） -->
<div th:object="${user}">
  <p th:text="${user.name}"></p>
  <p th:text="${user.age}"></p>
</div>

<!-- 使用*{...}的简化写法（推荐） -->
<div th:object="${user}">
  <p th:text="*{name}"></p>  <!-- 等价于${user.name} -->
  <p th:text="*{age}"></p>   <!-- 等价于${user.age} -->
</div>

<!-- 无th:object时，等价于${...} -->
<p th:text="*{user.name}"></p>  <!-- 效果同${user.name} -->

3. `#{...}` 消息表达式（国际化）

核心作用 ：读取resources下的国际化配置文件（如messages.properties），实现多语言切换。

1、配置文件messages.properties

XML 复制代码

user.name=用户名
user.age=年龄

2、页面中使用：

html 复制代码

<label th:text="#{user.name}"></label>  <!-- 渲染：用户名 -->
<label th:text="#{user.age}"></label>   <!-- 渲染：年龄 -->

`4.@{...}` 链接 URL 表达式

核心作用 ：自动补全项目的上下文路径（如/demo），避免硬编码；支持动态参数拼接。

html 复制代码

<!-- 静态链接（自动补全上下文） -->
<a th:href="@{/user/list}">用户列表</a>
<!-- 项目上下文为/demo时，渲染为：<a href="/demo/user/list">用户列表</a> -->

<!-- 带参数的动态链接 -->
<a th:href="@{/user/detail(id=${user.id}, name=${user.name})}">用户详情</a>
<!-- 渲染为：<a href="/demo/user/detail?id=1&name=张三">用户详情</a> -->

<!-- 相对路径、CSS/JS引用 -->
<link th:href="@{/css/style.css}" rel="stylesheet">
<script th:src="@{/js/main.js}"></script>

5. `~{...}` 片段表达式（代码复用）

核心作用：抽取页面中的公共片段（如页眉、页脚），在其他页面中引用，减少重复代码。

1、定义公共片段（footer.html）：

html 复制代码

<footer th:fragment="copy">
  <p>© 2025 我的网站 版权所有</p>
</footer>

2、引用片段（其他页面）

html 复制代码

<!-- 插入片段 -->
<div th:insert="~{footer :: copy}"></div>
<!-- 替换片段（用片段替换当前标签） -->
<div th:replace="~{footer :: copy}"></div>
<!-- 包含片段（仅包含，不替换标签） -->
<div th:include="~{footer :: copy}"></div>

3、带参数的片段

html 复制代码

<!-- 定义带参片段 -->
<div th:fragment="header(title)">
  <h1 th:text="${title}"></h1>
</div>
<!-- 传参引用 -->
<div th:replace="~{header :: header('首页')}"></div>

Thymeleaf 3.0+ 引入的片段表达式 (Fragment Expression) ，核心用于引用、复用页面片段 （如页眉、页脚、公共组件），配合 th:insert / th:replace 使用。

语法格式	含义	适用场景
~{templatename}	引入整个模板文件的所有内容	快速引入完整页面、布局模板
~{templatename :: selector}	引入指定模板中，匹配选择器的片段	跨模板引用公共片段（最常用）
~{::selector} / ~{this::selector}	引入当前模板内匹配选择器的片段	同一页面内复用片段、模块化布局

指令	行为	示例效果
th:insert	将片段内容插入到当前标签内部（保留当前标签）	当前 div 包裹片段内容
th:replace	用片段内容替换当前标签（删除当前标签）	片段标签直接替换原 div

html 复制代码

<!-- 原片段 -->
<p th:fragment="msg">Hello Thymeleaf</p>

<!-- th:insert 效果 -->
<div th:insert="~{common :: msg}"></div>
<!-- 渲染结果：<div><p>Hello Thymeleaf</p></div> -->

<!-- th:replace 效果 -->
<div th:replace="~{common :: msg}"></div>
<!-- 渲染结果：<p>Hello Thymeleaf</p> -->

完整实战

步骤 1：创建片段文件（templates/common/navbar.html）

html 复制代码

<body>
<nav th:fragment="nav(userRole)">
    <ul>
        <li><a href="/">首页Index</a></li>
        <li th:if="${userRole == 'admin'}"><a href="/admin">管理后台</a></li>
        <li><a href="/profile">个人中心</a></li>
    </ul>
</nav>
</body>

步骤 2：在目标页面引用（templates/common/my.html）

html 复制代码

<body>
<!-- 引入 navbar 片段，传递用户角色参数 -->
<div th:replace="~{common/navbar :: nav(${userRole})}"></div>

<div class="container">
    <main><h1>页面主体内容</h1></main>
</div>

</body>

后端传递 userRole = "admin" 时，页面会渲染包含 "管理后台" 的导航栏；传递 userRole = "user" 时，不显示管理后台入口。

Thymeleaf 核心语法详解

一、常用标签

二、简单表达式

1. ${...} 变量表达式（最常用）

2. *{...} 选择变量表达式

3. #{...} 消息表达式（国际化）

4.@{...} 链接 URL 表达式

5. ~{...} 片段表达式（代码复用）

完整实战

1. `${...}` 变量表达式（最常用）

2. `*{...}` 选择变量表达式

3. `#{...}` 消息表达式（国际化）

`4.@{...}` 链接 URL 表达式

5. `~{...}` 片段表达式（代码复用）