以下是针对 XWPFDocument 的详细解析，涵盖其核心功能、常见用法及实际开发中的关键点：

---

1. XWPFDocument 简介

XWPFDocument 是 Apache POI 库中用于操作 .docx 格式 Word 文档的核心类。它提供对文档内容（段落、表格、图片、样式等）的动态生成和修改能力，适用于需要自动化生成复杂 Word 文档的场景。

在pom.xml中添加Apache POI依赖：

<dependency><groupId>org.apache.poi</groupId><artifactId>poi-ooxml</artifactId><version>5.2.2</version>
</dependency>

---

2. 核心结构与类

类/接口	功能说明
XWPFDocument	文档对象，代表整个 .docx 文件，管理所有内容元素。
XWPFParagraph	段落对象，控制文本块（如标题、正文、列表）。
XWPFRun	段落内的文本片段，可单独设置样式（字体、颜色、加粗等）。
XWPFTable	表格对象，支持动态创建表格、合并单元格、设置边框等。
XWPFPicture	图片对象，用于插入本地或网络图片。
XWPFHeader/XWPFFooter	页眉和页脚，支持全局或分节设置。

---

3. 核心操作详解

3.1 段落与文本

// 1. 加载模板(文件要在src/main/resources目录下)ClassPathResource resource = new ClassPathResource("template/report_template.docx");XWPFDocument document = new XWPFDocument(resource.getInputStream());// 创建段落
XWPFParagraph para = document.createParagraph();
para.setAlignment(ParagraphAlignment.CENTER);  // 对齐方式（居中）
para.setIndentationFirstLine(600);             // 首行缩进（单位：TWIP）// 添加文本片段
XWPFRun run = para.createRun();
run.setText("Hello World!");
run.setBold(true);                            // 加粗
run.setFontSize(14);                          // 字号
run.setFontFamily("宋体");                     // 解决中文乱码的关键
run.setColor("FF0000");                       // 字体颜色（RGB 十六进制）
run.addBreak();                               // 换行（类似 <br>）

3.2 表格操作

// 创建表格（3行3列）
XWPFTable table = document.createTable(3, 3);// 设置列宽（单位：TWIP）
CTTblGrid grid = table.getCTTbl().addNewTblGrid();
grid.addNewGridCol().setW(3000);
grid.addNewGridCol().setW(3000);
grid.addNewGridCol().setW(3000);// 填充表头
XWPFTableRow headerRow = table.getRow(0);
headerRow.getCell(0).setText("姓名");
headerRow.getCell(1).setText("年龄");
headerRow.getCell(2).setText("部门");// 合并单元格（横向）
mergeCellsHorizontal(table, 1, 0, 1);
table.getRow(1).getCell(0).setText("合并示例");// 设置表格边框
CTBorder border = CTBorder.Factory.newInstance();
border.setVal(STBorder.SINGLE);
border.setSz(BigInteger.valueOf(4));  // 边框粗细
table.setTopBorder(border);           // 上边框
table.setBottomBorder(border);        // 下边框

3.3 列表与编号

// 创建编号列表
XWPFParagraph listPara = document.createParagraph();
listPara.setNumID(/* 编号ID，需通过样式定义 */);
XWPFRun listRun = listPara.createRun();
listRun.setText("列表项1");// 多级列表
CTAbstractNum abstractNum = CTAbstractNum.Factory.newInstance();
// ... 定义多级编号规则（需操作 XML 底层结构）

3.4 图片插入

// 从本地文件读取图片
byte[] imageBytes = Files.readAllBytes(Paths.get("path/to/image.png"));
XWPFParagraph imagePara = document.createParagraph();
XWPFRun imageRun = imagePara.createRun();
imageRun.addPicture(new ByteArrayInputStream(imageBytes),Document.PICTURE_TYPE_PNG,"image.png",Units.toEMU(200),   // 宽度（200像素）Units.toEMU(150)    // 高度（150像素）
);

---

4. 高级功能

4.1 页眉与页脚

// 创建页眉
XWPFHeader header = document.createHeader(HeaderFooterType.DEFAULT);
XWPFParagraph headerPara = header.createParagraph();
headerPara.createRun().setText("公司机密 - 第1页");// 创建页脚（带页码）
XWPFFooter footer = document.createFooter(HeaderFooterType.DEFAULT);
XWPFParagraph footerPara = footer.createParagraph();
footerPara.setAlignment(ParagraphAlignment.CENTER);
footerPara.createRun().setText("页码：");
footerPara.getCTP().addNewFldSimple().setInstr("PAGE \\* MERGEFORMAT");

4.2 超链接

// 插入超链接
CTHyperlink cthyperlink = paragraph.getCTP().addNewHyperlink();
cthyperlink.setId(document.getPackagePart().addExternalRelationship("https://example.com", XWPFRelation.HYPERLINK.getRelation()
).getId());
XWPFRun linkRun = paragraph.createRun();
linkRun.setText("访问示例网站");
linkRun.setUnderline(UnderlinePatterns.SINGLE);
linkRun.setColor("0000FF");

4.3 分页符

// 强制分页
XWPFParagraph pageBreakPara = document.createParagraph();
pageBreakPara.createRun().addBreak(BreakType.PAGE);

---

5. 样式与模板

5.1 使用预定义样式

// 设置段落样式（需提前定义或使用内置样式）
para.setStyle("Heading1");

5.2 自定义样式

// 创建字符样式
CTSectPr sectPr = document.getDocument().getBody().addNewSectPr();
CTDocDefaults docDefaults = sectPr.addNewDocDefaults();
CTRPrDefault rPrDefault = docDefaults.addNewRPrDefault();
CTRPr rpr = rPrDefault.addNewRPr();
rpr.addNewB().setVal(STOnOff.TRUE);  // 默认加粗

---

6. 最佳实践与注意事项

1. 中文乱码问题

   • 必须显式设置中文字体（如 run.setFontFamily("宋体")）。
   • 确保系统或服务器环境支持中文字体。

2. 性能优化

   • 生成大文档时，使用 SXSSFWorkbook 类似的流式处理（但 POI 对 Word 的支持有限）。
   • 及时关闭资源：生成后调用 document.close() 释放内存。

3. 版本兼容性

   • Apache POI 5.x+ 支持 Office 2019+ 格式，旧版本需降级至 POI 3.x。

4. 错误处理

   • 捕获 IOException 和 InvalidFormatException。
   • 使用 try-with-resources 确保流关闭：

     try (XWPFDocument doc = new XWPFDocument();FileOutputStream out = new FileOutputStream("output.docx")) {// 操作文档
     }
     

5. 模板引擎整合

   • 复杂文档建议结合 Freemarker 或 Velocity 模板引擎，避免硬编码样式。

---

7. 常见问题解决

• 表格边框不显示
  需显式设置表格边框属性（POI 默认不显示边框）。

• 生成的文档损坏
  确保正确关闭 XWPFDocument 和输出流。

• 样式不生效
  检查样式名称是否正确，或直接通过 XWPFRun 设置样式覆盖。

---

通过掌握 XWPFDocument 的核心 API 和上述技巧，可以高效生成复杂的 Word 文档，满足企业级应用需求。