Java 工具包 - 一站式 PDF 解决方案 x-easypdf (1)

约 2222 字大约 7 分钟

2026-05-25

作为一名 Java 开发者，我在日常工作中经常需要处理 PDF 文档。无论是生成报告、合同，还是对现有 PDF 进行编辑，一个简单易用的工具能极大提升开发效率。今天给大家介绍一款 Java 语言简化处理 PDF 的框架——x-easypdf，它最近发布了具有 AI 加持的 3.3.0 版本，让我们一起来看看它的强大功能吧。

x-easypdf 是什么？

x-easypdf 是一个专为简化 PDF 处理而设计的 Java 框架，提供了一套简单易用的 API 接口。它包含两个核心模块：

fop 模块：专注于 PDF 文档创建，基于 xsl-fo 模板生成 PDF 文档，支持多种数据源进行模板渲染
pdfbox 模块：专注于 PDF 文档编辑，在标准的 Apache PDFBox 基础上进行扩展，添加了大量实用功能

在 3.3.0 版本中，x-easypdf 更是加入了 AI 能力，可以智能解析文档内容，为 PDF 处理带来了全新可能。

官网地址：https://x-easypdf.cn/

项目地址：https://gitee.com/dromara/x-easypdf

Mavan仓库：https://central.sonatype.com/artifact/org.dromara/x-easypdf/overview

fop 模块与 pdfbox 模块如何选择？

fop 模块基于 xsl-fo 模板生成 pdf 文档，仅适用于文档创建。 pdfbox 模块支持文档的创建、解析、提取与处理，适用范围更广。

核心特性

简单易用

x-easypdf 的设计理念就是简化 PDF 操作流程，仅需一行代码，便可完成多种 PDF 操作。它通过组件化的形式进行 PDF 构建，极大降低了使用门槛。

功能丰富

创建 PDF 文档：轻松创建新的 PDF 文档
编辑 PDF 文档：添加文本、图像、表格等元素
操作 PDF 文档：支持合并、分割、加密和解密 PDF 文档
生成 PDF 表单：创建包含可填写字段的 PDF 表单
自动换行与分页：当内容超过页面宽度或高度时自动处理
内置中文支持：支持华为鸿蒙字体，中文处理更加自然

AI 加持

3.3.0 版本新增了大模型解析文档的支持，包括：

月之暗面（Kimi）AI 解析器
讯飞（Spark）AI 解析器
腾讯 AI 解析器

这些 AI 功能可以智能解析 PDF 中的文本和图像内容，实现更高级的文档处理能力。

安装与配置

Maven 依赖

根据需求，可以选择引入全功能模块或特定模块：

全功能模块（pdfbox + fop）

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>x-easypdf</artifactId>
    <version>版本号</version>
</dependency>

仅 pdfbox 模块

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>x-easypdf-pdfbox</artifactId>
    <version>版本号</version>
</dependency>

仅 fop 模块

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>x-easypdf-fop</artifactId>
    <version>版本号</version>
</dependency>

fop 模块

使用步骤

以 freemarker 数据源为例

添加数据源依赖

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>版本号</version>
</dependency>

创建模板对象

Template template = TemplateHandler.Template.build();

设置 fop 配置文件路径

template.setConfigPath(configPath);

设置数据源，并设置 xsl-fo 模板路径与模板数据

template.setDataSource(
        TemplateHandler.DataSource.Freemarker.build()
                            .setTemplateName("template.fo")
                            .setTemplateData(data)
);

执行转换

template.transform(outputPath);

完整示例

以 freemarker 数据源为例

// 定义fop配置文件路径
String configPath = "E:\\pdf\\template\\fop.xconf";
// 定义xsl-fo模板路径（目录）
String templatePath = "E:\\pdf\\template\\freemarker";
// 定义pdf输出路径
String outputPath = "E:\\pdf\\test\\fo\\Freemarker.pdf";
// 设置模板路径
TemplateHandler.DataSource.Freemarker.setTemplatePath(templatePath);
// 定义数据map
Map<String, Object> data = new HashMap<>();
// 定义数据list
List<String> list = new ArrayList<>(2);
list.add("hello");
list.add("world");
// 设置值
data.put("list", list);
data.put("str", "hello world");
// 转换pdf
TemplateHandler.Template.build().setConfigPath(configPath).setDataSource(
        // 构建数据源
        TemplateHandler.DataSource.Freemarker.build()
            // 设置模板名称（模板路径下的文件名称）
            .setTemplateName("template.fo")
            // 设置模板数据
            .setTemplateData(data)
).transform(outputPath);

fop 配置文件

<?xml version="1.0"?>
<!-- fop版本 -->
<fop version="1.0">

    <!-- 当前路径（项目所在路径） -->
    <base>.</base>

    <!-- 默认源图像 dpi（每英寸点数像素） -->
    <source-resolution>72</source-resolution>
    <!-- 默认目标图像 dpi（每英寸点数像素），默认: 72dpi -->
    <target-resolution>72</target-resolution>

    <!-- 默认页面宽度与高度（A4） -->
    <default-page-settings width="21cm" height="29.7cm"/>

    <!-- 渲染器 -->
    <renderers>
        <!-- pdf 渲染器 -->
        <renderer mime="application/pdf">
            <!-- 过滤器 -->
            <filterList>
                <!-- 默认使用 flate 依赖压缩 -->
                <value>flate</value>
            </filterList>
            <!-- 字体 -->
            <fonts>
                <!-- 自动扫描系统全部字体 -->
                <auto-detect/>
            </fonts>
        </renderer>
    </renderers>
