iText 2.1.7 中向扫描PDF或HTML转PDF添加图像失效的解决方案-java教程-PHP中文网

iText 2.1.7 中向扫描PDF或HTML转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 <blockquote><p>? addImage(..., true) 中的 true 表示启用原生图像压缩（推荐保留），适用于 PNG/JPEG 等格式。</p></blockquote><h3>坐标系统适配：避免位置偏移</h3><p>另一个易忽略的问题是坐标基准。PDF 的默认用户坐标系原点在<strong>左下角</strong>，但 Image.setAbsolutePosition(x, y) 中的 (x, y) 是相对于该原点的绝对坐标。若未显式考虑页面裁剪框（CropBox）的实际边界，图像可能被裁剪或定位错误，尤其在非标准尺寸PDF中。</p><p>建议在设置位置前，主动获取并校准坐标：</p><pre class="brush:php;toolbar:false;">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导出）上可靠叠加图像。