针对你遇到的每页不同高度页眉/页脚导致布局偏移的问题，咱们可以从动态调整页边距和优化页眉页脚渲染方式两个方面来解决，同时纠正直接粘贴XObject的非最佳实践：

一、核心解决方案：每页初始化前动态设置边距 #

iText允许在页面开始渲染前（onStartPage事件）修改Document的页边距，这样iText在计算内容布局时会自动预留出页眉/页脚的空间，从根源上避免内容重叠。具体步骤如下：

1. 自定义页面事件处理器 #

创建一个事件处理器类，负责在每页开始前设置对应边距，并在页面结束后绘制页眉/页脚到预留的边距区域：

public class DynamicPageEventHandler extends PdfPageEventHelper {
    // 存储当前页的页眉/页脚高度
    private float currentHeaderHeight = 0f;
    private float currentFooterHeight = 0f;
    // 可选：存储当前页要使用的页眉/页脚XObject
    private PdfXObject currentHeaderXObject;
    private PdfXObject currentFooterXObject;

    // 提供方法，提前设置当前页的页眉/页脚参数
    public void setCurrentPageParams(float headerHeight, float footerHeight, 
                                     PdfXObject headerXObject, PdfXObject footerXObject) {
        this.currentHeaderHeight = headerHeight;
        this.currentFooterHeight = footerHeight;
        this.currentHeaderXObject = headerXObject;
        this.currentFooterXObject = footerXObject;
    }

    // 在页面开始渲染前调整边距
    @Override
    public void onStartPage(PdfWriter writer, Document document) {
        // 边距 = 页眉/页脚高度 + 基础留白（可根据需求调整）
        float baseTopMargin = 20f;
        float baseBottomMargin = 15f;
        document.setMargins(
            document.leftMargin(),
            document.rightMargin(),
            currentHeaderHeight + baseTopMargin,
            currentFooterHeight + baseBottomMargin
        );
    }

    // 在页面渲染完成后绘制页眉/页脚到预留区域
    @Override
    public void onEndPage(PdfWriter writer, Document document) {
        PdfCanvas canvas = new PdfCanvas(writer.getDirectContentUnder());
        // 绘制页眉：位置从页面顶部向下偏移页眉高度（预留的边距区域内）
        if (currentHeaderXObject != null) {
            canvas.addXObject(currentHeaderXObject, 
                              document.left(), 
                              document.top() - currentHeaderHeight);
        }
        // 绘制页脚：位置从页面底部向上偏移页脚高度
        if (currentFooterXObject != null) {
            canvas.addXObject(currentFooterXObject, 
                              document.left(), 
                              document.bottom() + currentFooterHeight);
        }
    }
}

2. 结合HtmlConverter.convertToElements()手动控制文档构建 #

使用convertToElements()将HTML转为可操作的IElement列表，这样可以在添加内容前为每页设置对应的页眉/页脚参数：

public static void main(String[] args) throws IOException {
    // 1. 转换HTML为元素列表
    ConverterProperties converterProps = new ConverterProperties();
    List<IElement> contentElements = HtmlConverter.convertToElements(
        new FileInputStream("your-input.html"), converterProps
    );

    // 2. 初始化PDF文档和事件处理器
    PdfWriter writer = new PdfWriter("output.pdf");
    PdfDocument pdfDoc = new PdfDocument(writer);
    Document doc = new Document(pdfDoc);

    DynamicPageEventHandler eventHandler = new DynamicPageEventHandler();
    pdfDoc.addEventHandler(PdfDocumentEvent.START_PAGE, eventHandler);
    pdfDoc.addEventHandler(PdfDocumentEvent.END_PAGE, eventHandler);

    // 3. 准备每页的页眉/页脚数据（示例：3页不同高度的页眉页脚）
    // 假设已经提前将每页的页眉HTML转为PdfXObject并获取高度
    List<PageHeaderFooter> pageParams = Arrays.asList(
        new PageHeaderFooter(50f, 20f, generateHeaderXObject("header1.html"), generateFooterXObject("footer1.html")),
        new PageHeaderFooter(30f, 25f, generateHeaderXObject("header2.html"), generateFooterXObject("footer2.html")),
        new PageHeaderFooter(40f, 20f, generateHeaderXObject("header3.html"), generateFooterXObject("footer3.html"))
    );

    // 4. 遍历元素添加到文档，同时为每页设置参数
    int currentPageIndex = 0;
    for (IElement element : contentElements) {
        // 检查当前是否为新页面（可通过pdfDoc.getNumberOfPages()判断，这里简化处理）
        if (currentPageIndex < pageParams.size()) {
            PageHeaderFooter params = pageParams.get(currentPageIndex);
            eventHandler.setCurrentPageParams(
                params.getHeaderHeight(), params.getFooterHeight(),
                params.getHeaderXObject(), params.getFooterXObject()
            );
        }
        doc.add(element);
        // 每次添加元素后，如果触发了分页，递增页面索引
        if (pdfDoc.getNumberOfPages() > currentPageIndex + 1) {
            currentPageIndex++;
        }
    }

    doc.close();
}

// 辅助方法：将HTML转为PdfXObject并返回（包含高度信息）
private static PdfXObject generateHeaderXObject(String htmlPath) throws IOException {
    ConverterProperties props = new ConverterProperties();
    PdfDocument tempPdf = new PdfDocument(new PdfWriter(new ByteArrayOutputStream()));
    Document tempDoc = new Document(tempPdf);
    List<IElement> headerElements = HtmlConverter.convertToElements(new FileInputStream(htmlPath), props);
    for (IElement e : headerElements) {
        tempDoc.add(e);
    }
    tempDoc.close();
    // 将临时文档的第一页转为XObject
    return tempPdf.getPage(1).copyAsFormXObject(tempPdf);
}

// 辅助类：存储每页的页眉/页脚参数
static class PageHeaderFooter {
    private float headerHeight;
    private float footerHeight;
    private PdfXObject headerXObject;
    private PdfXObject footerXObject;

    // 构造方法、getter省略
}

二、关于页眉/页脚渲染的最佳实践 #

你提到的“将页眉/页脚粘贴到已生成的页面上”确实不是最佳实践，原因有两个：

• iText在计算内容分页时完全不知道这些额外内容的存在，很容易出现内容和页眉/页脚重叠的问题；
• 后期如果需要调整页眉/页脚高度，必须手动重新计算内容偏移，维护成本高。

更合理的做法是：

1. 先预留空间，再绘制内容：也就是上面方案中，先通过onStartPage调整边距，让iText在渲染内容时自动避开页眉/页脚区域，再在onEndPage里把页眉/页脚绘制到预留的边距空间内。
2. 结合CSS页面类（可选）：如果你的HTML中已经通过CSS的page-break-before或自定义类标记了分页点，可以在事件处理器中根据当前页的CSS类匹配对应的页眉/页脚参数，实现更灵活的关联。

关键注意点 #

• 必须在onStartPage事件中修改边距，onEndPage事件中修改边距不会影响当前页的内容布局；
• 如果页眉/页脚是从HTML生成的，一定要先获取其准确高度（可以通过临时文档渲染后获取页面高度），否则边距预留会不准确；
• 当内容自动分页时，要及时更新当前页的页眉/页脚参数，避免后续页面使用错误的边距。

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