完美！SpringBoot3.3 + OpenPDF + HTML模板高效生成PDF文檔
作者：編程疏影
通過本文的講解，我們成功實現了使用 SpringBoot 3.3 結合 Thymeleaf 模板引擎、高效生成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 versinotallow="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" >
</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:run2. 訪問預覽頁面
在瀏覽器中訪問：
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文檔生成功能。
責任編輯：武曉燕
來源：
路條編程
