Spring Boot 整合 Thymeleaf 生成 HTML 页面教学

Thymeleaf 是一款优秀的服务器端 Java 模板引擎，能与 Spring Boot 无缝整合，快速生成动态 HTML 页面。本教学从环境搭建到项目实战，带你逐步掌握 Thymeleaf 核心用法。

一、环境搭建

1. 技术栈要求

JDK：1.8 及以上

Spring Boot：2.x 或 3.x（本教学以 2.7.x 为例）

开发工具：IntelliJ IDEA（或 Eclipse）

2. 创建 Spring Boot 项目

方式一：通过 Spring Initializr（推荐）

打开 Spr ing I nitia lizr 官网。

配置项目信息：

- Group：自定义包名（如 com.example）

- Artifact：项目名（如 thymeleaf-demo）

- 依赖选择：Web -> Spring Web、Template Engines -> Thymeleaf

点击 "Generate" 下载项目压缩包，解压后用 IDE 打开。

方式二：Maven 手动配置

在项目的 pom.xml 文件中添加以下依赖：

复制代码

<dependencies>

<!-- Spring Web 依赖 -->

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<!-- Thymeleaf 依赖 -->

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-thymeleaf</artifactId>

</dependency>

</dependencies>

3. 项目目录结构

复制代码

thymeleaf-demo/

├── src/

│ ├── main/

│ │ ├── java/

│ │ │ └── com/

│ │ │ └── example/

│ │ │ ├── controller/ # 控制器目录

│ │ │ ├── entity/ # 实体类目录

│ │ │ └── ThymeleafDemoApplication.java # 项目启动类

│ │ └── resources/

│ │ ├── templates/ # Thymeleaf 模板文件目录（默认）

│ │ └── application.properties # 配置文件

└── pom.xml # Maven 依赖配置文件

4. 基础配置（application.properties）

在 resources 目录下的 application.properties 文件中添加 Thymeleaf 配置，方便开发调试：

复制代码

spring.thymeleaf.encoding=UTF-8

# 开发环境关闭缓存（修改页面无需重启项目）

spring.thymeleaf.cache=false

# 模板文件前缀（默认就是 classpath:/templates/，可省略）

spring.thymeleaf.prefix=classpath:/templates/

# 模板文件后缀（默认就是 .html，可省略）

spring.thymeleaf.suffix=.html

二、核心语法详解

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

用于获取控制器传递到页面的数据，是 Thymeleaf 最基础的语法。

控制器中通过 model.addAttribute("变量名", 变量值) 传递数据。

页面中通过 ${变量名} 获取数据，结合 th:text 标签渲染到页面，示例：

默认欢迎语

2. 链接表达式（@{}）

用于生成动态链接，避免硬编码路径问题，支持带参数传递。

无参数链接：<a th:href="@{/user-list}">查看用户列表</a>

带参数链接：<a th:href="@{/user-detail(id=${user.id})}">查看详情</a>，生成的链接类似 /user-detail?id=1

3. 循环遍历（th:each）

用于遍历集合数据（如 List），常用来渲染列表、表格等。

语法：th:each="单个元素, 状态变量 : ${集合}"

状态变量常用属性：count（从 1 开始的序号）、index（从 0 开始的索引）

示例：

复制代码

  <tr th:each="user, stat : ${userList}">

  <td th:text="${stat.count}">序号</td>

  <td th:text="${user.name}">姓名</td>

  </tr>

三、项目实战（三大核心页面）

1. 实体类创建（User.java）

在 entity 目录下创建 User 实体类，存储用户数据：

java 复制代码

package com.example.thymeleafdemo.entity;

public class User {

private Integer id;

private String name;

private Integer age;

private String email;

// 构造方法

public User(Integer id, String name, Integer age, String email) {

this.id = id;

this.name = name;

this.age = age;

this.email = email;

}

// Getter 方法（Thymeleaf 需通过 Getter 获取属性值）

public Integer getId() { return id; }

public String getName() { return name; }

public Integer getAge() { return age; }

public String getEmail() { return email; }

}

2. 控制器创建

（1）首页控制器（IndexController.java）

在 controller 目录下创建，处理首页请求并传递基础数据：

java 复制代码

package com.example.thymeleafdemo.controller;

import org.springframework.stereotype.Controller;

import org.springframework.ui.Model;

import org.springframework.web.bind.annotation.GetMapping;

@Controller

public class IndexController {

@GetMapping("/")

public String index(Model model) {

model.addAttribute("pageTitle", "首页");

model.addAttribute("welcomeMsg", "欢迎使用 Thymeleaf 页面！");

return "index"; // 对应 templates 目录下的 index.html

}

}

（2）用户控制器（UserController.java）

处理用户列表和用户详情页请求：

java 复制代码

package com.example.thymeleafdemo.controller;

import com.example.thymeleafdemo.entity.User;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

import java.util.Arrays;
import java.util.List;

