如何用Java及Apache POI更新Word文档TOC页码或创建带页码TOC

方案一：手动构建自定义类TOC结构 #

因为enforceUpdateFields()会触发弹窗，且POI无法直接静默更新Word原生TOC，最可靠的方式是手动生成类TOC结构，完全控制内容和页码。

实现步骤 #

• 遍历文档中所有标题段落（通过样式判断，比如Heading 1、Heading 2等）
• 计算每个标题所在的页码（POI v4.1.2可结合段落分节信息、内容长度估算，或借助布局相关API）
• 在文档指定位置插入段落/表格，构建包含标题层级、文本和对应页码的自定义TOC

代码片段 #

import org.apache.poi.xwpf.usermodel.*;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTSectPr;

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.util.ArrayList;
import java.util.List;

public class CustomTocGenerator {
    public static void main(String[] args) throws Exception {
        try (XWPFDocument doc = new XWPFDocument(new FileInputStream("modified_template.docx"))) {
            // 收集所有标题及对应页码
            List<TocEntry> tocEntries = collectTocEntries(doc);
            // 在文档开头插入自定义TOC
            insertCustomToc(doc, tocEntries);
            // 保存最终文档
            try (FileOutputStream out = new FileOutputStream("final_document.docx")) {
                doc.write(out);
            }
        }
    }

    private static List<TocEntry> collectTocEntries(XWPFDocument doc) {
        List<TocEntry> entries = new ArrayList<>();
        int currentPage = 1;
        boolean newSection = false;

        for (XWPFParagraph para : doc.getParagraphs()) {
            CTP ctp = para.getCTP();
            CTSectPr sectPr = ctp.getSectPr();
            
            // 处理分节符，重置起始页码
            if (sectPr != null && sectPr.getPgNumType() != null) {
                if (sectPr.getPgNumType().getStart() != null) {
                    currentPage = sectPr.getPgNumType().getStart().intValue();
                }
                newSection = true;
            }

            // 判断是否为标题样式
            String styleId = para.getStyleID();
            if (styleId != null) {
                XWPFStyle style = doc.getStyle(styleId);
                if (style != null && style.getName().startsWith("Heading ")) {
                    int level = Integer.parseInt(style.getName().split(" ")[1]);
                    // 此处为简化页码计算，复杂场景需结合段落实际排版高度调整
                    entries.add(new TocEntry(level, para.getText(), currentPage));
                }
            }

            // 根据段落内容量估算页码变化
            if (!newSection && !para.getText().isEmpty()) {
                if (para.getRuns().size() > 6 || para.getText().length() > 200) {
                    currentPage++;
                }
            }
            newSection = false;
        }
        return entries;
    }

    private static void insertCustomToc(XWPFDocument doc, List<TocEntry> tocEntries) {
        // 插入TOC标题
        XWPFParagraph tocTitle = doc.createParagraph();
        XWPFRun titleRun = tocTitle.createRun();
        titleRun.setText("目录");
        titleRun.setBold(true);
        titleRun.setFontSize(16);
        tocTitle.setSpacingAfter(200);

        // 插入每个TOC条目
        for (TocEntry entry : tocEntries) {
            XWPFParagraph para = doc.createParagraph();
            // 根据标题层级设置缩进（720 twips = 0.5英寸）
            para.setIndentationLeft(entry.getLevel() * 720);
            XWPFRun run = para.createRun();
            run.setText(entry.getTitle());
            // 添加制表位和点线页码
            run.addTab();
            run.setText("... " + entry.getPageNumber());
            run.setFontSize(12);
        }

        // TOC后插入分页符
        XWPFParagraph pageBreak = doc.createParagraph();
        pageBreak.setPageBreak(true);
    }

    // 自定义TOC条目实体类
    static class TocEntry {
        private int level;
        private String title;
        private int pageNumber;

        public TocEntry(int level, String title, int pageNumber) {
            this.level = level;
            this.title = title;
            this.pageNumber = pageNumber;
        }

        public int getLevel() { return level; }
        public String getTitle() { return title; }
        public int getPageNumber() { return pageNumber; }
    }
}

注意事项 #

• 页码计算逻辑需根据文档实际排版调整，复杂场景（如跨页表格、大图片）可结合POI的布局API细化计算
• 自定义TOC的样式可通过设置段落缩进、字体、制表位完全模拟原生TOC外观

方案二：绕过原生TOC弹窗的折中方案 #

如果必须保留原生TOC，可通过修改文档XML结构标记TOC为已更新，阻止弹窗，但页码不会实际同步，仅适合简单场景：

代码片段 #

import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTFldSimple;

import java.io.FileInputStream;
import java.io.FileOutputStream;

public class TocPopupFix {
    public static void main(String[] args) throws Exception {
        try (XWPFDocument doc = new XWPFDocument(new FileInputStream("modified_template.docx"))) {
            // 遍历所有域，找到TOC并添加锁定更新标记
            for (XWPFParagraph para : doc.getParagraphs()) {
                for (CTFldSimple fldSimple : para.getCTP().getFldSimpleList()) {
                    if ("TOC".equals(fldSimple.getInstr().trim())) {
                        fldSimple.addNewFldData().setStringValue("\\LOCKED \\UPDATED");
                    }
                }
            }

            try (FileOutputStream out = new FileOutputStream("no_popup_document.docx")) {
                doc.write(out);
            }
        }
    }
}

局限性 #

• 仅能阻止弹窗，页码不会实际更新，不适合对页码准确性要求高的场景
• 部分Word版本可能不识别该标记，仍会弹出更新提示

关键建议 #

• 优先选择自定义TOC方案，完全可控且无弹窗问题，适合生产环境
• 删除章节后务必重新遍历所有标题，确保页码计算无断层
• 若需精确页码，可参考POI官方文档中页面布局相关API，细化计算逻辑

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