XWPFDocument生成word文档介绍（格式 .docx）
以下是针对 XWPFDocument 的详细解析，涵盖其核心功能、常见用法及实际开发中的关键点：
XWPFDocument
1. XWPFDocument 简介2. 核心结构与类3. 核心操作详解**3.1 段落与文本****3.2 表格操作****3.3 列表与编号****3.4 图片插入**
4. 高级功能**4.1 页眉与页脚****4.2 超链接****4.3 分页符**
5. 样式与模板**5.1 使用预定义样式****5.2 自定义样式**
6. 最佳实践与注意事项7. 常见问题解决
1. XWPFDocument 简介
XWPFDocument 是 Apache POI 库中用于操作 .docx 格式 Word 文档的核心类。它提供对文档内容（段落、表格、图片、样式等）的动态生成和修改能力，适用于需要自动化生成复杂 Word 文档的场景。
在pom.xml中添加Apache POI依赖：
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(); // 换行（类似
）
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. 最佳实践与注意事项
中文乱码问题
必须显式设置中文字体（如 run.setFontFamily("宋体")）。确保系统或服务器环境支持中文字体。 性能优化
生成大文档时，使用 SXSSFWorkbook 类似的流式处理（但 POI 对 Word 的支持有限）。及时关闭资源：生成后调用 document.close() 释放内存。 版本兼容性
Apache POI 5.x+ 支持 Office 2019+ 格式，旧版本需降级至 POI 3.x。 错误处理
捕获 IOException 和 InvalidFormatException。使用 try-with-resources 确保流关闭：try (XWPFDocument doc = new XWPFDocument();
FileOutputStream out = new FileOutputStream("output.docx")) {
// 操作文档
}
模板引擎整合
复杂文档建议结合 Freemarker 或 Velocity 模板引擎，避免硬编码样式。
7. 常见问题解决
表格边框不显示 需显式设置表格边框属性（POI 默认不显示边框）。
生成的文档损坏 确保正确关闭 XWPFDocument 和输出流。
样式不生效 检查样式名称是否正确，或直接通过 XWPFRun 设置样式覆盖。
通过掌握 XWPFDocument 的核心 API 和上述技巧，可以高效生成复杂的 Word 文档，满足企业级应用需求。