如何在iText7.pdfhtml生成的PDF中避免文本跨页（含边距设置）

我刚好处理过类似的iText7 pdfhtml分页问题，结合你使用的版本（7.1.2 + 2.0.2），给你几个针对性的解决方案，覆盖你遇到的所有场景：

一、修复设置边距后page-break-inside: avoid失效问题 #

核心原因是pdfhtml在计算元素布局时，自定义边距会干扰默认的可用空间判断，导致防跨页逻辑没触发。这里有两种可靠的解决方式：

方式1：HTML内联属性+自定义TagWorker强制保持元素完整性 #

在需要防跨页的容器（比如包裹图表和文本的<div>）上，除了加page-break-inside: avoid，再添加一个自定义属性，然后通过TagWorker把它转为iText的keepTogether布局属性：

<!-- 你的防跨页元素 -->
<div style="page-break-inside: avoid;" data-keep-together="true">
  <img src="chart.png" alt="图表">
  <p>图表配套文本...</p>
</div>

然后注册自定义TagWorker处理器：

ConverterProperties props = new ConverterProperties();
props.setTagWorkerFactory(new DefaultTagWorkerFactory() {
    @Override
    public ITagWorker getCustomTagWorker(IElementNode tag, ProcessorContext context) {
        // 识别自定义属性
        if ("true".equals(tag.getAttribute("data-keep-together"))) {
            return new DivTagWorker(tag, context) {
                @Override
                public void processEnd(IElementNode element, ProcessorContext context) {
                    super.processEnd(element, context);
                    // 强制元素保持在同一页
                    if (getElementResult() instanceof Div) {
                        ((Div) getElementResult()).setKeepTogether(true);
                    }
                }
            };
        }
        return super.getCustomTagWorker(tag, context);
    }
});

keepTogether=true会让iText严格计算页面可用空间（包含你设置的边距），尽量把整个元素放在同一页。

方式2：先初始化带边距的Document再传给pdfhtml #

不要让pdfhtml自动创建Document，而是手动创建带边距的Document，再通过ConverterProperties传入，确保布局计算基于正确的页面尺寸：

// 初始化带边距的PDF文档
PdfDocument pdfDoc = new PdfDocument(new PdfWriter("output.pdf"));
// 设置上下左右边距为36pt（约0.5英寸）
Document layoutDoc = new Document(pdfDoc, PageSize.A4, 36, 36, 36, 36);

ConverterProperties props = new ConverterProperties();
props.setDocument(layoutDoc); // 把自定义边距的Document传给pdfhtml

// 执行转换
HtmlConverter.convertToPdf(new FileInputStream("input.html"), pdfDoc, props);
layoutDoc.close();

这种方式从根源上统一了布局上下文，page-break-inside: avoid会基于正确的可用页面空间生效。

二、修复page-break-before/after: always失效问题 #

旧版iTextSharp的分页样式在pdfhtml中对元素类型和样式优先级有要求，确保你把样式用在块级元素（如<div>、<p>）上。如果还是失效，直接通过TagWorker强制添加分页：

// 在之前的TagWorkerFactory中添加这段逻辑
if ("always".equals(tag.getStyles().get("page-break-before"))) {
    return new DivTagWorker(tag, context) {
        @Override
        public void processEnd(IElementNode element, ProcessorContext context) {
            super.processEnd(element, context);
            if (getElementResult() instanceof Div) {
                // 强制在元素前添加分页
                ((Div) getElementResult()).setProperty(Property.BEFORE, new AreaBreak(AreaBreakType.NEXT_PAGE));
            }
        }
    };
}

// page-break-after: always的处理逻辑
if ("always".equals(tag.getStyles().get("page-break-after"))) {
    return new DivTagWorker(tag, context) {
        @Override
        public void processEnd(IElementNode element, ProcessorContext context) {
            super.processEnd(element, context);
            if (getElementResult() instanceof Div) {
                ((Div) getElementResult()).setProperty(Property.AFTER, new AreaBreak(AreaBreakType.NEXT_PAGE));
            }
        }
    };
}

用iText原生的AreaBreak来触发分页，比依赖CSS样式更可靠。

三、自定义<pageBreak/>标签的正确实现 #

你之前直接调用AddNewPage()失败，是因为跳过了pdfhtml的布局上下文，导致后续内容错位。正确的做法是让TagWorker返回一个AreaBreak元素，交给布局引擎处理：

props.setTagWorkerFactory(new DefaultTagWorkerFactory() {
    @Override
    public ITagWorker getCustomTagWorker(IElementNode tag, ProcessorContext context) {
        if ("pageBreak".equals(tag.name())) {
            return new ITagWorker() {
                @Override
                public void processEnd(IElementNode element, ProcessorContext context) {}

                @Override
                public boolean processContent(String content, ProcessorContext context) { return false; }

                @Override
                public boolean processTagChild(ITagWorker childTagWorker, ProcessorContext context) { return false; }

                @Override
                public IPropertyContainer getElementResult() {
                    // 返回AreaBreak实现分页
                    return new AreaBreak(AreaBreakType.NEXT_PAGE);
                }
            };
        }
        return super.getCustomTagWorker(tag, context);
    }
});

这样<pageBreak/>会被正确解析为分页指令，和你设置的边距完全兼容。

最后几个注意事项 #

• 确保防跨页元素是块级元素，不要嵌套在行内元素或浮动元素中，否则布局规则会失效。
• 如果图表特别大，提前计算页面可用高度（页面高度 - 上下边距），给图表容器设置max-height，避免即使keepTogether=true也无法放下的情况。
• 测试时先简化HTML结构，排除其他样式（如绝对定位、负边距）对分页的干扰。

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