Apache POI XWPFDocument添加分节符后页眉仅在最后一页显示问题

问题背景 #

使用Apache POI创建带图片的Word文档时，需实现以下需求：

• 放置图片的页面设置为横向，其余页面保持纵向
• 全文档所有页面统一配置页眉（页脚实现逻辑与页眉完全一致）

问题复现代码 #

val document = XWPFDocument()

// 预期全文档生效的页眉
document.createHeader(HeaderFooterType.DEFAULT).createParagraph().createRun().setText("Header")

// 图片前的正文内容
var par = document.createParagraph()
var run = par.createRun()
run.setText("I am text")

// 插入图片并设置当前页为横向
par = document.createParagraph()
// 直接在段落属性新建分节属性实现页面方向切换
val pageSize = par.ctp.addNewPPr().addNewSectPr().addNewPgSz()
pageSize.orient = STPageOrientation.LANDSCAPE
pageSize.h = BigInteger.valueOf(595 * 20) // 单位为TWIPS，即1/20印刷磅
pageSize.w = BigInteger.valueOf(842 * 20)
run = par.createRun()
val decodedByteArray = Base64.getDecoder().decode(PLACEHOLDER_IMAGE.substringAfter(','))
run.addPicture(
    ByteArrayInputStream(decodedByteArray),
    XWPFDocument.PICTURE_TYPE_PNG,
    "",
    pixelToEMU(400),
    pixelToEMU(150)
)

// 图片后的正文内容
par = document.createParagraph()
run = par.createRun()
run.setText("Me too")
val out = FileOutputStream("Output.docx")
document.write(out)
out.close()
document.close()

异常表现 #

运行上述代码生成的文档存在排版问题：

• 页眉仅在最后一个分节符之后的页面显示，异常效果参考：
• Word原生规则中每个独立节可单独配置页眉/页脚，也支持开启「链接到前一节」复用前序节的页眉配置，但当前代码创建的页眉仅绑定文档最后一节，无法关联前序节供后续节复用，也无法访问前序节的页眉对象，多次调试仅能为最后一节设置页眉内容。

根因分析 #

直接通过段落的ctp.addNewPPr().addNewSectPr()裸创建分节属性时，Apache POI不会自动为中间生成的节配置页眉关系引用，也不会默认开启「链接到前一节」的配置，代码最开始调用document.createHeader()创建的默认页眉，只会自动绑定到文档末尾的最终节，不会自动关联前面通过段落属性创建的中间节。

解决方案 #

方案1：规范分节配置，开启节间页眉链接（推荐，完全满足页面方向需求） #

按照Word的分节规则调整代码逻辑，步骤如下：

1. 先创建文档默认的页眉（即第一节的页眉），保存该页眉对应的关系ID
2. 插入图片前的纵向内容后，不要在图片所在段落直接创建分节，而是在图片内容结束后的第一个段落上创建「下一页」类型的分节符，将分节符之前的页面（即图片所在页）设置为横向
3. 为每个新增的分节配置页眉引用：非第一节的页眉直接引用第一节的页眉关系ID，并设置linkToPrevious=true，复用第一节的页眉内容，无需重复创建页眉
4. 文档末尾的最终节（即文档级的节配置）同样绑定该默认页眉，确保最后一页正常显示

注意：分节符的页面设置作用范围是分节符之前的所有内容，不是分节符所在段落之后的内容，不要放错分节位置，否则会出现页面方向错位。

方案2：无分节符单页横向（不推荐） #

Word原生不支持不分节单独设置某一页方向，网传的无分节符方案本质是通过旋转图片、调整页边距的hack方式模拟横向效果，不同版本Word、WPS打开容易出现排版错位，不建议生产环境使用。

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