iText 7 HTML转PDF页面尺寸异常求助：容器宽度未达预期值

你遇到的核心问题是CSS像素与PDF点单位的转换差异，加上iText 7 HTML渲染器的默认配置没有匹配你的目标宽度。下面是具体分析和可行的解决方案：

问题根源 #

iText 7处理HTML时，默认会将CSS像素（px）转换为PDF的点（pt），转换规则基于标准屏幕DPI（96dpi）：
1px = 72/96 = 0.75pt
你设置的容器宽度是512px，对应PDF点值是 512 * 0.75 = 384pt，这和你看到的385pt（可能是四舍五入或默认边距导致的微小偏差）完全对应——说明iText默认执行了单位转换，但你没有明确指定渲染的目标宽度，导致它用了默认的页面/设备宽度来布局，而非你期望的512px对应的尺寸。

解决方案：明确配置渲染参数 #

你需要通过ConverterProperties设置媒体设备描述（MediaDeviceDescription），强制渲染器按目标宽度布局，同时先完成一次布局计算获取实际高度，再生成对应尺寸的单页PDF。

步骤1：单位转换计算 #

先把你的目标像素宽度转成PDF点单位：

// 目标宽度（像素）
float targetWidthPx = 512;
// 网页默认DPI是96，PDF默认DPI是72，完成单位转换
float targetWidthPt = targetWidthPx * 72 / 96;

步骤2：预布局获取实际高度 #

先执行一次布局计算，得到HTML内容渲染后的实际高度：

String htmlContent = "你的Velocity模板渲染后的HTML内容";
ConverterProperties properties = new ConverterProperties();

// 设置媒体设备的宽度，强制渲染器按目标宽度布局
MediaDeviceDescription mediaDevice = new MediaDeviceDescription(MediaType.SCREEN);
mediaDevice.setWidth(targetWidthPt);
properties.setMediaDeviceDescription(mediaDevice);

// 临时PDF用于布局计算
ByteArrayOutputStream tempStream = new ByteArrayOutputStream();
PdfDocument tempPdf = new PdfDocument(new PdfWriter(tempStream));
Document tempDoc = new Document(tempPdf);
HtmlConverter.convertToDocument(htmlContent, tempDoc, properties);

// 执行布局，获取实际占用高度
LayoutResult layoutResult = tempDoc.getRenderer().layout(new LayoutContext(new LayoutArea(1, new Rectangle(targetWidthPt, 10000))));
float actualHeightPt = layoutResult.getOccupiedArea().getBBox().getHeight();

// 关闭临时文档
tempDoc.close();
tempPdf.close();

步骤3：生成自定义尺寸的单页PDF #

用获取到的实际高度创建自定义页面尺寸的PDF，再正式渲染HTML：

ByteArrayOutputStream finalPdfStream = new ByteArrayOutputStream();
PdfDocument finalPdf = new PdfDocument(new PdfWriter(finalPdfStream));
// 创建自定义页面：宽度为目标点值，高度为实际布局高度
PageSize customPageSize = new PageSize(targetWidthPt, actualHeightPt);
Document finalDoc = new Document(finalPdf, customPageSize);

// 渲染HTML到自定义尺寸的PDF
HtmlConverter.convertToDocument(htmlContent, finalDoc, properties);
finalDoc.close();
finalPdf.close();

额外注意事项 #

• 消除默认边距：在HTML的CSS里添加body { margin: 0; padding: 0; }，避免body的默认边距占用额外的宽度或高度。
• 适配打印机DPI：如果你的热敏打印机有特定DPI（比如常见的203dpi），需要调整单位转换的DPI参数，确保最终PNG的尺寸匹配打印机要求。

内容的提问来源于stack exchange，提问作者Dede