Qweb(Odoo)中页眉间距与上边距为何随页码不同表现不一致？

问题描述 #

自定义Odoo PDF报表布局时，因采用了小尺寸页眉，最初对Euro纸张格式做如下配置：

<record id="base.paperformat_euro" model="report.paperformat">
    <field name="margin_top">10</field>
    <field name="header_spacing">5</field>
</record>

该配置存在全局参数无法同时适配多页显示的问题：

• 初始参数下仅首页显示正常，第二页及后续页的正文顶部会被页眉遮挡
• 调大margin_top与header_spacing参数后，后续页可正常显示，但首页页眉与正文之间留白过大
• 取中间参数值时两页显示均异常：首页页眉下方留白超出设计要求，后续页页眉预留间距不足，正文合计行上方的分隔线会被页眉完全遮挡
• 参数调小会加剧后续页遮挡问题，参数调大会放大首页留白问题，常规调整纸张格式参数的方式无法同时满足多页显示要求。
  目标是寻找更优解决方案，避免使用「调大全局间距参数后，再为首页顶部元素设置负边距/内边距」的折中处理方式。

实现方案 #

以下方案均不需要对正文元素设置负边距，可从渲染机制层面解决间距不一致问题：

• 方案1：通过打印CSS伪类单独控制首页边距
  首先将纸张格式的margin_top、header_spacing设置为满足后续页显示的数值，保证所有非首页的正文不会被页眉遮挡。之后在报表引入的自定义CSS中，通过:first-page伪类单独给首页设置更小的顶部边距，抵消全局边距带来的首页多余留白：

  /* 全局页边距适配非首页页眉高度 */
  @page {
      margin-top: 20mm;
  }
  /* 首页单独设置紧凑顶部边距，匹配小页眉设计 */
  @page :first {
      margin-top: 10mm;
  }
  

  该方案基于W3C标准打印CSS规则实现，wkhtmltopdf 0.12.5及以上版本对该特性支持稳定，不需要修改QWeb模板逻辑。

• 方案2：通过QWeb页码判断逻辑拆分页眉占位
  Odoo QWeb报表渲染时内置了page页码变量，可以直接在页眉模板中判断当前页码：首页渲染无额外底部占位的小尺寸页眉，非首页渲染带对应底部间距的页眉，配合统一的纸张格式参数即可实现多页间距适配。该方案完全兼容低版本wkhtmltopdf，不需要依赖CSS高级特性。

• 方案3：改用CSS running元素实现自定义页眉
  废弃Odoo默认的页眉渲染与间距计算逻辑，将纸张格式的header_spacing设为0，在报表正文模板中编写自定义页眉内容，通过CSS的running元素特性将页眉固定到每页顶部，页眉占位高度完全由CSS自定义控制，不会出现默认逻辑下首页、非首页间距计算不一致的问题：

  .report-custom-header {
      position: running(header);
      height: 8mm; /* 与设计的小页眉实际高度完全一致 */
  }
  @page {
      margin-top: 10mm;
      @top-center {
          content: element(header);
      }
  }
  

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