当前位置：首页 > news >正文

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

news 2025/10/11 7:40:47

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（推荐）

打开 Spring Initializr 官网。

配置项目信息：

- 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 标签渲染到页面，示例：

<h1 th:text="${welcomeMsg}">默认欢迎语</h1>

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 实体类，存储用户数据：

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 目录下创建，处理首页请求并传递基础数据：

package com.example.thymeleafdemo.controller;import org.springframework.stereotype.Controller;import org.springframework.ui.Model;import org.springframework.web.bind.annotation.GetMapping;@Controllerpublic class IndexController {@GetMapping("/")public String index(Model model) {model.addAttribute("pageTitle", "首页");model.addAttribute("welcomeMsg", "欢迎使用 Thymeleaf 页面！");return "index"; // 对应 templates 目录下的 index.html}}

（2）用户控制器（UserController.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 目录下创建，展示欢迎语并提供跳转链接：

<!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）

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

<!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）

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

<!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>