如何使用Apache POI为.docx文档添加可自动更新的目录（TOC）

我明白你在用Apache POI 5.2.3给docx文件加自动更新目录时遇到的糟心问题——不管是提前插TOC还是事后补，要么出空行要么报“引用源未找到”，加上你用的是Linux下的LibreOffice Writer，还要考虑和Word的兼容差异。别着急，咱们一步步来解决：

首先，确保标题样式配置正确 #

TOC的核心依赖文档里的标题样式（Heading 1/2/3），所以第一步要保证自定义的标题样式能被POI和办公软件正确识别。先检查你的addCustomHeadingStyle方法，下面是一个标准的实现，能确保样式级别和内置标题对应：

private static void addCustomHeadingStyle(XWPFDocument doc, String styleName, int headingLevel) {
    XWPFStyle style = doc.createStyle();
    style.setStyleId(styleName);
    CTString styleNameCT = CTString.Factory.newInstance();
    styleNameCT.setVal(styleName);
    style.getCTStyle().setName(styleNameCT);
    
    // 设置样式类型为段落样式
    CTDecimalNumber indentNumber = CTDecimalNumber.Factory.newInstance();
    indentNumber.setVal(BigInteger.valueOf(headingLevel));
    style.getCTStyle().setUiPriority(indentNumber);
    
    CTOnOff onoffnull = CTOnOff.Factory.newInstance();
    style.getCTStyle().setUnhideWhenUsed(onoffnull);
    
    // 关联到内置标题体系，让办公软件能识别
    style.getCTStyle().setBasedOn("Heading");
    style.getCTStyle().setNext("Heading");
    style.getCTStyle().setLink(styleName);
    
    CTPPr ppr = CTPPr.Factory.newInstance();
    CTDecimalNumber outlineLvl = CTDecimalNumber.Factory.newInstance();
    outlineLvl.setVal(BigInteger.valueOf(headingLevel-1)); // 注意：办公软件用0-based级别
    ppr.setOutlineLvl(outlineLvl);
    style.getCTStyle().setPPr(ppr);
    
    doc.getStyles().addStyle(style);
}

然后，调整操作顺序：先写内容，再插TOC #

你之前的问题很大一部分是顺序搞反了——先插TOC再写标题内容，POI没法提前识别还没创建的标题。正确流程是：

1. 先创建所有带标题样式的段落
2. 再在目标位置插入TOC字段

完整可运行代码示例 #

下面是调整后的完整代码，能生成可自动更新的TOC：

import org.apache.poi.xwpf.usermodel.*;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;
import java.math.BigInteger;
import java.io.FileOutputStream;
import java.io.IOException;

public class TOCGenerator {
    public static void main(String[] args) throws IOException {
        try (XWPFDocument doc = new XWPFDocument()) {
            // 1. 配置标题样式
            addCustomHeadingStyle(doc, "Heading 1", 1);
            addCustomHeadingStyle(doc, "Heading 2", 2);
            addCustomHeadingStyle(doc, "Heading 3", 3);

            // 2. 先创建所有内容段落
            // 正文说明
            XWPFParagraph bodyPara = doc.createParagraph();
            XWPFRun bodyRun = bodyPara.createRun();
            bodyRun.setText("文档正文开始：");

            // 一级标题
            XWPFParagraph heading1 = doc.createParagraph();
            heading1.setStyle("Heading 1");
            XWPFRun run1 = heading1.createRun();
            run1.setText("一级标题示例");

            // 一级标题下的内容
            XWPFParagraph content1 = doc.createParagraph();
            XWPFRun contentRun1 = content1.createRun();
            contentRun1.setText("这是一级标题下的内容");

            // 二级标题
            XWPFParagraph heading2 = doc.createParagraph();
            heading2.setStyle("Heading 2");
            XWPFRun run2 = heading2.createRun();
            run2.setText("二级标题示例");

            // 三级标题
            XWPFParagraph heading3 = doc.createParagraph();
            heading3.setStyle("Heading 3");
            XWPFRun run3 = heading3.createRun();
            run3.setText("三级标题示例");

            // 3. 在文档开头插入TOC（可调整位置，比如正文前）
            doc.insertParagraph(0);
            XWPFParagraph tocPara = doc.getParagraphs().get(0);
            CTP ctP = tocPara.getCTP();

            // 创建TOC字段
            CTSimpleField tocField = ctP.addNewFldSimple();
            // TOC指令：包含1-3级标题、显示页码、带超链接、更新保留格式
            tocField.setInstr("TOC \\o \"1-3\" \\h \\z \\u");
            tocField.setDirty(true); // 设置为脏状态，打开文档时会提示更新

            // TOC后加分页符
            XWPFRun tocRun = tocPara.createRun();
            tocRun.addBreak(BreakType.PAGE);

            // 保存文档
            try (FileOutputStream out = new FileOutputStream("带目录的文档.docx")) {
                doc.write(out);
            }
        }
    }

    private static void addCustomHeadingStyle(XWPFDocument doc, String styleName, int headingLevel) {
        XWPFStyle style = doc.createStyle();
        style.setStyleId(styleName);
        CTString styleNameCT = CTString.Factory.newInstance();
        styleNameCT.setVal(styleName);
        style.getCTStyle().setName(styleNameCT);

        CTDecimalNumber indentNumber = CTDecimalNumber.Factory.newInstance();
        indentNumber.setVal(BigInteger.valueOf(headingLevel));
        style.getCTStyle().setUiPriority(indentNumber);

        CTOnOff onoffnull = CTOnOff.Factory.newInstance();
        style.getCTStyle().setUnhideWhenUsed(onoffnull);

        style.getCTStyle().setBasedOn("Heading");
        style.getCTStyle().setNext("Heading");
        style.getCTStyle().setLink(styleName);

        CTPPr ppr = CTPPr.Factory.newInstance();
        CTDecimalNumber outlineLvl = CTDecimalNumber.Factory.newInstance();
        outlineLvl.setVal(BigInteger.valueOf(headingLevel - 1));
        ppr.setOutlineLvl(outlineLvl);
        style.getCTStyle().setPPr(ppr);

        doc.getStyles().addStyle(style);
    }
}

关键注意事项 #

1. 大纲级别设置：一定要把outlineLvl设为headingLevel-1，因为Office和LibreOffice的大纲级别是从0开始计数的，这是很多人踩坑的点。
2. TOC字段指令："TOC \\o \"1-3\" \\h \\z \\u"的含义：
   • \\o \"1-3\"：包含1到3级标题
   • \\h：添加超链接（点击标题跳转至对应位置）
   • \\z：隐藏页码前的制表符
   • \\u：更新目录时保留原格式
3. 自动更新实现：设置tocField.setDirty(true)后，打开文档时（Word或LibreOffice）会提示更新目录；如果没提示，右键点击目录选择“更新目录”即可。
4. 不要手动构建TOC行：你之前遍历段落手动添加行的方法是错误的，生成的是静态文本，无法自动更新。正确做法是用CTSimpleField创建TOC字段，让办公软件自动识别标题生成目录。

LibreOffice Writer里的更新操作 #

打开生成的docx后，右键点击目录区域，选择更新目录，在弹出窗口中选择“更新整个目录”，就能同步所有新增的标题。

备注：内容来源于stack exchange，提问作者hido