Spring 整合 Thymeleaf 模板引擎

2023-12-02

教程

1、概览

Thymeleaf 是一个 Java 模板引擎，用于处理和创建 HTML、XML、JavaScript、CSS 和文本。

本文将带你了解如何在 Spring 和 Spring Boot 应用中整合、使用 Thymeleaf。

该库具有极高的可扩展性，其天然的模板功能可以确保在没有后端的情况下制作模板原型。与其他流行的模板引擎（如 JSP）相比，这使得开发速度非常快。

2、Spring 整合 Thymeleaf

首先，来看看与 Spring 整合所需的配置。这需要使用 thymeleaf-spring 库。

在 Maven POM 文件中添加以下依赖：

<dependency>
    <groupId>org.thymeleaf</groupId>
    <artifactId>thymeleaf</artifactId>
    <version>3.1.2.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.thymeleaf</groupId>
    <artifactId>thymeleaf-spring5</artifactId>
    <version>3.1.2.RELEASE</version>
</dependency>

注意，对于 Spring 4，必须使用 thymeleaf-spring4，而不是 thymeleaf-spring5。

通过 SpringTemplateEngine 类执行所有配置步骤。

可以在 Java 配置中将该类配置为 bean：

@Bean
@Description("Thymeleaf Template Resolver")
public ServletContextTemplateResolver templateResolver() {
    ServletContextTemplateResolver templateResolver = new ServletContextTemplateResolver();
    templateResolver.setPrefix("/WEB-INF/views/");
    templateResolver.setSuffix(".html");
    templateResolver.setTemplateMode("HTML5");

    return templateResolver;
}

@Bean
@Description("Thymeleaf Template Engine")
public SpringTemplateEngine templateEngine() {
    SpringTemplateEngine templateEngine = new SpringTemplateEngine();
    templateEngine.setTemplateResolver(templateResolver());
    templateEngine.setTemplateEngineMessageSource(messageSource());
    return templateEngine;
}

templateResolver Bean 的 prefix 和 suffix 属性分别表示视图页面在 webapp 目录中的位置及其文件扩展名。

Spring MVC 的 ViewResolver 接口将 Controller 返回的视图名称映射为实际的视图对象。ThymeleafViewResolver 实现了 ViewResolver 接口，用于根据视图名称确定要渲染的 Thymeleaf 视图。

整合的最后一步是将 ThymeleafViewResolver 添加为一个 Bean：

@Bean
@Description("Thymeleaf View Resolver")
public ThymeleafViewResolver viewResolver() {
    ThymeleafViewResolver viewResolver = new ThymeleafViewResolver();
    viewResolver.setTemplateEngine(templateEngine());
    viewResolver.setOrder(1);
    return viewResolver;
}

3、Spring Boot 整合 Thymeleaf

Spring Boot 通过添加 spring-boot-starter-thymeleaf 依赖，为 Thymeleaf 提供了自动配置功能：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
    <version>2.3.3.RELEASE</version>
</dependency>

无需明确配置。默认情况下，HTML 文件应放在 resources/templates 位置。

4、渲染 Message Source（Properties 文件）中的值

可以使用 th:text="#{key}" 标签属性来渲染 Properties 文件中的值。

为此，需要将 Properties 文件配置为 messageSource Bean：

@Bean
@Description("Spring Message Resolver")
public ResourceBundleMessageSource messageSource() {
    ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
    messageSource.setBasename("messages");
    return messageSource;
}

渲染 welcome.message 的 KEY 值：

<span th:text="#{welcome.message}" />

5、渲染 Model 属性

5.1、示例属性

使用 th:text="${attributename}" 标签属性来渲染 Model 属性。

在 Controller 类中添加一个名为 serverTime 的 Model 属性：

model.addAttribute("serverTime", dateFormat.format(new Date()));

渲染 serverTime 属性：

Current time is <span th:text="${serverTime}" />

5.2、集合属性

如果 Model 属性是一个对象集合，可以使用 th:each 标签属性对其进行遍历。

定义一个包含 id 和 name 两个字段的 Student Model 类：

public class Student implements Serializable {
    private Integer id;
    private String name;
    // 标准的 GET / SET
}

在 Controller 类中添加一个 List<Student> 作为 Model 属性：

List<Student> students = new ArrayList<Student>();
// 构建 students 的逻辑 ...
model.addAttribute("students", students);

最后，遍历 students 列表并渲染所有字段值：

<tbody>
    <tr th:each="student: ${students}">
        <td th:text="${student.id}" />
        <td th:text="${student.name}" />
    </tr>
</tbody>

6、条件分支

6.1、`if` 和 `unless`

使用 th:if="${condition}" 属性在满足条件时渲染视图的某个部分。如果不满足条件，使用 th:unless="${condition}" 属性来渲染视图的某个部分。

在 Student model 中添加一个 gender 字段：

public class Student implements Serializable {
    private Integer id;
    private String name;
    private Character gender;
    
