Android图片转PDF总结

Android 图片转 PDF 总结整理日期2026-07-30适用单图/多图转 PDF、扫描件归档、证件导出等场景原生 APIandroid.graphics.pdf.PdfDocumentAPI 19目录1. 概述2. 方案对比3. 原生 PdfDocument推荐首选3.1 基本流程3.2 单图转 PDFKotlin3.3 多图合并为一份 PDF3.4 固定纸张如 A4等比适配4. 第三方库方案4.1 PdfBox-Android4.2 iText / OpenPDF4.3 PrintedPdfDocument / 打印框架5. 图片预处理要点6. 存储与权限7. 性能与内存8. 常见坑与排查9. 推荐落地 Checklist10. 优缺点总览11. 参考链接1. 概述Android 上将图片JPEG/PNG/WebP 等转为 PDF本质是解码为Bitmap或库直接读文件创建 PDF 页面纸张尺寸多为pt1 pt 1/72 inch将图片绘制/嵌入到页面写入文件或ParcelFileDescriptor/ SAF Uri维度说明最简官方方案PdfDocumentCanvas.drawBitmap最低 API19KitKat即可用原生生成典型产物扫描 PDF、相册导出、表单附件与预览关系生成用PdfDocument预览用PdfRenderer反向PDF→Bitmap2. 方案对比方案依赖适合场景许可注意包体/复杂度PdfDocument系统自带图片铺满页、简单多页无最低PrintedPdfDocument系统自带按打印属性介质尺寸、边距出 PDF无低PdfBox-Androidcom.tom-roush:pdfbox-android需合并/加密/读改已有 PDFApache 2.0中iTextMaven 商业/AGPL复杂排版、表单、签名、合规AGPL 或商用授权高OpenPDF开源 fork中等复杂度生成LGPL/MPL 等中WebView / HTML→PDF系统 Print图文混排、CSS 布局无中质量与分页难控选型建议只做「多张图 → 多页 PDF」→优先 PdfDocument要加密、合并已有 PDF、抽图 →PdfBox-Android强排版/签名/PDF/A → 评估iText注意授权3. 原生 PdfDocument推荐首选3.1 基本流程创建 PdfDocument → 循环PageInfo.Builder(宽, 高, 页码).create() → startPage → Canvas 绘制 Bitmap → finishPage → writeTo(OutputStream) → close()注意同一时刻只能有一个未 finish 的 Page非线程安全后台线程串行生成即可PageInfo宽高单位是PostScript point1/72 英寸不是像素用「像素值当 pt」时打印出来的物理尺寸会偏大/偏小需按纸张规格换算或「页图」策略3.2 单图转 PDFKotlin「一页尺寸 图片像素」——实现快适合屏幕查看打印物理尺寸不保证 A4。funbitmapToPdf(bitmap:Bitmap,output:OutputStream){valdocumentPdfDocument()try{valpageInfoPdfDocument.PageInfo.Builder(bitmap.width,bitmap.height,/* pageNumber */1).create()valpagedocument.startPage(pageInfo)page.canvas.drawBitmap(bitmap,0f,0f,null)document.finishPage(page)document.writeTo(output)}finally{document.close()}}从文件路径解码时建议采样避免 OOMfundecodeSampled(path:String,maxSide:Int):Bitmap{valboundsBitmapFactory.Options().apply{inJustDecodeBoundstrue}BitmapFactory.decodeFile(path,bounds)varsample1vallongestmaxOf(bounds.outWidth,bounds.outHeight)while(longest/samplemaxSide)sample*2valoptsBitmapFactory.Options().apply{inSampleSizesample inPreferredConfigBitmap.Config.RGB_565// 文档扫描可降内存透明 PNG 用 ARGB_8888}returnBitmapFactory.decodeFile(path,opts)?:error(decode failed:$path)}3.3 多图合并为一份 PDFfunimagesToPdf(bitmaps:ListBitmap,output:OutputStream){require(bitmaps.isNotEmpty())valdocumentPdfDocument()try{bitmaps.forEachIndexed{index,bitmap-valpageInfoPdfDocument.PageInfo.Builder(bitmap.width,bitmap.height,index1).create()valpagedocument.startPage(pageInfo)page.canvas.drawBitmap(bitmap,0f,0f,null)document.finishPage(page)}document.writeTo(output)}finally{document.close()// 若 Bitmap 由本方法独占可在此 recycle}}业务上常见每张图一页也可多图拼一页自行算网格RectF。3.4 固定纸张如 A4等比适配A4 竖向约595 × 842 pt210mm × 297mm 72dpi。privateconstvalA4_WIDTH595privateconstvalA4_HEIGHT842fundrawBitmapFitA4(canvas:Canvas,bitmap:Bitmap,margin:Float24f){valcontentWA4_WIDTH-margin*2valcontentHA4_HEIGHT-margin*2valscaleminOf(contentW/bitmap.width,contentH/bitmap.height)valdstWbitmap.width*scalevaldstHbitmap.height*scalevalleftmargin(contentW-dstW)/2fvaltopmargin(contentH-dstH)/2fvaldstRectF(left,top,leftdstW,topdstH)canvas.drawColor(android.graphics.Color.WHITE)canvas.drawBitmap(bitmap,null,dst,null)}funbitmapsToA4Pdf(bitmaps:ListBitmap,output:OutputStream){valdocumentPdfDocument()try{bitmaps.forEachIndexed{index,bitmap-valpageInfoPdfDocument.PageInfo.Builder(A4_WIDTH,A4_HEIGHT,index1).create()valpagedocument.startPage(pageInfo)drawBitmapFitA4(page.canvas,bitmap)document.finishPage(page)}document.writeTo(output)}finally{document.close()}}横图可改为横向页面842 × 595或统一竖版留白。4. 第三方库方案4.1 PdfBox-Android仓库TomRoush/PdfBox-Android依赖示例implementation(com.tom-roush:pdfbox-android:version)使用前PDFBoxResourceLoader.init(context)适合向已有 PDF 插页、合并多个 PDF、加密、读文本/元数据。图片转 PDF用PDImageXObject嵌入矢量文字可选中比纯 Bitmap 页更「文档化」。优点Apache 2.0能力接近桌面 PDFBox内存表现往往较好缺点APK 增大API 偏重需注意 Android 兼容与 ProGuard4.2 iText / OpenPDFiText功能最全表格、水印、签名、PDF/A闭源商用通常需付费AGPL 有传染风险OpenPDF开源替代适合中等复杂度纯「图片拼 PDF」一般不必上 iText除非已有企业授权或强合规需求。4.3 PrintedPdfDocument / 打印框架valprintAttrsPrintAttributes.Builder().setMediaSize(PrintAttributes.MediaSize.ISO_A4).setResolution(PrintAttributes.Resolution(pdf,pdf,300,300)).setMinMargins(PrintAttributes.Margins.NO_MARGINS).build()valdocumentPrintedPdfDocument(context,printAttrs)// page document.startPage(0) …优点纸张、边距、分辨率与系统打印模型一致缺点仍要自己画内容偏「打印管线」不如直接 PdfDocument 直观另PrintManagerPrintDocumentAdapter可走系统打印 UI用户另存为 PDF依赖厂商打印服务。5. 图片预处理要点项建议EXIF 旋转用ExifInterface读ORIENTATION转正后再写入 PDF避免「相册竖图 PDF 横着」色域/格式扫描件可用RGB_565需透明通道用ARGB_8888压缩源文件JPEG 质量与采样平衡PDF 内嵌的是绘制结果过大 Bitmap 会撑内存与文件体积超长图可裁成多页或缩放到页高后一页展示HEIC部分机型需转 JPEG/Bitmap 再处理矢量PdfDocument 画 Bitmap 后文字不可选中需要可选文字要用 PDF 库画文字层EXIF 校正示意funBitmap.rotateIfNeeded(path:String):Bitmap{valexifExifInterface(path)valdegreewhen(exif.getAttributeInt(ExifInterface.TAG_ORIENTATION,ExifInterface.ORIENTATION_NORMAL)){ExifInterface.ORIENTATION_ROTATE_90-90ExifInterface.ORIENTATION_ROTATE_180-180ExifInterface.ORIENTATION_ROTATE_270-270else-0}if(degree0)returnthisvalmMatrix().apply{postRotate(degree.toFloat())}returnBitmap.createBitmap(this,0,0,width,height,m,true)}6. 存储与权限目标做法App 私有context.filesDir/cacheDir无需存储权限用户可见「下载/文档」MediaStoreDownloads/Documents或 SAFCreateDocument分享FileProviderIntent.ACTION_SENDapplication/pdfAndroid 10避免直接写Environment.getExternalStorageDirectory()用分区存储 APISAF 创建示例意图valintentIntent(Intent.ACTION_CREATE_DOCUMENT).apply{addCategory(Intent.CATEGORY_OPENABLE)typeapplication/pdfputExtra(Intent.EXTRA_TITLE,images.pdf)}// Activity Result 拿到 Uri 后 openOutputStream(uri) 写入7. 性能与内存后台线程生成Dispatchers.IO/Executor主线程只更进度逐页解码多图时不要一次把全部原图 Bitmap 留在堆上一页写完可recycle限制长边如 20484096再 draw 到 A4盲目用原图像素当页尺寸易 OOMPdfDocument 非线程安全多任务排队大文件写入用缓冲流写完关闭PdfDocument与流粗算一张ARGB_8888的 4000×3000 图约48MB堆内存多图并行极易崩溃。8. 常见坑与排查现象可能原因处理PDF 空白未finishPage/ 画在错误 Canvas / Bitmap 已 recycle检查调用顺序打印尺寸离谱把 px 当成 pt改用 A4 pt RectF缩放方向错误忽略 EXIF解码后旋转OOM原图过大、多图常驻inSampleSize、逐页、降配置文件打不开未writeTo或中途异常未 closetry/finally校验文件头%PDF分享失败未用 FileProvider / URI 权限FLAG_GRANT_READ_URI_PERMISSION文字不可选整页是位图预期行为需文字层则换 PDF 库9. 推荐落地 Checklist明确纸张策略页随图 vs 固定 A4/LetterEXIF 方向校正采样解码 后台生成 进度回调输出到 App 目录或 SAF/MediaStore分享走 FileProvider多图顺序、失败重试、取消任务低端机用 23 张大图压测内存用系统「文件」/ Adobe Reader 打开校验若需加密/合并已有 PDF再引入 PdfBox10. 优缺点总览PdfDocument图片转 PDF优点零依赖、API 简单、生成快、够用绝大多数「图转 PDF」缺点弱于复杂排版/加密/编辑页尺寸易用错单位内容多为位图PdfBox-Android优点开源协议友好读写合并加密强嵌入图更「标准」缺点体积与学习成本高纯拼图场景偏重iText优点企业级能力最全缺点授权成本/合规风险简单转图不划算11. 参考链接PdfDocumentPdfDocument.PageInfo.BuilderPrintedPdfDocumentPdfRenderer预览PdfBox-AndroidExifInterface一句话结论业务只是「图片生成/合并 PDF」时用系统PdfDocument 采样解码 可选A4 等比绘制 SAF/FileProvider即可需要加密、改已有 PDF 再上PdfBox-Android。