</fop>

xsl-fo 配置文件

<?xml version="1.0" encoding="utf-8"?>
<!--根标签-->
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
    <!--页面模板-->
    <fo:layout-master-set>
        <!--单页面模板-->
        <fo:simple-page-master master-name="A4">
            <!--页面区域主体-->
            <fo:region-body/>
        </fo:simple-page-master>
    </fo:layout-master-set>
    <!--页面序列-->
    <fo:page-sequence master-reference="A4">
        <!--页面流-->
        <fo:flow flow-name="xsl-region-body">
            <#list list as data>
                <fo:block>${data}</fo:block>
            </#list>
            <#if str??>
                <fo:block>${str}</fo:block>
            <#else>
                <fo:block font-family="微软雅黑">为空</fo:block>
            </#if>
        </fo:flow>
    </fo:page-sequence>
</fo:root>

提示

使用中文时，需设置支持中文的字体名称

pdfbox 模块

使用步骤

创建文档

以添加文本为例

创建文档对象

Document document = PdfHandler.getDocumentHandler().create();

创建页面对象

Page page = new Page(document);

创建组件对象

Textarea textarea = new Textarea(page);

渲染组件

textarea.render();

添加页面

document.appendPage(page);

保存文档

document.save(outputPath);

关闭文档

document.close();

完整示例

// 定义pdf输出路径
String outputPath = "E:\\PDF\\pdfbox\\test.pdf";

// 创建文档
Document document = PdfHandler.getDocumentHandler().create();
// 设置字体
document.setFontName("微软雅黑");

// 创建页面
Page page = new Page(document);

// 创建文本域
Textarea textarea = new Textarea(page);
// 设置文本
textarea.setText("Hello World!");
// 渲染文本
textarea.render();

// 添加页面
document.appendPage(page);
// 保存文档
document.save(outputPath);
// 关闭文档
document.close();

编辑文档

以第一页添加文本为例

读取文档

Document document = PdfHandler.getDocumentHandler().load(sourcePath);

获取页面对象

Page page = document.getPage(0);

创建组件对象

Textarea textarea = new Textarea(page);

渲染组件

textarea.render();

保存文档

document.save(outputPath);

关闭文档

document.close();

完整示例

// 定义pdf源路径
String sourcePath = "E:\\PDF\\pdfbox\\test.pdf";
// 定义pdf输出路径
String outputPath = "E:\\PDF\\pdfbox\\newTest.pdf";

// 读取文档
Document document = PdfHandler.getDocumentHandler().load(sourcePath);

// 获取页面
Page page = document.getPage(0);

// 创建文本域
Textarea textarea = new Textarea(page);
// 设置X轴起始坐标
textarea.setBeginX(100F);
// 设置Y轴起始坐标
textarea.setBeginY(100F);
// 设置文本
textarea.setText("Hello World!");
// 渲染文本
textarea.render();

// 保存文档
document.save(outputPath);
// 关闭文档
document.close();

实战

基础 PDF 创建

// 创建文档
Document document = PdfHandler.getDocumentHandler().create();
// 设置使用字体
document.setFontName("微软雅黑");
// 创建页面
Page page = new Page(document);
// 创建文本域
Textarea textarea = new Textarea(page);
// 设置文本
textarea.setText("Hello World!");
// 渲染文本
textarea.render();
// 添加页面
document.appendPage(page);
// 保存文档
/Users/zhangni/liushiGong
// 关闭文档
document.close();

多张图片合并为 PDF

public static File imagesToPdf(List<File> imageFiles, File targetPdfFilePath) {
    if (CollUtil.isNotEmpty(imageFiles) && targetPdfFilePath != null) {
        XEasyPdfDocument document = XEasyPdfHandler.Document.build();
        
        imageFiles.stream().forEachOrdered(imageFile -> {
            XEasyPdfComponent xEasyPdfImage = toEasyPdfImage(imageFile);
            XEasyPdfPage newPage = customNewPageByImage(imageFile);
            newPage.addComponent(xEasyPdfImage);
            document.addPage(newPage);
        });
        
        document.save(new FileOutputStream(targetPdfFilePath)).close();
        return targetPdfFilePath;
    }
    return null;
}

使用 AI 解析文档内容

3.3.0 版本的 AI 功能为文档解析带来了革命性变化：

// 解析图像示例
@Test
public void parseImageWithPageTest() {
    String ak = System.getenv("ak");
    String sk = System.getenv("sk");
    Document document = PdfHandler.getDocumentHandler().load("E:\\\\PDF\\\\pdfbox\\\\allTest.pdf");
    TencentAIParser parser = PdfHandler.getDocumentAIParser(document).getTencentAI(ak, sk, false);
    AIParseInfo info = parser.parseImageWithPage(
        "根据'这是一张XXX地点XXX的图片'的格式描述图片展示的内容，说出具体的城市，使用中文回答", 
        0, 1
    );
    log.info("返回内容：\n" + info.getResult());
    document.close();
}

// 解析文本示例
@Test
public void parseTextWithDocumentTest() {
    String ak = System.getenv("ak");
    String sk = System.getenv("sk");
    Document document = PdfHandler.getDocumentHandler().load("E:\\PDF\\pdfbox\\allTest.pdf");
    TencentAIParser parser = PdfHandler.getDocumentAIParser(document).getTencentAI(ak, sk, true);
    AIParseInfo info = parser.parseTextWithDocument("提取表格内容，以json格式返回");
    log.info("返回内容：\n" + info.getResult());
    document.close();
}