iText 2.1.7 添加图片失效解决方法

本文深入剖析了在老旧的iText 2.1.7中向扫描PDF或HTML生成的PDF添加图片时图像“神秘消失”的根本原因——并非代码错误，而是`getUnderContent()`将图像绘制在底层，被扫描件的全页位图或HTML转PDF的背景填充彻底遮盖；文章直击痛点，给出即插即用的解决方案：果断切换至`getOverContent()`确保图像始终显示在最上层，并辅以CropBox坐标精准校准、路径加载健壮性处理及实用调试技巧，同时坦诚提醒该版本已停更多年，强烈建议升级至iText 7以获得长期安全与原生支持，让开发者一次搞定跨源PDF图像叠加难题。

本文详解为何在 iText 2.1.7 中使用 getUnderContent() 向扫描PDF或HTML生成的PDF添加图像时图像不可见，并提供正确使用 getOverContent()、坐标适配及兼容性处理的专业方案。

本文详解为何在 iText 2.1.7 中使用 `getUnderContent()` 向扫描PDF或HTML生成的PDF添加图像时图像不可见，并提供正确使用 `getOverContent()`、坐标适配及兼容性处理的专业方案。

在使用 iText 2.1.7（com.lowagie.itext）对现有 PDF 进行图像叠加时，开发者常遇到一个典型问题：代码在普通生成的 PDF 上运行正常，但在扫描件（如OCR前的纯图像PDF）或 HTML 转 PDF（如通过 html2pdf.com 生成）文档中，调用 stamp.getUnderContent(page) 添加的图像完全不可见。根本原因在于 图层渲染顺序与页面内容覆盖关系，而非图像加载或路径错误。

核心问题：UnderContent 的可见性陷阱

PDF 页面内容按“底层→顶层”分层绘制。getUnderContent() 返回的是页面最底层的绘图上下文——它位于所有已有内容（包括背景图像、填充矩形等）之下。而：

• ✅ 常规PDF（如iText原生生成）：页面内容稀疏，底层留白充足 → 图像可见；
• ❌ 扫描PDF：每页本质是一张全幅位图（ImageXObject），占据整个 CropBox → 完全覆盖 UnderContent，图像被遮挡；
• ❌ HTML转PDF（如 html2pdf.com）：多数工具会在页面起始处绘制一个白色 Rectangle 或 Background 填充，同样覆盖底层 → 图像不可见。

因此，修复的关键是将图像绘制到顶层（OverContent），确保其始终显示在所有既有内容之上：

// ✅ 正确做法：使用 OverContent 替代 UnderContent
PdfContentByte over = stamp.getOverContent(pageOfPDF); // 注意：pageOfPDF 是 int 类型页码（从1开始）
over.addImage(images.get(feuilletCpt < feuilletTot ? "NL" + seq : "L" + seq), true);

? addImage(..., true) 中的 true 表示启用原生图像压缩（推荐保留），适用于 PNG/JPEG 等格式。

坐标系统适配：避免位置偏移

另一个易忽略的问题是坐标基准。PDF 的默认用户坐标系原点在左下角，但 Image.setAbsolutePosition(x, y) 中的 (x, y) 是相对于该原点的绝对坐标。若未显式考虑页面裁剪框（CropBox）的实际边界，图像可能被裁剪或定位错误，尤其在非标准尺寸PDF中。

建议在设置位置前，主动获取并校准坐标：

PdfReader reader = new PdfReader(inputPdfPath);
PdfStamper stamp = new PdfStamper(reader, new FileOutputStream(outputPdfPath));

int pageOfPDF = 1;
Rectangle cropBox = reader.getCropBox(pageOfPDF); // 获取当前页裁剪区域
float llx = cropBox.getLeft();   // 左下角X
float lly = cropBox.getBottom(); // 左下角Y

// 将目标位置（posX, posY）映射到实际页面坐标系中
float finalX = llx + posX;
float finalY = lly + posY;

Image img = getBlackAndWhiteBarCode("/img/Last01.png", finalX, finalY);
PdfContentByte over = stamp.getOverContent(pageOfPDF);
over.addImage(img, true);

此方式确保无论PDF来源如何（扫描/HTML转换/手动生成），图像均精准锚定在页面可视区域内。

补充注意事项与最佳实践

• iText 版本警示：com.lowagie.itext 2.1.7 是已停止维护的旧版（2009年左右），存在安全风险与功能限制。生产环境强烈建议升级至 iText 7.x（com.itextpdf:itext7-core），其 API 更健壮，对扫描PDF/混合内容支持更完善，且内置 PdfCanvas 明确区分 underLayer/defaultLayer/overLayer。
• 图像格式兼容性：确保 getBlackAndWhiteBarCode() 中 Image.getInstance(...) 能正确解析资源路径。若图片来自 classpath，推荐使用 Image.getInstance(ClassLoader.getSystemResource(filename)) 避免空指针。
• 内存与性能：对多页PDF批量处理时，PdfStamper 会加载整份文档至内存。若PDF体积大（如高DPI扫描件），需监控堆内存，必要时采用分页处理或流式写入策略。
• 调试技巧：临时添加一个半透明矩形到 OverContent，可快速验证图层是否生效：

  over.setColorFill(BaseColor.LIGHT_GRAY);
  over.rectangle(finalX, finalY, 100, 50);
  over.fill();

综上，解决该问题的核心逻辑是：弃用 UnderContent，改用 OverContent 绘制；显式校准页面 CropBox 坐标；并前瞻性评估旧版iText的技术债务。遵循上述方案，即可稳定实现在任意来源PDF（含扫描件与HTML导出）上可靠叠加图像。

以上就是《iText 2.1.7 添加图片失效解决方法》的详细内容，更多关于的资料请关注golang学习网公众号！