Java Word 创建页脚页码时如何设置起始页码？

Question

在使用 Java 操作 Word 文档（如 Apache POI 或 docx4j）创建页脚并添加页码时，一个常见问题是：**如何设置起始页码？** 默认情况下，Word 文档的页码从第一页开始编号，但在实际应用中，比如报告或论文排版，往往需要跳过封面或目录，从第二页或其它指定页面开始计数。此问题的核心在于如何通过 Java 代码控制 Word 的“起始页码”属性。由于不同库对 OOXML 的封装程度不同，实现方式存在差异，尤其在分节符（Section）处理和页脚链接方面容易遇到问题，例如页码不生效、起始页码未生效或跨节页码继承错误等。解决该问题通常需要深入理解文档结构及页脚与节的关系。

Answer 1

一、问题背景与理解

在使用 Java 操作 Word 文档时，尤其是在生成报告或论文等正式文档的场景下，往往需要对页脚中的页码进行精确控制。默认情况下，Apache POI 或 docx4j 生成的 .docx 文件会从第一页开始编号，但实际需求常常是跳过封面或目录，从第二页甚至其它指定页开始计数。

该问题的核心在于：如何通过代码设置“起始页码”，并正确处理节（Section）之间的关系。Word 中的分节符决定了页面布局和页眉页脚的独立性，若未正确断开前一节的页脚链接，则新节的页码设置将被忽略。

二、技术原理概述

Word 文档中页码的控制依赖于以下两个核心结构：

• 分节符（Section）：每个节可以拥有独立的页眉页脚配置。
• 页脚链接（Footer Reference）：定义当前节是否继承上一节的页脚内容。

要实现从某一页开始自定义页码，通常需要执行如下步骤：

1. 插入一个分节符以创建新节。
2. 断开新节与前一节的页脚链接。
3. 在新节中创建页脚并添加页码。
4. 设置该节的起始页码值。

三、Apache POI 实现方案详解

Apache POI 是目前 Java 社区中最流行的 Word 操作库之一。其底层基于 OOXML schema 实现，提供了对文档结构的精细控制。

以下是 Apache POI 设置起始页码的关键步骤及示例代码：

XWPFDocument document = new XWPFDocument();
// 添加一个段落作为正文
document.createParagraph().createRun().setText("This is the first page (cover).");

// 插入分节符，创建新节
CTP p = CTP.Factory.newInstance();
CTRPr rpr = p.addNewR();
rpr.addNewBdr();
p.addNewR().addNewBr().setType(STBrType.PAGE);
document.getDocument().getBody().add(p);

// 获取所有节信息
List policies = new ArrayList<>();
for (int i = 0; i < document.getDocument().getBody().getSectPrList().size(); i++) {
    CTBody body = document.getDocument().getBody();
    CTSectPr sectPr = body.getSectPrArray(i);
    XWPFHeaderFooterPolicy policy = new XWPFHeaderFooterPolicy(document, sectPr);
    policies.add(policy);
}

// 设置第二节的页脚，并断开链接
XWPFHeaderFooterPolicy secondPolicy = policies.get(1);
secondPolicy.createFooter(STHdrFtr.DEFAULT);
secondPolicy.getFooter().createParagraph().createRun().addText("Page ");
secondPolicy.getFooter().getParagraphArray(0).getRuns().get(0).addField("PAGE");
secondPolicy.getFooter().getParagraphArray(0).getRuns().get(0).addText(" of ");
secondPolicy.getFooter().getParagraphArray(0).getRuns().get(0).addField("NUMPAGES");

// 设置起始页码为 1（即从第二页开始计数）
CTSectPr sectPr = document.getDocument().getBody().getSectPrList().get(1);
if (sectPr.isSetPgNumType()) {
    sectPr.unsetPgNumType();
}
CTPageNumber pgNum = sectPr.addNewPgNumType();
pgNum.setStart(BigInteger.ONE); // 起始页码为 1
    

四、docx4j 实现方案对比分析

docx4j 提供了更接近 XML 结构的操作方式，适合需要高度定制化文档结构的场景。相比 Apache POI，它对 OOXML 的封装更为原始，但也因此具备更高的灵活性。

使用 docx4j 设置起始页码的流程如下：

步骤	操作说明
1	创建主文档并添加第一节内容
2	插入分节符（Section Break）
3	创建新节的页脚对象
4	断开页脚与前节的链接
5	设置页码字段并定义起始值

由于篇幅限制，此处不展示完整代码，但其关键点在于操作 w:sectPr 元素下的 w:pgNumType 和 w:start 字段。

五、常见问题与调试技巧

在使用 Java 操作 Word 设置起始页码时，常见的问题包括：

• 页码字段未正确解析，导致显示为 “PAGE” 文本而非数字。
• 新节未断开页脚链接，导致页码继承前节设置。
• OOXML 格式错误，导致 Word 打开文档时报错。

建议的调试方法：

• 使用 docx4j Debug 工具查看文档内部结构。
• 手动在 Word 中设置页码后保存为 docx，解压文件观察 XML 内容。
• 使用 Apache POI 的 document.write() 方法输出临时文件验证结果。

六、流程图辅助理解

以下是一个设置起始页码的逻辑流程图：

```mermaid
graph TD
    A[创建 Word 文档] --> B[添加封面内容]
    B --> C[插入分节符]
    C --> D[创建新节]
    D --> E{是否断开页脚链接?}
    E -- 否 --> F[继续使用上一节页脚]
    E -- 是 --> G[新建独立页脚]
    G --> H[添加页码字段]
    H --> I[设置起始页码值]
    I --> J[完成文档构建]
```