    // 标准的 GET 、SET 方法
}

假设这个字段有两个枚举值（M 或 F）来表示学生的性别。

如果想渲染 “Male” 或 “Female” 字样，而不是单个字符，可以使用 th:if 来实现：

<td>
    <span th:if="${student.gender} == 'M'" th:text="Male" /> 
    <span th:unless="${student.gender} == 'M'" th:text="Female" />
</td>

6.2、 `switch` 和 `case`

使用 th:switch 和 th:case 属性，通过 switch 语句结构有条件地渲染内容。

使用 th:switch 和 th:case 属性重写之前的代码：

<td th:switch="${student.gender}">
    <span th:case="'M'" th:text="Male" /> 
    <span th:case="'F'" th:text="Female" />
</td>

7、处理用户输入

可以使用 th:action="@{url}" 和 th:object="${object}" 属性来处理表单输入。使用 th:action 提供表单 action URL，使用 th:object 指定要将提交的表单数据绑定到的对象。

单个字段使用 th:field="{name}" 属性映射，其中 name 是对象的匹配属性。

对于 Student 类，可以创建一个输入表单：

<form action="#" th:action="@{/saveStudent}" th:object="${student}" method="post">
    <table border="1">
        <tr>
            <td><label th:text="#{msg.id}" /></td>
            <td><input type="number" th:field="*{id}" /></td>
        </tr>
        <tr>
            <td><label th:text="#{msg.name}" /></td>
            <td><input type="text" th:field="*{name}" /></td>
        </tr>
        <tr>
            <td><input type="submit" value="Submit" /></td>
        </tr>
    </table>
</form>

在上述代码中，/saveStudent 是表单 action URL，student 是保存所提交表单数据的对象。

saveStudent 方法处理表单提交：

@RequestMapping(value = "/saveStudent", method = RequestMethod.POST)
public String saveStudent(Model model, @ModelAttribute("student") Student student) {
    // 处理输入数据的逻辑
}

@RequestMapping 注解将 Controller 方法与表单中提供的 URL 映射。注解方法 saveStudent() 对提交的表单执行所需的处理。最后，@ModelAttribute 注解将表单字段与 student 对象绑定。

8、渲染 Validation 验证错误

可以使用 #fields.hasErrors() 函数检查某个字段是否存在任何验证错误。还可以使用 #fields.errors() 函数渲染特定字段的错误。这两个函数的输入参数都是字段名称。

迭代并渲染表单中每个字段错误：

<ul>
    <li th:each="err : ${#fields.errors('id')}" th:text="${err}" />
    <li th:each="err : ${#fields.errors('name')}" th:text="${err}" />
</ul>

上述函数可以不使用字段名，而是使用通配符 * 或常量 all 来表示所有字段。使用 th:each 属性来遍历每个字段可能存在的多个错误。

下面是使用通配符重写的 HTML 代码：

<ul>
    <li th:each="err : ${#fields.errors('*')}" th:text="${err}" />
</ul>

下例使用了常量 all：

<ul>
    <li th:each="err : ${#fields.errors('all')}" th:text="${err}" />
</ul>

同样，也可以使用 global 常量在 Spring 中渲染全局错误。如下：

<ul>
    <li th:each="err : ${#fields.errors('global')}" th:text="${err}" />
</ul>

此外，还可以使用 th:errors 属性来渲染错误信息。

使用 th:errors 属性重写之前在表单中渲染错误的代码：

<ul>
    <li th:errors="*{id}" />
    <li th:errors="*{name}" />
</ul>

9、格式化和转换

使用双括号语法 {{}} 来格式化要渲染的数据。这使用了在 conversionService Bean 中为该类型字段配置的 formatters。

格式化 Student 类中的 name 字段：

<tr th:each="student: ${students}">
    <td th:text="${{student.name}}" />
</tr>

上述代码使用了 NameFormatter 类。该类通过 WebMvcConfigurer 接口中的 addFormatters() 方法进行配置。如下：

@Configuration 类继承了 WebMvcConfigurerAdapter 类：

@Configuration
public class WebMVCConfig extends WebMvcConfigurerAdapter {
    // ...
    @Override
    @Description("Custom Conversion Service")
    public void addFormatters(FormatterRegistry registry) {
        registry.addFormatter(new NameFormatter());
    }
}

NameFormatter 类实现了 Spring Formatter 接口。

还可以使用 #conversions 来转换对象。其语法是 #conversions.convert(Object, Class)，其中 Object 将转换为 Class 类型。

去掉 student 对象 percentage 字段的小数部分（转换为 Integer）：

<tr th:each="student: ${students}">
    <td th:text="${#conversions.convert(student.percentage, 'Integer')}" />
</tr>

10、总结

本文介绍了如何在 Spring 应用中整合和使用 Thymeleaf。还介绍了如何渲染字段、处理表单输入、渲染验证错误和转换数据。

Ref：https://www.baeldung.com/thymeleaf-in-spring-mvc