@Controller
public class UserController {
    // 处理用户列表请求
    @GetMapping("/user-list")
    public String userList(Model model) {
        // 模拟用户数据
        List<User> userList = Arrays.asList(
                new User(1, "张三", 22, "zhangsan@test.com"),
                new User(2, "李四", 25, "lisi@test.com")
        );
        model.addAttribute("userList", userList);
        model.addAttribute("pageTitle", "用户列表");
        return "userList";
    }

    // 处理用户详情请求
    @GetMapping("/user-detail")
    public String userDetail(Integer id, Model model) {
        // 模拟根据 ID 查询用户（实际项目中替换为数据库查询）
        User user = new User(id, "张三", 22, "zhangsan@test.com");
        model.addAttribute("user", user);
        model.addAttribute("pageTitle", "用户详情");
        return "userDetail";
    }
}

3. 模板页面创建

（1）首页（index.html）

在 templates 目录下创建，展示欢迎语并提供跳转链接：

html 复制代码

<!DOCTYPE html>

<html xmlns:th="http://www.thymeleaf.org">

<head>

<meta charset="UTF-8">

<title th:text="${pageTitle}">首页</title>

</head>

<body>

<h1 th:text="${welcomeMsg}">欢迎信息</h1>

<a th:href="@{/user-list}">查看用户列表</a>

</body>

</html>

（2）用户列表页（userList.html）

渲染用户列表表格，提供查看详情和返回首页链接：

html 复制代码

<!DOCTYPE html>

<html xmlns:th="http://www.thymeleaf.org">

<head>

<meta charset="UTF-8">

<title th:text="${pageTitle}">用户列表</title>

<style>

table { border-collapse: collapse; width: 60%; margin: 20px 0; }

th, td { border: 1px solid #ddd; padding: 8px; text-align: center; }

</style>

</head>

<body>

<h1 th:text="${pageTitle}">用户列表</h1>

<table>

<tr>

<th>序号</th>

<th>ID</th>

<th>姓名</th>

<th>年龄</th>

<th>操作</th>

</tr>

<tr th:each="user, stat : ${userList}">

<td th:text="${stat.count}">1</td>

<td th:text="${user.id}">1</td>

<td th:text="${user.name}">张三</td>

<td th:text="${user.age}">22</td>

<td><a th:href="@{/user-detail(id=${user.id})}">查看详情</a></td>

</tr>

</table>

<a th:href="@{/}">返回首页</a>

</body>

</html>

（3）用户详情页（userDetail.html）

展示单个用户的详细信息：

html 复制代码

<!DOCTYPE html>

<html xmlns:th="http://www.thymeleaf.org">

<head>

<meta charset="UTF-8">

<title th:text="${pageTitle}">用户详情</title>

</head>

<body>

<h1 th:text="${pageTitle}">用户详情</h1>

<div>

<p><span>ID：</span><span th:text="${user.id}">1</span></p>

<p><span>姓名：</span><span th:text="${user.name}">张三</span></p>

<p><span>年龄：</span><span th:text="${user.age}">22</span></p>

<p><span>邮箱：</span><span th:text="${user.email}">zhangsan@test.com</span></p>

</div>

<a th:href="@{/user-list}">返回用户列表</a>

</body>

</html>

四、项目运行与测试

找到项目启动类 ThymeleafDemoApplication.java，点击运行按钮启动项目。

打开浏览器，输入 http://localhost:8080 访问首页，可看到欢迎语和 "查看用户列表" 链接。

点击 "查看用户列表"，进入用户列表页，能看到用户数据表格和 "查看详情" 链接。

点击任意 "查看详情" 链接，进入用户详情页，查看该用户的详细信息，也可通过 "返回用户列表" 回到列表页。

五、关键总结

数据传递流程：控制器通过 Model 传递数据 → 模板页面用 ${变量名} 获取数据 → 结合 th:text 等标签渲染。

页面跳转逻辑：通过 th:href="@{路径}" 实现页面间跳转，带参数时在路径后加 (参数名=参数值)。

核心优势：开发环境无缓存，修改页面实时生效；语法简洁，与 HTML 标签自然融合，易于理解和维护。

Spring Boot 整合 Thymeleaf 生成 HTML 页面教学

一、环境搭建

1. 技术栈要求

2. 创建 Spring Boot 项目

方式一：通过 Spring Initializr（推荐）

方式二：Maven 手动配置

3. 项目目录结构

4. 基础配置（application.properties）

二、核心语法详解

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

默认欢迎语

2. 链接表达式（@{}）

3. 循环遍历（th:each）

三、项目实战（三大核心页面）

1. 实体类创建（User.java）

2. 控制器创建

（1）首页控制器（IndexController.java）

（2）用户控制器（UserController.java）

3. 模板页面创建

（1）首页（index.html）

（2）用户列表页（userList.html）

（3）用户详情页（userDetail.html）

四、项目运行与测试

五、关键总结