Thymeleaf使用手册

什么是Thymeleaf？

Thymeleaf是一种Java服务器端模板引擎，用于构建Web应用程序的用户界面。它允许开发人员将动态数据与HTML模板结合，以生成最终的Web页面。Thymeleaf的语法简单且易于理解，它可以与各种Java框架（如Spring）无缝集成，使开发人员能够轻松创建动态、可扩展的Web应用。

Thymeleaf的功能

• 整合到@Controller，可以像jsp一样， 在@Controller中指向模板文件
• 允许你在template文件中使用SPEL表达式
• 模板上的表单可与你后端的bean对象进行属性绑定
• 通过Spring管理的消息文件显示国际化消息
• 使用Spring的资源分辨机制去解析你的template文件。

Thymeleaf支持的6种模板模式

• HTML
• XML
• TEXT
• JAVASCRIPT
• CSS
• RAW 其中HTML和XML是标记语音，TEXT、JAVASCRIPT、CSS是文本语言，RAW是特殊语言

语法

名称空间

xmlns:th="http://www.thymeleaf.org"

标准表达式语法

Thymeleaf模板引擎支持多种表达式：

• 变量表达式：${...}
• 选择变量表达式：*{...}
• 链接表达式：@{...}
• 国际化表达式：#{...}
• 片段引用表达式：~{...}

变量表达式

• 获取变量、对象表达式

${person.lastName}

• Thymeleaf内置的基本对象
  • #ctx：上下文对象
  • #vars：上下文变量
  • #locale：上下文的语言环境
  • #request：HttpServletRequest对象（仅在Web应用中可用）
  • #response：HttpServletResponse对象（仅在Web应用中可用）
  • #session：HttpSession对象（仅在Web应用中可用）
  • #servletContext：ServletContext对象（仅在Web应用中可用）

