如何用iText、HTML和Thymeleaf实现PDF多页重复页眉Logo

核心思路 #

Flying-Saucer遵循CSS Paged Media规范，要实现跨页重复页眉，需通过@page规则定义页面区域，结合特定CSS属性标记可复用的页眉元素。

具体实现步骤 #

1. 配置页面边距与页眉区域
   在CSS中用@page规则为页面设置边距，并指定页眉显示的位置：

   @page {
     size: A4;
     /* 上边缘预留足够空间放置页眉 */
     margin: 80px 20px 40px 20px;
     
     /* 将页眉元素绑定到页面顶部中心区域 */
     @top-center {
       content: element(header);
     }
   }
   

2. 设置页眉元素的可复用样式
   为包含Logo和页眉内容的容器添加专属样式，标记其为可跨页复用的页眉：

   #header {
     /* 关键属性：标记为可运行的页眉元素 */
     position: running(header);
     width: 100%;
     /* 高度需小于@page设置的上边距，避免和正文重叠 */
     height: 60px;
     border-bottom: 1px solid #eee;
     padding: 10px 0;
   }
   
   #header .logo {
     height: 40px;
     margin-left: 15px;
   }
   
   #header .doc-title {
     float: right;
     margin-right: 15px;
     font-size: 16px;
     font-weight: 600;
     line-height: 40px;
   }
   

3. 调整HTML模板结构
   在正文内容前添加页眉容器，确保Flying-Saucer能识别并复用它：

   <!-- 页眉容器，需放在正文之前 -->
   <div id="header">
     <img class="logo" th:src="@{/images/your-logo.png}" alt="Logo">
     <span class="doc-title" th:text="${documentTitle}">文档标题</span>
   </div>
   
   <!-- 正文内容区域，即使跨页也会自动重复页眉 -->
   <div id="content">
     <!-- Thymeleaf渲染的动态内容 -->
     <div th:each="item : ${dataList}">
       <p th:text="${item.content}"></p>
     </div>
   </div>
   

4. 常见问题排查

   • 若页眉与正文重叠，检查@page的上边距是否大于等于页眉容器的高度。
   • 若Logo不显示，确认图片路径为Flying-Saucer可解析的路径（可通过设置资源解析器处理相对路径）。
   • 动态内容渲染异常时，确保Thymeleaf表达式在页眉容器中正常解析，Flying-Saucer会保留渲染后的内容进行复用。

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