iText 2.1.7 中向扫描PDF或HTML转PDF添加图片失效的解决方案

使用 itext 2.1.7 向扫描pdf或html生成的pdf中添加图片时，若采用 `getundercontent()` 方法，图片常被底层内容遮挡而不可见；根本原因在于这类pdf存在全页覆盖图像或白底矩形，正确做法是改用 `getovercontent()` 并校准坐标系。

在 PDF 内容叠加操作中，PdfStamper 提供了三类内容层：getUnderContent()（底层）、getOverContent()（顶层）和 getDuplicateContent()（副本层）。你当前的代码：

PdfContentByte under = stamp.getUnderContent(pageOfPDF);under.addImage(images.get(feuilletCpt < feuilletTot ? "NL" + seq : "L" + seq), true);

将图片绘制在页面最底层。这在空白或结构简单（如纯文本生成）的 PDF 中可正常显示，但在以下两类文档中必然失败：

✅ 扫描PDF：通常由单张高分辨率位图（如 TIFF/JPEG 转换而来）铺满整个 CropBox，完全覆盖底层区域；✅ HTML 转 PDF（如 html2pdf.com 生成）：多数转换器会在页面初始化时先绘制一个白色 Rectangle 或背景色块作为画布底衬，导致 UnderContent 内容被彻底遮挡。

✅ 正确做法：使用 getOverContent()

只需将 getUnderContent() 替换为 getOverContent()，确保图片绘制在所有已有内容之上：

PdfContentByte over = stamp.getOverContent(pageOfPDF); // ← 关键修改over.addImage(images.get(feuilletCpt < feuilletTot ? "NL" + seq : "L" + seq), true);

该方式无需修改图像创建逻辑（如 scalePercent()、setAbsolutePosition()），兼容原有 Image 实例。

立即学习“前端免费学习笔记（深入）”；

⚠️ 补充注意事项：坐标系对齐

PDF 的用户坐标系原点默认位于页面左下角，但 HTML 转换或扫描PDF可能设置了非标准 CropBox 或 MediaBox。若图片位置偏移或截断，请显式校准坐标：

Rectangle pageSize = reader.getPageSize(pageOfPDF);float x = posX + pageSize.getLeft(); // 校正横坐标float y = posY + pageSize.getBottom(); // 校正纵坐标im.setAbsolutePosition(x, y);

? 总结

场景推荐方法原因空白/文本PDFgetUnderContent() 可用底层无遮挡扫描PDF / HTML转PDF✅ 必须用 getOverContent()避免被全页图像或底色覆盖定位不准✅ 使用 reader.getPageSize().getLeft()/getBottom() 校准兼容自定义裁剪与旋转

最后提醒：iText 2.1.7 已停止维护（最新稳定版为 iText 7.x），若项目允许，建议升级至 iText 7 并使用 PdfCanvas API，其分层语义更清晰、坐标处理更安全。但针对存量系统，上述 OverContent 方案可立即修复问题，零成本、高可靠性。