iText生成PDF时分页的核心是调用document.newPage()方法，但实际开发中常遇到表格跨页、页码位置等问题，需要结合事件监听和页面设置灵活处理。
iText PDF分页设置：从基础到实战
document.newPage()的正确用法
在iText 5中，分页通常通过Document.newPage()实现，手动触发换页，iText 7改用PdfDocument和Document模型，Document.add()超出当前页面时会自动分页，但手动分页仍需调用newPage()，官方文档建议，在添加块级内容前调用newPage()，避免在表格或列表中间断页，多数情况下，自动分页已足够，但若需控制章节起始位置,手动分页更可靠。
设置页面大小和边距
分页效果受页面尺寸影响，初始化PdfDocument时指定PageSize，如new PageSize(595, 842)（A4），边距通过Document.setMargins()调整，至少保留上下左右各20单位，否则分页时内容可能贴边，业内专家指出，边距设置不当是分页错位的常见原因,建议在模板中统一管理。
表格跨页：keepTogether与splitLate
表格分页是高频需求，iText的PdfPTable提供setKeepTogether(boolean)，设置为true时，表格会尽量保持在同一页，但若空间不足，整表会移到下一页，造成前一页空白，更推荐使用setSplitLate(false)，允许表格跨页，但行内容可能被截断，行高较大时，结合setRowRenderers自定义分页行为,避免行内截断。
iText分页不移除底部内容的技巧
通过事件监听保留页脚或版权信息
默认分页会清空内容区域，但页脚、页码需要每页保留，使用PdfPageEventHelper（iText 5）或IEventHandler（iText 7），在onEndPage事件中重新绘制页脚，通过PdfWriter.getPageNumber()获取当前页码，确保每页底部内容一致，注意，onStartPage事件也可用于绘制页眉,但需防止重复绘制。
自定义分页符避免内容重叠
当页面底部有固定内容时，手动分页可能导致正文与页脚重叠，解决方案是在PdfDocument中添加PdfPageEvent，在onEndPage中预留底部区域，例如调用PdfCanvas绘制矩形遮罩，或调整Document的边距，iText 7中，使用PageCountHelper和PdfDocument.addNewPage()时，通过PdfCanvas.getPdfDocument()获取当前页,手动控制内容偏移。
iText表格分页处理：解决方案与对比
| 方法 | 适用场景 | 注意点 |
|---|---|---|
setKeepTogether(true) |
较小表格，不希望跨页 | 可能导致前一页留白 |
setSplitLate(false) |
大表格，允许跨页但行内截断 | 需配合行高限制 |
自定义PdfPageEventHelper |
需要每页重复表头或页脚 | 代码量较大，但灵活 |
表格自动分页时表头重复
iText 5的
PdfPTable默认不重复表头，需设置setHeaderRows(1)，iText 7中，Table类通过setCaption或addHeaderCell实现，若表头在第一页后消失，检查是否在onEndPage中重新添加了表头，建议在onEndPage事件中调用PdfPTable.writeSelectedRows(),将表头写入每页的固定位置。
大型表格分页性能优化
当表格行数超过千行，逐页渲染可能变慢，使用PdfWriter.setFullCompression()减少文件大小，并分批次添加行，避免一次性加载所有数据，对于动态数据，可考虑使用PdfDocument的flushCopyObjects方法,及时释放内存。
iText 7分页事件：添加页码和动态控制
PdfDocument与Document的事件模型
iText 7不再使用PdfPageEventHelper，改用IEventHandler接口，通过PdfDocument.addEventHandler(PdfDocumentEvent.END_PAGE, handler)注册事件，在handleEvent方法中，通过PdfDocumentEvent.getDocument()获取当前文档，使用PdfCanvas绘制页码，示例：PdfCanvas canvas = new PdfCanvas(page); canvas.beginText().setFontAndSize(...).showText("第 " + pageNum + " 页").endText();
的分页：根据内容长度自动分页
对于生成报告或合同，内容长度不定，利用Document的自动分页能力，结合Paragraph的setKeepTogether属性，可让段落整体跨页，若需强制分页，在模板中插入new AreaBreak()（iText 7）或Chunk.NEXTPAGE（iText 5），注意，
AreaBreak会创建新页面，但不会清空事件,页脚仍会保留。
iText PDF分页Q&A
iText PDF分页时内容被截断怎么办？
检查边距是否过小，尤其是底部边距，若页脚占用空间，需在onEndPage中预留区域，对于表格，避免使用固定行高，改用PdfPTable.setWidthPercentage(100)自适应，若内容仍被截断，尝试手动计算页面剩余空间，使用PdfWriter.getVerticalPosition(true)获取当前Y坐标,判断是否需换页。
如何实现iText分页不移除底部版权信息？
在PdfPageEventHelper.onEndPage中，直接调用PdfWriter.getDirectContent()绘制底部文本，注意，onEndPage在页面完成前触发，此时绘制的内容不会被后续内容覆盖，iText 7中，在END_PAGE事件中使用PdfCanvas，确保绘制操作在flush之前完成。
iText表格分页后表头丢失如何解决？
iText 5需设置setHeaderRows(1)，并在PdfPTable构造时指定表头行数，iText 7中，使用Table.addHeaderCell()添加表头，若仍丢失，检查是否在onEndPage事件中重置了表格布局，推荐在onStartPage事件中重新添加表头，确保每页都包含，对于复杂表格，可将表头作为独立PdfPTable,在每页手动写入。
iText PDF分页的核心在于理解自动分页与事件控制的配合，通过合理设置边距、表格属性和页面事件，可以实现稳定、美观的分页效果。
首发原创文章，作者：王坚，如若转载，请注明出处：https://test.idctop.com/article/565086.html
