Word文档自动化——Apache POI实战指南
1. Apache POI入门：Word自动化处理基础
如果你是一名Java开发者，经常需要处理Word文档的生成或修改，那么Apache POI绝对是你的得力助手。这个强大的Java库让我们能够轻松操作Microsoft Word文件，无论是创建全新的文档、修改现有文件，还是从文档中提取内容，都能得心应手。
Apache POI主要支持两种Word格式：传统的.doc文件（使用HWPF模块）和现代的.docx文件（使用XWPF模块）。在实际开发中，我们更推荐使用XWPF来处理.docx格式，因为这是目前主流的Word文件格式，而且功能更加强大和稳定。
要开始使用Apache POI，首先需要在项目中添加依赖。如果你使用Maven，只需在pom.xml中加入以下依赖：
<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency>创建第一个Word文档非常简单，只需要几行代码：
import org.apache.poi.xwpf.usermodel.XWPFDocument; import java.io.FileOutputStream; public class FirstWordDoc { public static void main(String[] args) throws Exception { // 创建一个空白文档 XWPFDocument document = new XWPFDocument(); // 将文档写入文件系统 try (FileOutputStream out = new FileOutputStream("first_document.docx")) { document.write(out); System.out.println("文档创建成功！"); } } }这段代码会生成一个完全空白的Word文档。虽然看起来简单，但这已经包含了Apache POI操作Word文档的核心流程：创建文档对象、进行各种操作、最后保存到文件系统。
在实际项目中，我们通常需要处理更复杂的场景。比如，你可能需要：
- 自动生成包含动态内容的报告
- 批量处理大量Word模板文件
- 从数据库中提取数据填充到Word文档
- 合并多个Word文档的内容
Apache POI提供了丰富的API来满足这些需求。接下来，我们将深入探讨如何操作文档中的各种元素，包括段落、表格、样式等，让你的Word自动化处理能力更上一层楼。
2. 文档内容操作：段落与文本样式
掌握了基础文档创建后，让我们深入探讨如何在Word文档中添加和格式化内容。在Apache POI中，段落(Paragraph)是最基本的内容单元，而文本样式则通过XWPFRun来控制。
2.1 创建段落与基础文本
创建段落是Word文档处理中最常见的操作。每个段落都是独立的文本块，可以有自己的对齐方式、缩进等属性。下面是一个创建段落并添加文本的完整示例：
import org.apache.poi.xwpf.usermodel.*; public class ParagraphExample { public static void main(String[] args) throws Exception { XWPFDocument doc = new XWPFDocument(); // 创建第一个段落 XWPFParagraph para1 = doc.createParagraph(); XWPFRun run1 = para1.createRun(); run1.setText("这是第一个段落，包含普通文本。"); // 创建第二个段落并设置对齐方式 XWPFParagraph para2 = doc.createParagraph(); para2.setAlignment(ParagraphAlignment.CENTER); // 居中对齐 XWPFRun run2 = para2.createRun(); run2.setText("这是居中对齐的段落。"); // 保存文档 try (FileOutputStream out = new FileOutputStream("paragraphs.docx")) { doc.write(out); } } }2.2 文本样式设置
XWPFRun类提供了丰富的方法来设置文本样式。我们可以轻松实现加粗、斜体、字体颜色、大小等常见格式：
// 创建样式丰富的段落 XWPFParagraph stylePara = doc.createParagraph(); XWPFRun styledRun = stylePara.createRun(); // 设置多种样式 styledRun.setBold(true); // 加粗 styledRun.setItalic(true); // 斜体 styledRun.setFontSize(14); // 字体大小 styledRun.setFontFamily("宋体"); // 字体 styledRun.setColor("FF0000"); // 红色文本 styledRun.setText("这段文本有多种样式效果！");2.3 高级文本控制
除了基础样式，我们还可以实现更复杂的文本控制：
// 在同一段落中添加不同样式的文本 XWPFParagraph multiStylePara = doc.createParagraph(); XWPFRun runPart1 = multiStylePara.createRun(); runPart1.setText("这部分是普通文本，"); XWPFRun runPart2 = multiStylePara.createRun(); runPart2.setBold(true); runPart2.setColor("0000FF"); runPart2.setText("这部分是蓝色加粗文本，"); XWPFRun runPart3 = multiStylePara.createRun(); runPart3.setUnderline(UnderlinePatterns.SINGLE); runPart3.setText("这部分带下划线。"); // 添加换行 runPart3.addBreak(); XWPFRun newLineRun = multiStylePara.createRun(); newLineRun.setText("这是新的一行文本。");2.4 段落属性设置
段落本身也有许多可设置的属性，这些属性会影响整个段落的外观：
// 设置段落属性 XWPFParagraph formattedPara = doc.createParagraph(); formattedPara.setAlignment(ParagraphAlignment.RIGHT); // 右对齐 formattedPara.setIndentationFirstLine(600); // 首行缩进 formattedPara.setSpacingBetween(1.5, LineSpacingRule.AUTO); // 行间距 formattedPara.setBorderBottom(Borders.DOUBLE); // 底部边框 XWPFRun paraRun = formattedPara.createRun(); paraRun.setText("这个段落有特殊的格式设置，包括右对齐、首行缩进和底部边框。");通过这些API，我们可以精确控制文档中每个段落、每段文本的外观，满足各种复杂的文档生成需求。在实际项目中，我经常将这些样式设置封装成工具方法，便于复用和维护统一的文档风格。
3. 表格操作：创建与格式化数据展示
在Word文档中，表格是展示结构化数据的重要方式。Apache POI提供了强大的表格操作API，让我们能够以编程方式创建和格式化各种复杂表格。
3.1 基础表格创建
创建一个基础表格非常简单，以下是一个完整的示例：
import org.apache.poi.xwpf.usermodel.*; public class BasicTableExample { public static void main(String[] args) throws Exception { XWPFDocument doc = new XWPFDocument(); // 创建一个3列4行的表格 XWPFTable table = doc.createTable(4, 3); // 设置表头 XWPFTableRow headerRow = table.getRow(0); headerRow.getCell(0).setText("序号"); headerRow.getCell(1).setText("产品名称"); headerRow.getCell(2).setText("价格"); // 填充数据行 fillTableData(table); // 保存文档 try (FileOutputStream out = new FileOutputStream("basic_table.docx")) { doc.write(out); } } private static void fillTableData(XWPFTable table) { String[][] data = { {"1", "笔记本电脑", "¥5,299"}, {"2", "智能手机", "¥3,899"}, {"3", "平板电脑", "¥2,599"} }; for (int i = 0; i < data.length; i++) { XWPFTableRow row = table.getRow(i + 1); // 跳过表头行 for (int j = 0; j < data[i].length; j++) { row.getCell(j).setText(data[i][j]); } } } }3.2 表格样式设置
Apache POI允许我们对表格进行各种样式设置：
// 设置表格宽度（占页面宽度的80%） table.setWidth("80%"); // 设置表格边框 table.setInsideHBorder(Borders.SINGLE, 4, 0, "000000"); table.setInsideVBorder(Borders.SINGLE, 4, 0, "000000"); table.setBottomBorder(Borders.DOUBLE, 12, 0, "FF0000"); // 设置单元格对齐方式 CTTcPr cellProps = table.getRow(0).getCell(0).getCTTc().addNewTcPr(); cellProps.addNewVAlign().setVal(STVerticalJc.CENTER); // 垂直居中 table.getRow(0).getCell(0).setVerticalAlignment(XWPFTableCell.XWPFVertAlign.CENTER);3.3 合并单元格与复杂表格
创建复杂表格时，经常需要合并单元格：
// 合并单元格示例 XWPFTable complexTable = doc.createTable(); // 添加行并合并单元格 XWPFTableRow row1 = complexTable.createRow(); row1.createCell().setText("合并行示例"); row1.addNewTableCell().setText("正常单元格"); row1.addNewTableCell().setText("正常单元格"); // 合并第一行的第一和第二列 complexTable.mergeCells(0, 0, 0, 1); // 添加第二行 XWPFTableRow row2 = complexTable.createRow(); row2.createCell().setText("合并列示例"); row2.addNewTableCell().setText("下方合并"); row2.addNewTableCell().setText("独立单元格"); // 合并第二行的第二和第三列 complexTable.mergeCells(1, 1, 1, 2);3.4 表格最佳实践
在实际项目中，处理表格时有一些经验值得分享：
性能考虑：创建大量表格时（如超过100行），建议分批处理并及时释放资源，避免内存溢出。
样式统一：将常用的表格样式封装成工具类，确保整个文档中表格风格一致。
动态数据：对于动态数据表格，先计算好最大行数再创建表格，避免频繁调整表格结构。
复杂布局：对于特别复杂的表格布局，考虑先在Word中设计好模板，然后使用POI进行内容填充。
单元格内容格式化：对于数字、日期等特殊格式，建议在插入表格前格式化好字符串。
下面是一个更完整的表格处理示例，展示了如何创建带有样式和动态数据的表格：
public class AdvancedTableExample { public static void main(String[] args) throws Exception { XWPFDocument doc = new XWPFDocument(); // 创建带样式的表格 XWPFTable table = doc.createTable(); table.setWidth("100%"); // 设置表头样式 XWPFTableRow headerRow = table.createRow(); styleHeaderCell(headerRow.getCell(0), "日期"); styleHeaderCell(headerRow.addNewTableCell(), "销售额"); styleHeaderCell(headerRow.addNewTableCell(), "增长率"); // 添加动态数据 addTableData(table); // 保存文档 try (FileOutputStream out = new FileOutputStream("sales_report.docx")) { doc.write(out); } } private static void styleHeaderCell(XWPFTableCell cell, String text) { cell.setText(text); cell.setColor("4472C4"); // 蓝色背景 cell.setVerticalAlignment(XWPFTableCell.XWPFVertAlign.CENTER); // 设置文本样式 for (XWPFParagraph p : cell.getParagraphs()) { for (XWPFRun r : p.getRuns()) { r.setBold(true); r.setColor("FFFFFF"); // 白色文字 r.setFontFamily("微软雅黑"); } p.setAlignment(ParagraphAlignment.CENTER); } } private static void addTableData(XWPFTable table) { String[][] salesData = getSalesData(); // 假设从数据库获取数据 for (String[] rowData : salesData) { XWPFTableRow row = table.createRow(); for (int i = 0; i < rowData.length; i++) { XWPFTableCell cell = row.getCell(i); cell.setText(rowData[i]); cell.setVerticalAlignment(XWPFTableCell.XWPFVertAlign.CENTER); // 特殊格式处理 if (i == 2) { // 增长率列 double rate = Double.parseDouble(rowData[i].replace("%", "")); if (rate < 0) { cell.setColor("FF0000"); // 红色背景表示负增长 } else if (rate > 0) { cell.setColor("00B050"); // 绿色背景表示正增长 } } } } } }通过这些表格操作技术，你可以创建出满足各种业务需求的复杂报表，无论是销售数据、统计报表还是产品目录，都能以专业的形式展现。
4. 高级功能与实战技巧
掌握了基础文档操作后，让我们探讨一些Apache POI的高级功能和实战中的技巧，这些知识将帮助你处理更复杂的Word自动化需求。
4.1 文档内容提取
除了生成文档，Apache POI还能从现有Word文档中提取内容。这在处理模板或分析现有文档时非常有用：
import org.apache.poi.xwpf.extractor.XWPFWordExtractor; public class DocumentExtractor { public static void main(String[] args) throws Exception { // 加载现有文档 try (FileInputStream fis = new FileInputStream("existing_document.docx"); XWPFDocument doc = new XWPFDocument(fis)) { // 方法1：提取全部文本 XWPFWordExtractor extractor = new XWPFWordExtractor(doc); System.out.println("全部文本内容:\n" + extractor.getText()); // 方法2：按段落提取 System.out.println("\n按段落提取:"); for (XWPFParagraph para : doc.getParagraphs()) { System.out.println(para.getText()); } // 方法3：提取表格数据 System.out.println("\n表格数据:"); for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { System.out.print(cell.getText() + "\t"); } System.out.println(); } } } } }4.2 图片插入与处理
在报告中插入图片是常见需求，Apache POI支持在文档中添加多种格式的图片：
public class ImageInsertExample { public static void main(String[] args) throws Exception { XWPFDocument doc = new XWPFDocument(); // 创建段落用于放置图片 XWPFParagraph para = doc.createParagraph(); para.setAlignment(ParagraphAlignment.CENTER); // 添加图片 try (FileInputStream imageStream = new FileInputStream("logo.png")) { XWPFRun run = para.createRun(); run.addPicture(imageStream, XWPFDocument.PICTURE_TYPE_PNG, "logo.png", Units.toEMU(200), // 宽度200像素 Units.toEMU(100)); // 高度100像素 run.addBreak(); // 图片后换行 run.setText("公司Logo"); } // 保存文档 try (FileOutputStream out = new FileOutputStream("document_with_image.docx")) { doc.write(out); } } }4.3 页眉页脚设置
专业文档通常需要设置页眉和页脚：
public class HeaderFooterExample { public static void main(String[] args) throws Exception { XWPFDocument doc = new XWPFDocument(); // 创建页眉 XWPFHeader header = doc.createHeader(HeaderFooterType.DEFAULT); XWPFParagraph headerPara = header.createParagraph(); headerPara.setAlignment(ParagraphAlignment.RIGHT); XWPFRun headerRun = headerPara.createRun(); headerRun.setText("公司机密文档 - 第"); headerRun.getCTR().addNewFldChar().setFldCharType(STFldCharType.BEGIN); headerRun.getCTR().addNewInstrText().setStringValue("PAGE"); headerRun.getCTR().addNewFldChar().setFldCharType(STFldCharType.END); headerRun.setText("页"); // 创建页脚 XWPFFooter footer = doc.createFooter(HeaderFooterType.DEFAULT); XWPFParagraph footerPara = footer.createParagraph(); footerPara.setAlignment(ParagraphAlignment.CENTER); footerPara.createRun().setText("Copyright © 2023 公司名称"); // 添加文档内容 doc.createParagraph().createRun().setText("文档正文内容..."); // 保存文档 try (FileOutputStream out = new FileOutputStream("header_footer.docx")) { doc.write(out); } } }4.4 性能优化技巧
处理大型文档时，性能优化尤为重要：
批量操作：尽量减少文档的I/O操作，先在内存中完成所有修改，再一次性写入磁盘。
资源管理：确保关闭所有流和文档对象，避免资源泄漏：
try (XWPFDocument doc = new XWPFDocument(); FileOutputStream out = new FileOutputStream("output.docx")) { // 文档操作... doc.write(out); } // 自动关闭资源缓存重用：对于频繁使用的样式或格式，创建一次后重复使用，而不是每次都新建。
分块处理：对于超大文档，考虑分块处理或使用SAX模式解析。
内存监控：处理大量文档时监控内存使用，必要时增加JVM堆大小。
4.5 常见问题解决方案
在实际项目中，可能会遇到以下问题及解决方案：
问题1：中文乱码
- 解决方案：确保使用支持中文的字体，如：
run.setFontFamily("宋体");问题2：样式不生效
- 解决方案：检查样式设置的顺序，某些属性需要在文本设置前配置。
问题3：生成的文档损坏
- 解决方案：确保正确关闭所有资源，避免写入过程中断。
问题4：复杂格式难以实现
- 解决方案：考虑使用模板文档，只修改内容部分，保留原有格式。
问题5：表格自动调整问题
- 解决方案：明确设置表格和列宽度：
table.setWidth("100%"); table.getRow(0).getCell(0).setWidth("20%");4.6 实战案例：合同生成系统
结合以上知识，我们可以构建一个合同生成系统。假设我们需要根据数据库中的数据自动生成标准合同：
public class ContractGenerator { public static void main(String[] args) throws Exception { // 从数据库获取合同数据 ContractData data = fetchContractData(); // 使用模板生成合同 try (FileInputStream template = new FileInputStream("contract_template.docx"); XWPFDocument doc = new XWPFDocument(template); FileOutputStream out = new FileOutputStream("generated_contract.docx")) { // 替换模板中的占位符 replacePlaceholders(doc, data); // 添加动态表格（如产品清单） addProductTable(doc, data.getProducts()); // 添加签名区域 addSignatureArea(doc, data.getParties()); doc.write(out); } } private static void replacePlaceholders(XWPFDocument doc, ContractData data) { for (XWPFParagraph para : doc.getParagraphs()) { String text = para.getText(); if (text != null) { text = text.replace("${contractNo}", data.getContractNo()) .replace("${date}", data.getSignDate()) .replace("${clientName}", data.getClientName()); // 清除原有内容 for (XWPFRun run : para.getRuns()) { run.setText("", 0); } // 添加新内容 para.createRun().setText(text); } } } private static void addProductTable(XWPFDocument doc, List<Product> products) { XWPFTable table = doc.createTable(); // 添加表头和产品行... } private static void addSignatureArea(XWPFDocument doc, List<Party> parties) { XWPFParagraph para = doc.createParagraph(); // 创建签名区域... } }通过这些高级功能和实战技巧，Apache POI可以满足企业级文档自动化处理的各种复杂需求，大幅提高工作效率和文档处理的准确性。