使用iText pdfHTML转换HTML为PDF时Grid CSS失效求助

• 未适配pdfHTML的CSS支持限制
  浏览器支持的CSS属性远多于pdfHTML，像flex布局的部分细节、grid高级特性、CSS全局变量、position: sticky等特性，pdfHTML对其支持有限。检查你的HTML代码，替换掉这类非兼容属性，比如用float替代部分flex场景，改用pdfHTML兼容的CSS写法。

• 缺少pdfHTML专用的页面/容器配置
  默认转换逻辑可能未设置合适的页面尺寸、边距或容器宽高约束。浏览器中块级元素会自适应视口，但PDF需要明确页面参数，否则元素易溢出或挤压。可以在HTML中添加@page规则定义页面属性：

  @page {
    size: A4;
    margin: 20mm;
  }
  

  也可在Java代码里通过ConverterProperties设置模拟屏幕的媒体设备参数：

  ConverterProperties properties = new ConverterProperties();
  properties.setMediaDeviceDescription(new MediaDeviceDescription(MediaType.SCREEN));
  

• 字体未正确嵌入或加载
  浏览器会自动 fallback 系统字体，但pdfHTML遇到未嵌入的字体时会替换为默认字体，导致文字排版、行高、宽度变化，进而打乱布局。确保所有用到的字体都通过FontProvider嵌入：

  FontProvider fontProvider = new DefaultFontProvider();
  fontProvider.addFont("path/to/your/font.ttf");
  ConverterProperties properties = new ConverterProperties();
  properties.setFontProvider(fontProvider);
  

• 未处理图片的尺寸约束
  浏览器会自动缩放图片适配容器，但pdfHTML对无尺寸约束的图片可能按原始尺寸渲染，导致溢出页面。给图片明确设置width/height属性，或用CSS限制：

  img {
    max-width: 100%;
    height: auto;
  }
  

• 忽略了pdfHTML的盒模型差异
  pdfHTML的盒模型计算和浏览器存在细微差异，比如padding、border的叠加方式，或box-sizing默认值。强制统一盒模型规则：

  * {
    box-sizing: border-box;
  }
  

• Java转换逻辑未配置必要参数
  若HTML包含JS动态修改布局，需开启JS支持；若有外部资源（CSS、图片），需设置baseUri确保资源加载成功：

  ConverterProperties properties = new ConverterProperties();
  properties.setBaseUri("file:///path/to/your/resources/");
  properties.setEnableJavascript(true);
  

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