本文详解为何在 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导出）上可靠叠加图像。