${#session.getAttribute('map')}
${session.map}

• Thymeleaf内置一些工具对象，各个工具对象都提供了大量的api。
  • strings：字符串工具对象
  • numbers：数字工具对象
  • bools：布尔工具对象
  • arrays：数组工具对象
  • lists/sets：List/Set集合工具对象
  • maps：Map集合工具对象
  • dates：日期工具对象

${#string.equals("chenzhuowen",name)}

选择变量表达式

选择变量表达式一般与th:object配置使用，使用th:object存储一个对象后，我们可以使用选择变量表达式*{...}获取该对象中的属性。

<div th:object=${session.user}>
	<p th:text=*{firstname}>firstname</p>
</div>

链接表达式

不管是静态资源引用还是form表达的请求，所有链接都可以使用链接表达式@{...}

链接表达式分为：

• 无参请求：@{/url}
• 有参请求：@{/uri(k1=v1,k2=v2)}

<link th:href="@{/www.baidu.com}"/>

国际化表达式

国际化表达式一般用于国际化场景

<p th:text='#{msg}'>msg</p>

片段引用表达式

片段引用表达式，用于在模板页面中引用其他的模板片段，支持以下两种方式：

• ~{templateName::fragmentname}
• ~{templateName::#id} 其中templateName为模板名。fragmentname为片段名，通过th:fragmentname声明定义代码块。id为HTML的id选择器。

Thymeleaf模板th属性

属性	作用	示例
th:id	替换标签中的id值	<p id="id" th:id="${id}"></p>‘
th:text	替换标签中的text属性,自动转义特殊字符
th:utext	替换标签中的text属性，不转义特殊字符
th:object	选择对象，用于临时存储对象，在子标签中使用选择表达式获取对象属性
th:value	替换标签中的value属性
th:with	局部变量赋值运行。通过该标签可以定义并赋值一个局部变量，局部变量可以在其他地方使用变量表达式引用
th:style	设置样式，替换标签中的style属性
th:onclick	点击事件，替换标签的onclick属性
th:each	遍历集合，支持iterable、Map、数组等
th:if	根据条件判断是否展示该标签
th:unless	和th:if相反，满足条件时不显示
th:switch	与java的switch、case语法相似，根据条件显示不同的标签。通常与th:case一起使用
th:fragment	用于定义一段可被引用或包含的模板片段
th:insert	将使用th:fragment定义的模板片段（包含标签）插入到当前标签中
th:replace	将使用th:fragment定义的模板片段替换当前标签
th:include	将使用th:fragment定义的模板片段（不包含标签）插入到当前标签中
th:select	针对选择框标签使用，当属性的条件满足时选中选择框
th:src	替换标签中的src属性
th:inline	内联属性，可以取值为text、none、javascript。当在<script>标签配置时，js代码可以通过标准表达式获取到java对象
th:action	替换表单提交地址action属性

引用公共页面

通常页面中有很多重复的内容可以抽象成公共的代码块，这些公共代码块可以使用Thymeleaf提供的功能去引用，有下面3种方式去引用Thymeleaf。

• th:insert：将模板片段（包含标签）插入到当前标签
• th:replace：将模板片段（包含标签）替换当前标签
• th:include：将模板片段（不含标签）插入到当前标签

通过这个属性的属性值使用以下两种方式表示：

• ~{templatename::selector}：模板名::选择器，id选择器#id
• ~{templatename::fragmentname}：模板名::片段名

模板也支持传递参数。要传递参数，需要在定义模板时定义入参。在使用参数时，通过变量表达式引用。

• 定义模板变量

<!--th:insert 片段名引入-->
<div th:insert="commons::fragment-name(var1='insert-name',var2='insert-name2')"></div>
<!--th:insert id 选择器引入-->
<div th:insert="commons::#fragment-id(var1='insert-id',var2='insert-id2')"></div>

• 传入模板变量、使用变量

<!--使用 var1 和 var2 声明传入的参数，并在该片段中直接使用这些参数 -->
<div th:fragment="fragment-name(var1,var2)" id="fragment-id">
    <p th:text="'参数1:'+${var1} + '-------------------参数2:' + ${var2}">...</p>
</div>

SpringBoot集成Thymeleaf

SpringBoot默认推荐使用Thymeleaf，引入相关依赖后，自动配置类ThymeleafAutoConfiguration会自动完成相关配置。

要在SpringBoot种集成Thymeleaf，需要完成以下三步：

1. 引入相关依赖。
2. 创建Thymeleaf模板文件目录，添加模板到指定目录。
3. 在代码中使用Thymeleaf。

1. 引入依赖

<!--Thymeleaf 启动器-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

2. 根据情况修改Thymeleaf的配置

在application.yml下修改Thymeleaf的配置，配置前缀为spring.thymeleaf，对应的java配置类为ThymeleafAutoConfiguration，常用配置如下：

//模板默认编码
private static final Charset DEFAULT_ENCODING = StandardCharsets.UTF_8;
//模板文件路径前缀
public static final String DEFAULT_PREFIX = "classpath:/templates/";
//模板文件文件名后缀
public static final String DEFAULT_SUFFIX = ".html";
//模板引擎模式，值参考TemplateMode枚举值
private String mode = "HTML";

3. 创建一个模板文件，放入到模板文件目录

• 目录地址：resource/template/
• 文件名：helloworld.html
• html文件头添加命名空间：xmlns:th="http://www.thymeleaf.org"

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
<p th:text="'hello world'+${name}">hello world nobody</p>
</body>
</html>

4. 编写controller方法，返回模板页面

• 通过Model模型对象，向前端传输数据。
• 返回模板名称，springmvc会自动处理，完成数据绑定与页面渲染。

@Controller
public class ThymeleafController {

    @GetMapping(path = "/helloworld")
    public String helloWorld(Model model, @RequestParam("name") String name) {
        model.addAttribute("name", name);
        return "helloworld";
    }
}