完美！SpringBoot3.3 + OpenPDF + HTML模板高效生成PDF文档
完美！SpringBoot3.3 + OpenPDF + Flying Saucer + HTML模板高效生成PDF文档
在现代Web开发中，生成PDF文档是一个常见的需求，无论是生成报表、导出合同还是制作发票，都需要高效、灵活的PDF生成方案。本篇文章将深入探讨如何使用 SpringBoot 3.3 结合 Thymeleaf、JavaScript 和 Bootstrap 实现高效的PDF文档生成，并通过详细的代码示例和配置说明，帮助大家快速上手这一技术方案。
随着业务需求的不断增长，传统的PDF生成方式已经难以满足复杂、多样化的需求。使用HTML模板生成PDF具有以下优势：
可视化强：可以直接在浏览器中预览效果，所见即所得。
样式灵活：借助CSS和Bootstrap，可以轻松实现复杂的布局和样式。
开发高效：前后端分离，开发维护更加便捷。
本篇文章将基于 SpringBoot 3.3，利用 Thymeleaf 模板引擎和 OpenPDF 库，将HTML模板渲染为PDF文档，实现高效、灵活的PDF生成方案。
运行效果：
生成 pdf 效果：
若想获取项目完整代码以及其他文章的项目源码，且在代码编写时遇到问题需要咨询交流，欢迎加入下方的知识星球。
项目环境准备
1. 开发环境
JDK 17：确保您的项目运行在Java 17环境下。
Maven 3.8+：用于项目构建和依赖管理。
SpringBoot 3.3：最新版本的SpringBoot框架。
Thymeleaf：流行的Java模板引擎。
OpenPDF：开源的PDF生成库。
Bootstrap 5：用于前端页面的布局和样式。
JavaScript：用于增强页面交互性。
2. 项目结构
项目的基本结构如下：
pdf-demo
├── src
│ ├── main
│ │ ├── java
│ │ │ └── com.icoderoad.pdfdemo
│ │ │ ├── controller
│ │ │ ├── service
│ │ │ └── PdfDemoApplication.java
│ │ ├── resources
│ │ │ ├── templates
│ │ │ ├── fonts/SimSun.ttf
│ │ │ ├── static
│ │ │ └── application.yml
├── pom.xml
项目依赖配置（pom.xml）
首先，我们需要在 pom.xml 中添加必要的依赖。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.3</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.icoderoad</groupId>
<artifactId>pdfdemo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>pdfdemo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>17</java.version>
<openpdf.version>1.3.29</openpdf.version>
</properties>
<dependencies>
<!-- Spring Boot Starter 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>
<!-- OpenPDF 库 -->
<dependency>
<groupId>com.github.librepdf</groupId>
<artifactId>openpdf</artifactId>
<version>${openpdf.version}</version>
</dependency>
<!-- HTML转PDF工具（flying-saucer） -->
<dependency>
<groupId>org.xhtmlrenderer</groupId>
<artifactId>flying-saucer-core</artifactId>
<version>9.1.20</version>
</dependency>
<dependency>
<groupId>org.xhtmlrenderer</groupId>
<artifactId>flying-saucer-pdf-openpdf</artifactId>
<version>9.1.20</version>
</dependency>
<!-- 日志框架 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
依赖说明：
spring-boot-starter-web：提供Web开发所需的基本依赖。
spring-boot-starter-thymeleaf：集成Thymeleaf模板引擎。
openpdf：用于生成PDF文档的核心库。
flying-saucer：将HTML转换为PDF的工具，结合OpenPDF使用。
spring-boot-starter-logging：提供日志支持。
应用配置（application.yml）
在 src/main/resources 目录下创建 application.yml 配置文件。
# application.yml
server:
port: 8080
spring:
thymeleaf:
prefix: classpath:/templates/
suffix: .html
mode: HTML
encoding: UTF-8
cache: false
配置说明：
server.port：设置应用运行端口为8080。
spring.thymeleaf：配置Thymeleaf模板引擎的相关属性，指定模板路径、后缀、编码等。
后端代码实现
1. 主启动类
创建主启动类 PdfDemoApplication.java。
package com.icoderoad.pdfdemo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class PdfdemoApplication {
public static void main(String[] args) {
SpringApplication.run(PdfdemoApplication.class, args);
}
}
2. 控制器层
创建控制器类 PdfController.java，负责处理请求和生成PDF文档。
// PdfController.java
package com.icoderoad.pdfdemo.controller;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import com.icoderoad.pdfdemo.service.PdfService;
import jakarta.servlet.http.HttpServletResponse;
@Controller
public class PdfController {
@Autowired
private PdfService pdfService;
/**
* 显示数据预览页面
* @param model 模型数据
* @return 模板名称
*/
@GetMapping("/preview")
public String preview(Model model) {
model.addAttribute("title", "PDF文档预览");
model.addAttribute("content", "这是一个使用Thymeleaf渲染的HTML内容，将被转换为PDF文档。");
return "preview";
}
/**
* 生成PDF文档并下载
* @param response HTTP响应
* @throws Exception 异常
*/
@GetMapping("/download")
public void downloadPdf(HttpServletResponse response) throws Exception {
String htmlContent = pdfService.generateHtmlContent();
pdfService.generatePdf(response, htmlContent);
}
}
代码说明：
/preview：用于展示HTML内容的预览页面，方便在生成PDF前查看效果。
/download：生成PDF文档并通过HTTP响应下载。
3. 服务层
创建服务类 PdfService.java，负责处理HTML内容的生成和PDF文档的生成。
package com.icoderoad.pdfdemo.service;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Service;
import org.thymeleaf.TemplateEngine;
import org.thymeleaf.context.Context;
import org.xhtmlrenderer.pdf.ITextFontResolver;
import org.xhtmlrenderer.pdf.ITextRenderer;
import com.lowagie.text.DocumentException;
import jakarta.servlet.http.HttpServletResponse;
@Service
public class PdfService {
@Autowired
private TemplateEngine templateEngine;
/**
* 生成HTML内容
* @return 渲染后的HTML字符串
*/
public String generateHtmlContent() {
Context context = new Context();
context.setVariable("title", "PDF文档标题");
context.setVariable("content",
"这是PDF文档的主要内容："
+ "“成功并不是终点，失败也不是终结，最重要的是继续前行的勇气。在人生的旅途中，我们会遇到许多挑战与挫折，这些都是成长的必经之路。每一次跌倒都是一次学习的机会，每一次失败都为成功铺设了基础。只要我们保持信念，不断努力，最终会到达梦想的彼岸。无论前方的路有多么坎坷，只要心怀希望，我们就有无限的可能性去改变自己的命运，实现心中的理想。”"
+ "由Thymeleaf模板引擎渲染。"
+ "");
return templateEngine.process("pdf_template", context);
}
/**
* 将HTML内容转换为PDF并写入响应
* @param response HTTP响应
* @param htmlContent HTML内容
* @throws IOException IO异常
* @throws DocumentException 文档异常
*/
public void generatePdf(HttpServletResponse response, String htmlContent) throws IOException, DocumentException {
// 设置响应类型
response.setContentType("application/pdf");
response.setHeader("Content-Disposition", "attachment; filename=generated.pdf");
// 创建ITextRenderer实例
ITextRenderer renderer = new ITextRenderer();
// 设置字体路径，使用 classpath 加载字体
ITextFontResolver fontResolver = renderer.getFontResolver();
ClassPathResource fontResource = new ClassPathResource("fonts/SimSun.ttf");
System.out.println(fontResource.getFile().getAbsolutePath());
fontResolver.addFont(fontResource.getFile().getAbsolutePath(), "Identity-H", true);
renderer.setDocumentFromString(htmlContent);
renderer.layout();
// 输出PDF到响应输出流
try (OutputStream outputStream = response.getOutputStream()) {
renderer.createPDF(outputStream);
outputStream.flush();
}
}
}
代码说明：
generateHtmlContent()：使用Thymeleaf模板引擎渲染HTML内容，填充模板变量。
generatePdf()：使用
ITextRenderer将HTML内容转换为PDF文档，并写入HTTP响应，供用户下载。
注意事项：
模板引擎配置：
TemplateEngine需要在配置类中进行相应设置，这里通过自动装配注入。字符编码：确保HTML内容的字符编码为UTF-8，避免中文乱码。
前端代码实现
1. Thymeleaf模板
在 src/main/resources/templates 目录下创建 preview.html 和 pdf_template.html 两个模板文件。
1.1 preview.html
用于在浏览器中预览内容。
<!-- preview.html -->
<!DOCTYPE html>
<html lang="zh-CN" xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title th:text="${title}">PDF预览</title>
<!-- 引入Bootstrap CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css">
</head>
<body>
<div class="container mt-5">
<h1 class="text-center" th:text="${title}">PDF文档预览</h1>
<p class="mt-4" th:text="${content}">这里是内容部分。</p>
<div class="text-center mt-5">
<a href="/pdf-demo/download" class="btn btn-primary">下载PDF文档</a>
</div>
</div>
<!-- 引入Bootstrap JS -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>
代码说明：
使用 Bootstrap 5 进行简单的页面布局和样式设计。
通过Thymeleaf的
th:text属性渲染动态内容。提供一个下载PDF的按钮，链接到 /download`。
1.2 pdf_template.html
用于生成PDF的模板。
<!DOCTYPE html>
<html lang="zh-CN" xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8"/>
<title th:text="${title}">PDF文档</title>
<style>
/* 内联CSS样式，确保在PDF中正确渲染 */
body {
font-family: "SimSun", serif;
padding: 20px;
line-height: 1.6;
}
h1 {
text-align: center;
margin-bottom: 40px;
color: #333;
}
p {
font-size: 16px;
color: #555;
}
.footer {
text-align: center;
margin-top: 50px;
font-size: 12px;
color: #999;
}
</style>
</head>
<body>
<h1 th:text="${title}">PDF文档标题</h1>
<p th:text="${content}">这是PDF文档的内容部分，由Thymeleaf模板引擎渲染。</p>
<div class="footer">
<p>© 2024 路条编程 - 保留所有权利。</p>
</div>
</body>
</html>
代码说明：
内联样式：为了确保PDF中样式正确渲染，使用内联CSS样式。
字体设置：指定
font-family为中文字体（如 "SimSun"），避免中文显示乱码。内容布局：简单的标题、内容和页脚布局，满足基本的PDF文档需求。
2. 静态资源
对于简单的示例，我们直接使用CDN引入Bootstrap的CSS和JS。如果需要自定义样式和脚本，可以在 src/main/resources/static 目录下添加相应的文件。
运行与测试
1. 启动应用
在项目根目录下执行以下命令启动应用：
mvn spring-boot:run
2. 访问预览页面
在浏览器中访问：
http://localhost:8080/preview
您将看到预览页面，展示了将要生成的PDF内容。
3. 下载PDF文档
在预览页面点击“下载PDF文档”按钮，浏览器将自动下载生成的PDF文件 generated.pdf。
效果展示：
生成的PDF文档应当包含正确的中文内容和样式，确保没有乱码和样式错乱。
深度解析
1. 为什么选择OpenPDF和Flying Saucer
OpenPDF 是一个功能强大且稳定的开源PDF库，支持丰富的PDF操作。而 Flying Saucer 是一个专门用于将XHTML/CSS转换为PDF的库，与OpenPDF兼容性良好。两者结合，可以方便地将HTML模板转换为高质量的PDF文档。
优势：
易于使用：API简洁明了，集成方便。
支持CSS样式：能够很好地渲染复杂的CSS样式，满足多样化的布局需求。
开源免费：无版权限制，适用于商业项目。
2. 字体和编码问题
在生成包含中文内容的PDF时，常常会遇到乱码或字体缺失的问题。为了解决这些问题，我们需要：
指定中文字体：在CSS中设置
font-family为系统支持的中文字体，如"SimSun"、"Microsoft YaHei"等。嵌入字体：确保PDF中嵌入所需的字体文件，可以通过配置ITextRenderer来实现。
设置编码：确保HTML内容和生成的PDF使用统一的UTF-8编码。
示例：嵌入字体
renderer.getFontResolver().addFont("path/to/simsun.ttf", BaseFont.IDENTITY_H, BaseFont.EMBEDDED);
注意：需要将字体文件放在项目的资源目录中，并指定正确的路径。
3. 处理复杂布局和样式
对于复杂的PDF文档，可以在HTML模板中使用更丰富的Bootstrap组件和自定义CSS，实现多栏布局、表格、图片等元素。同时，Thymeleaf的强大模板功能也可以帮助我们动态生成复杂的内容。
示例：在模板中使用表格
<table class="table table-bordered">
<thead>
<tr>
<th>序号</th>
<th>名称</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>示例项</td>
<td>这是一个示例描述。</td>
</tr>
<!-- 更多行 -->
</tbody>
</table>
4. 动态数据填充
通过在服务层获取数据库或其他数据源的数据，并将其传递给Thymeleaf模板，我们可以动态生成包含业务数据的PDF文档。
示例：传递数据列表
List<Item> items = itemService.getItems();
context.setVariable("items", items);
在模板中迭代显示数据：
<tbody>
<tr th:each="item, iterStat : ${items}">
<td th:text="${iterStat.index + 1}">1</td>
<td th:text="${item.name}">示例项</td>
<td th:text="${item.description}">这是一个示例描述。</td>
</tr>
</tbody>
总结
通过本文的讲解，我们成功实现了使用 SpringBoot 3.3 结合 Thymeleaf 模板引擎、高效生成PDF文档的功能。从环境配置、依赖管理到代码实现，再到样式设计和复杂布局处理，都进行了详细的阐述。
优势总结：
高效性：利用现有的HTML模板和样式，快速生成所见即所得的PDF文档。
灵活性：通过模板和数据的结合，轻松实现动态内容的生成。
可维护性：清晰的前后端分离，方便维护和扩展。
未来展望：
多语言支持：通过国际化配置，实现PDF文档的多语言版本。
更复杂的样式：引入更丰富的前端框架，如Tailwind CSS，提升文档的美观度。
性能优化：对于大批量PDF生成的场景，可以考虑异步处理和缓存机制，提升性能。
希望本文能对大家的开发工作有所帮助，助大家在项目中高效地实现PDF文档生成功能。