对于需要在企业级应用中生成动态文档、财务报表或法律文书的开发者而言，HTML 到 PDF 的高质量转换是一项核心需求。无论是构建 Web 应用后端、自动化报告系统还是电子发票生成工具，确保内容在不同平台和设备上保持一致的格式和布局至关重要。
本文将演示如何使用功能强大的 Spire.PDF for .NET 库和 QT WebEngine 在 Java 中转换 HTML 到 PDF，确保从动态网页、原始 HTML 字符串或 HTML 文件中高保真地渲染出 PDF。
目录：
- 为什么要在 Java 中转换 HTML 到 PDF？
- 环境准备与配置
- 通过 Java 将 URL 转换为 PDF
- 通过 Java 将 HTML 字符串转换为 PDF
- 通过 Java 将 HTML 文件转换为 PDF
- 常见问题
- 结论
为什么要在 Java 中转换 HTML 到 PDF？
在 Java 环境中处理 HTML 到 PDF 的转换，能够充分发挥以下优势：
- 格式精准保留：完美复现 HTML/CSS 样式，确保打印文档与网页显示一致
- 跨平台兼容性：突破设备限制，实现文档在不同操作系统中的统一渲染
- 动态文档生成：基于网页模板快速创建个性化 PDF（如发票、合同等）
- 网页内容归档：将动态网页转为永久静态的 PDF 快照
- 工作流自动化：无缝集成到 Java 应用中，实现批量转换与定时任务
环境准备与配置
使用 Spire.PDF for Java 搭配 QT WebEngine 可构建专业级转换工具，具体安装步骤如下：
安装 Spire.PDF for Java
支持两种安装方式，开发者可根据项目需求选择：
1. Maven 依赖配置
在项目的 pom.xml 中添加以下仓库与依赖：
<repositories>
<repository>
<id>com.e-iceblue</id>
<name>e-iceblue</name>
<url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>e-iceblue</groupId>
<artifactId>spire.pdf</artifactId>
<version>11.7.0</version>
</dependency>
</dependencies>
2. 手动导入 JAR 包
从官方网站下载最新版 Spire.PDF for Java，解压后将 JAR 文件添加至项目的类路径。
下载 QT WebEngine 插件
QT WebEngine 作为基于 Chromium 的渲染引擎，是解析现代网页内容的核心组件。本场景使用开源版本的 Qt WebEngine（基于 LGPLv3/GPL 许可）来将 HTML 内容渲染为 PDF。根据您的操作系统下载相应的 QT 插件版本：
解压后得到 "plugins" 文件夹（示例路径：F:\Plugin\plugins-windows-x64\plugins）。
环境特殊配置
- Linux/Mac 系统：直接将插件包拷贝到 Linux 或 Mac 系统上解压缩，并确保解压后的文件夹有权限进行读取。
- 无头服务器（无 GUI）：本文中的转换方法需要 GUI （图形用户界面）支持。对于未安装图形用户界面的服务器，需要先安装 xvfb 工具，然后使用 xvfb-run 命令来运行应用程序。
#1. 安装 xvfb
Centos：yum install Xvfb
Ubuntu：apt-get install Xvfb
#2. 运行应用程序
xvfb-run java -jar HTMLToPDF.jar
通过 Java 将 URL 转换为 PDF
通过以下 Java 代码将 HTML 网页（URL）转换为 PDF文档。适用于动态抓取网页快照。
import com.spire.pdf.graphics.PdfMargins;
import com.spire.pdf.htmlconverter.qt.HtmlConverter;
import com.spire.pdf.htmlconverter.qt.Size;
public class ConvertUrlToPdf {
public static void main(String[] args) {
// 指定 url 路径
String url = "https://www.baidu.com/";
// 指定输出文件路径
String fileName = "output/Url转Pdf.pdf";
// 指定插件路径
String pluginPath = "F:\\Plugin\\plugins-windows-x64\\plugins";
// 设置插件路径
HtmlConverter.setPluginPath(pluginPath);
// 将 URL 转换为 PDF
HtmlConverter.convert(url, fileName, true, 1000000, new
Size(1200f, 1000f), new
PdfMargins(0));
}
}
参数说明：
上述代码中，使用到的核心转换方法是 HtmlConverter.convert()。它接受以下 6 个参数：
| 参数 | 用途 |
|---|---|
| String url | 指定要转换的网页地址 |
| String fileName | 指定输出 PDF 文件的路径 |
| boolean enableJavaScript | 允许动态内容（如 AJAX、动画）。设置为 false 可禁用 |
| int timeout | 最大页面加载时间。可根据网站加载速度调整。 |
| Size pageSize | 设置输出 PDF 的页面大小 |
| PdfMargins margins | 设置输出 PDF 的页边距 |
转换结果：
通过 Java 将 HTML 字符串转换为 PDF
对于程序中动态生成的 HTML 内容（如用户输入的富文本），可直接将 HTML 字符串转换为 PDF：
import com.spire.pdf.graphics.PdfMargins;
import com.spire.pdf.htmlconverter.LoadHtmlType;
import com.spire.pdf.htmlconverter.qt.HtmlConverter;
import com.spire.pdf.htmlconverter.qt.Size;
import java.io.IOException;
public class ConvertHtmlStringToPdf {
public static void main(String[] args) throws IOException {
// 指定 Html 字符串
String htmlString = "<html>" +
"<style> h1 {color: #FF5733;font-size: 24px;margin-top: 50px;} </style>" +
"<body>" +
"<h1>Hello, PDF!</h1>" +
"<p>将 HTML 字符串转换为 PDF 文档的简单示例.</p>" +
"<ul>" +
"<li>项目 1</li>" +
"<li>项目 2</li>" +
"<li>项目 3</li>" +
"</ul>" +
"</body></html>";
// 指定输出文件路径
String outputFile = "output/Html字符串转PDF.pdf";
// 指定插件路径
String pluginPath = "F:\\Plugin\\plugins-windows-x64\\plugins";
// 设置插件路径
HtmlConverter.setPluginPath(pluginPath);
// 将 HTML 字符串转换为 PDF
HtmlConverter.convert(htmlString, outputFile, true, 100000, new
Size(700, 900), new
PdfMargins(0), LoadHtmlType.Source_Code);
}
}
在这段代码中：
- 指定了一个包含内联 CSS 样式（如红色 h1 文本）和简单内容（标题、段落、列表）的 HTML 字符串。
- 使用 HtmlConverter.convert() 方法将 HTML 字符串转换为 PDF，其参数如下：
- HTML 内容（字符串）
- 输出文件路径
- true 表示启用 JavaScript 执行。
- 超时时间（100,000 毫秒）
- 页面大小（700x900）
- 页边距为 0
- LoadHtmlType.Source_Code 表示输入类型为 HTML 源码。
转换效果：
通过 Java 将 HTML 文件转换为 PDF
本示例展示了如何通过编程将本地 HTML 文件转换为 PDF 文档。适用于静态文档归档和设计复杂的出版物。
import com.spire.pdf.graphics.PdfMargins;
import com.spire.pdf.htmlconverter.LoadHtmlType;
import com.spire.pdf.htmlconverter.qt.HtmlConverter;
import com.spire.pdf.htmlconverter.qt.Size;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
public class ConvertHtmlToPdf {
public static void main(String[] args) throws IOException {
// 调用自定义方法 HtmlToString() 将 HTML 文件转换为字符串
String htmlString = HtmlToString("input.html");
// 指定输出文件路径
String outputFile = "output/Html文件转Pdf.pdf";
// 指定插件路径
String pluginPath = "F:\\Plugin\\plugins-windows-x64\\plugins";
// 设置插件路径
HtmlConverter.setPluginPath(pluginPath);
// 将 HTML 字符串转换为 PDF
HtmlConverter.convert(htmlString, outputFile, true, 100000, new
Size(700, 900), new
PdfMargins(0), LoadHtmlType.Source_Code);
}
// 将 HTML 文件转换为字符串
public static String
HtmlToString(String filePath) throws IOException {
String path = filePath;
File file = new File(path);
FileReader fileReader = new FileReader(file);
BufferedReader
bufferedReader = new
BufferedReader(fileReader);
StringBuilder stringBuilder = new StringBuilder();
String temp = "";
while ((temp = bufferedReader.readLine()) != null) {
stringBuilder.append(temp +
"\n");
}
bufferedReader.close();
String str = stringBuilder.toString();
return str;
}
}
注意：只有内联 CSS 样式和内部 CSS 样式可以在 PDF 上正确呈现。对于外部 CSS 样式表，请将其转换为内联或内部 CSS 样式。
核心转换流程
- 读取 HTML 文件：使用自定义方法 HtmlToString() 将 HTML 文件转换为字符串。
- 使用 FileReader 和 BufferedReader 打开 HTML 文件。
- 逐行读取，将内容附加到 StringBuilder 中。
- 将 HTML 内容作为单个字符串返回。
- 配置输出和插件：指定输出文件路径并设置 Qt 插件路径。
- HTML 转 PDF：使用与上面示例相同的 HtmlConverter.convert() 方法。
转换效果：
常见问题
问题 1：为什么需要 Qt 插件来转换 HTML 到 PDF？
答：Qt WebEngine 提供了一个基于 Chromium 的渲染引擎，支持现代 HTML5、CSS3 和 JavaScript 特性，是实现高保真转换的核心依赖。
问题 2：如何避免输出 PDF 中出现水印？
答：申请 30 天试用许可证，以去除水印并解除功能限制。
问题 3：如何优化大型文档的转换速度？
答：
- 关闭不必要的 JavaScript 执行（enableJavaScript=false）
- 缩短超时时间（根据网络情况调整）
- 减小页面尺寸（如 A4 规格）
结论
将 Spire.PDF for Java 与 QT 插件相结合，仅需极少代码就能在 Java 环境中实现 HTML 到 PDF 的高效转换。无论源文件是 URL、字符串还是本地文档，本文都提供了详尽的操作说明与实用代码示例，助您轻松强化文档自动化工作流程。
点击查看 Spire.PDF for Java 在线文档，解锁更多 Java 操作 PDF 的强大功能，如数字签名、PDF/A 合规性等，让文档处理更全面高效。
