Android平台PDFBox库使用指南：安全高效处理PDF文档

重要提示：本文聚焦于专为Android优化的PDFBox分支（PdfBox-Android），而非直接使用Apache原版PDFBox。原版PDFBox因依赖Java SE特有API（如javax.*）、内存管理差异及字体处理问题，在Android上极易崩溃。本文提供经过验证的可行方案。

一、为什么不能直接使用Apache PDFBox？

问题类型	原版PDFBox (Java SE)	Android环境
API兼容性	依赖`javax.imageio`等Java SE API	Android运行时缺失部分API
内存管理	假设大内存环境	移动端内存受限，易OOM
字体处理	依赖系统字体路径	Android字体路径与结构不同
线程安全	非主线程友好	需严格避免主线程阻塞

✅ 结论：切勿在build.gradle中直接添加org.apache.pdfbox:pdfbox！

二、推荐方案：PdfBox-Android（TomRoush维护版）

这是目前社区广泛采用的Android适配分支，已解决核心兼容性问题：

✅ 移除Java SE专属依赖
✅ 优化内存使用（流式处理支持）
✅ 适配Android字体系统
✅ 保留PDFBox 1.8.x核心API（熟悉PDFBox的开发者可快速上手）

⚠️ 注意：该项目最后一次活跃更新为2018年（GitHub仓库），适用于中小型PDF操作场景。对复杂需求或长期维护项目，文末提供替代方案建议。

三、集成与配置（Android Studio）

1. 添加依赖（Groovy DSL）

dependencies {
    // 核心库（PDFBox Android适配版）
    implementation 'com.tom_roush:pdfbox-android:1.8.10.1'
    
    // 可选：如需处理加密PDF
    implementation 'com.tom_roush:fontbox-android:1.8.10.1'
}

2. 声明必要权限（AndroidManifest.xml）

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" /> <!-- Android 13+需分区存储处理 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

📌 Android 6.0+需动态申请存储权限；Android 10+建议使用MediaStore或应用专属目录（context.filesDir）。

四、核心功能实战示例（Java）

✅ 场景1：创建带文本的PDF（后台线程执行！）

new Thread(() -> {
    try {
        PDDocument document = new PDDocument();
        PDPage page = new PDPage();
        document.addPage(page);

        // 使用Android内置字体（避免路径问题）
        PDFont font = PDType1Font.HELVETICA_BOLD; 
        PDPageContentStream contentStream = new PDPageContentStream(document, page);
        
        contentStream.beginText();
        contentStream.setFont(font, 18);
        contentStream.newLineAtOffset(50, 700);
        contentStream.showText("Hello from Android PDFBox!");
        contentStream.endText();
        contentStream.close();

        // 保存到应用私有目录（无需权限）
        File file = new File(context.getFilesDir(), "output.pdf");
        document.save(file);
        document.close();
        
        runOnUiThread(() -> Toast.makeText(context, "PDF已保存: " + file.getPath(), Toast.LENGTH_SHORT).show());
    } catch (IOException e) {
        e.printStackTrace();
        runOnUiThread(() -> Toast.makeText(context, "生成失败: " + e.getMessage(), Toast.LENGTH_SHORT).show());
    }
}).start();

✅ 场景2：提取PDF文本内容

public String extractTextFromPdf(File pdfFile) {
    StringBuilder text = new StringBuilder();
    try (PDDocument document = PDDocument.load(pdfFile)) {
        if (document.isEncrypted()) {
            // 简单处理：跳过加密文档（生产环境需密码）
            return "文档已加密";
        }
        PDFTextStripper stripper = new PDFTextStripper();
        text.append(stripper.getText(document));
    } catch (IOException e) {
        Log.e("PDFBox", "文本提取失败", e);
    }
    return text.toString();
}

✅ 场景3：向PDF添加本地图片（资源转PDImage）

// 将drawable资源转为PDImage（简化版）
public void addImageToPdf(PDDocument doc, int drawableResId) throws IOException {
    Bitmap bitmap = BitmapFactory.decodeResource(context.getResources(), drawableResId);
    ByteArrayOutputStream stream = new ByteArrayOutputStream();
    bitmap.compress(Bitmap.CompressFormat.PNG, 100, stream);
    byte[] bitmapData = stream.toByteArray();
    
    PDImageXObject pdImage = PDImageXObject.createFromByteArray(doc, bitmapData, "img.png");
    PDPageContentStream contentStream = new PDPageContentStream(doc, doc.getPage(0), true, true);
    contentStream.drawImage(pdImage, 50, 500, 200, 150); // x, y, width, height
    contentStream.close();
}

五、关键注意事项（避坑指南）

问题	解决方案
主线程卡顿/ANR	所有PDF操作必须在`AsyncTask`、`Coroutine`或新线程中执行
字体缺失/乱码	优先使用`PDType1Font`内置字体；自定义字体需转为`.ttf`并加载（注意License）
大文件OOM	分页处理；使用`PDFTextStripper.setStartPage()`/`setEndPage()`；及时`close()`流
Android 10+存储	保存至`context.getExternalFilesDir(null)`或使用SAF（Storage Access Framework）
ProGuard混淆	添加规则：-keep class org.apache.pdfbox.** { ; }``-dontwarn org.apache.pdfbox.*

六、替代方案对比（按场景选型）

库	优势	适用场景	推荐指数
PdfBox-Android	API熟悉、功能全面（创建/编辑/提取）	需生成/修改PDF、轻度文本处理	⭐⭐⭐
AndroidPdfViewer (barteksc)	渲染快、支持注释/表单、活跃维护	仅需查看/注释PDF（90%场景首选）	⭐⭐⭐⭐⭐
PdfRenderer (Android原生)	系统级、零依赖、内存高效	Android 5.0+、仅需渲染预览	⭐⭐⭐⭐
MuPDF	跨平台、高性能、支持注释	专业PDF阅读器、需深度定制	⭐⭐⭐⭐

💡 决策建议：

仅需显示PDF → 选 AndroidPdfViewer（集成简单，体验佳）

需生成/编辑PDF内容 → 评估 PdfBox-Android（注意维护状态）

企业级需求/长期项目 → 考察商业SDK（如 PSPDFKit、Foxit）

七、总结

PdfBox-Android为Android开发者提供了在移动端操作PDF文档的可行路径，尤其适合：

需动态生成简单PDF报告（如订单、票据）
从PDF中提取结构化文本数据
轻量级PDF内容修改（添加水印、页眉页脚）

但请牢记：

严格在子线程操作，做好异常与内存管理
优先使用应用私有目录存储，规避权限问题
复杂需求或新项目，优先评估AndroidPdfViewer等活跃维护库
上线前务必在低端机型测试性能与稳定性

🌐 资源链接

PdfBox-Android GitHub: https://github.com/TomRoush/PdfBox-Android

AndroidPdfViewer: https://github.com/barteksc/AndroidPdfViewer

官方PDFBox文档（参考API）: https://pdfbox.apache.org/docs/1.8.10/javadocs/

技术选型无银弹，贴合场景方为上策。 希望本文助你安全高效地驾驭Android PDF处理！