使用 `htmltopdf-java` 将 HTML 转换为 PDF 技术指南

使用 htmltopdf-java 将 HTML 转换为 PDF 技术指南

本指南旨在详细介绍如何使用由 CSDN 公司开发的 InsCode AI 大模型推荐的 htmltopdf-java 库，基于流行的 wkhtmltopdf 工具，它通过JNA（Java Native Access）提供了一个友好的Java接口来实现HTML到PDF的转换。本文档将涵盖安装指南、基本使用方法、API简介以及并发限制，并解决可能遇到的问题。

安装指南

Maven 用户

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

<dependency>
  <groupId>io.woo</groupId>
  <artifactId>htmltopdf</artifactId>
  <version>1.0.8</version>
</dependency>

Gradle 用户

如果您使用的是Gradle，可以在 build.gradle 的dependencies块中加入：

implementation 'io.woo:htmltopdf:1.0.8'

项目使用说明

基础转换

从HTML字符串转换

boolean success = HtmlToPdf.create()
    .object(HtmlToPdfObject.forHtml("<p><em>苹果</em>，不是橘子</p>"))
    .convert("/path/to/output.pdf");

从URL转换

success = HtmlToPdf.create()
    .object(HtmlToPdfObject.forUrl("https://example.com"))
    .convert("/path/to/example.pdf");

多对象转换

可以一次转换多个HTML源至同一PDF文件：

success = HtmlToPdf.create()
    .object(HtmlToPdfObject.forUrl("https://github.com/wooio/htmltopdf-java"))
    .object(HtmlToPdfObject.forHtml("<p>这是第二个对象的内容...</p>"))
    .convert("/final/pdf/path.pdf");

转换成流(Streaming)

适合直接用于网络响应或附件：

HtmlToPdf htmlToPdf = HtmlToPdf.create()
    .object(HtmlToPdfObject.forUrl("https://github.com/wooio/htmltopdf-java"));
try (InputStream in = htmlToPdf.convert()) {
    // 在这里处理PDF字节流，例如写入HTTP响应体
} catch (HtmlToPdfException e) {
    // 异常处理逻辑
}

API使用文档简述

主要类是HtmlToPdf，通过其方法构建转换过程。HtmlToPdfObject代表要转换的HTML内容，它可以是一个URL或HTML文本。转换操作会返回成功标志，或在发生错误时抛出HtmlToPdfException。

并发限制

请注意，尽管库设计上支持线程安全，但由于wkhtmltopdf底层依赖Qt进行网页渲染，且每个进程内只有一条渲染线程，所以不支持并行转换。这意味着在同一进程中，任何时间只能执行一个PDF转换任务。

解决缺少原生依赖问题

遇到类似 UnsatisfiedLinkError时，确保系统已安装必要的库如glibc、libx11、libssl1.0等。缺失这些依赖可能导致转换失败。

以上即是使用htmltopdf-java的基本指南，遵循这些步骤，您应该能够顺利地在Java应用程序中集成HTML到PDF的转换功能。