使用Apache POI操作Word文檔：從入門到實戰

Apache POI是Java生態中最流行的Microsoft Office文檔操作庫之一，它為Word文檔（包括傳統的.doc格式和現代的.docx格式）提供了全面的API支持。本文將詳細介紹如何使用Apache POI創建、讀取和修改Word文檔。

一、Apache POI簡介與環境準備

1. Apache POI組件

Apache POI包含多個組件用于處理不同Office文檔：

POI-HWPF：處理.doc格式（Word 97-2003）
POI-XWPF：處理.docx格式（Word 2007及以后版本）
POI-HSLF：處理PowerPoint
POI-HSSF/XSSF：處理Excel

2. 添加Maven依賴

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

3. 核心類介紹

XWPFDocument：代表整個Word文檔
XWPFParagraph：文檔中的段落
XWPFRun：段落中的文本運行（具有相同格式的文本段）
XWPFTable：表格
XWPFPicture：圖片

二、創建Word文檔

1. 創建簡單文檔

import org.apache.poi.xwpf.usermodel.*;import java.io.FileOutputStream;
import java.io.IOException;public class SimpleDocumentCreator {public static void main(String[] args) throws IOException {// 1. 創建空文檔XWPFDocument document = new XWPFDocument();// 2. 創建段落XWPFParagraph title = document.createParagraph();title.setAlignment(ParagraphAlignment.CENTER);// 3. 創建文本運行并設置樣式XWPFRun titleRun = title.createRun();titleRun.setText("Apache POI示例文檔");titleRun.setBold(true);titleRun.setFontSize(16);// 4. 添加正文段落XWPFParagraph body = document.createParagraph();body.setAlignment(ParagraphAlignment.LEFT);body.setIndentationFirstLine(600); // 首行縮進XWPFRun bodyRun = body.createRun();bodyRun.setText("這是使用Apache POI創建的Word文檔。");bodyRun.addBreak(); // 換行bodyRun.setText("POI支持豐富的文本格式設置。");// 5. 保存文檔try (FileOutputStream out = new FileOutputStream("SimpleDocument.docx")) {document.write(out);}document.close();System.out.println("文檔創建成功！");}
}

2. 添加復雜格式

// 創建帶格式的段落
XWPFParagraph styledPara = document.createParagraph();
styledPara.setAlignment(ParagraphAlignment.BOTH); // 兩端對齊XWPFRun styledRun = styledPara.createRun();
styledRun.setText("格式豐富的文本：");
styledRun.setColor("FF0000"); // 紅色
styledRun.setFontFamily("宋體");
styledRun.addBreak();// 添加不同格式的文本
styledRun = styledPara.createRun();
styledRun.setText("粗體+斜體");
styledRun.setBold(true);
styledRun.setItalic(true);
styledRun.addTab(); // 制表符styledRun = styledPara.createRun();
styledRun.setText("下劃線");
styledRun.setUnderline(UnderlinePatterns.SINGLE);

三、操作表格

1. 創建表格

// 創建3行4列的表格
XWPFTable table = document.createTable(3, 4);// 設置表格寬度
table.setWidth("100%");// 填充表頭
XWPFTableRow headerRow = table.getRow(0);
headerRow.getCell(0).setText("序號");
headerRow.getCell(1).setText("姓名");
headerRow.getCell(2).setText("年齡");
headerRow.getCell(3).setText("部門");// 填充數據
for (int i = 1; i < 3; i++) {XWPFTableRow row = table.getRow(i);row.getCell(0).setText(String.valueOf(i));row.getCell(1).setText("員工" + i);row.getCell(2).setText(String.valueOf(20 + i));row.getCell(3).setText(i % 2 == 0 ? "技術部" : "市場部");
}// 合并單元格
table.getRow(2).getCell(3).setText("備注：所有部門");
table.addNewColSpan(2, 3, 2); // 合并第3行的第3-4列

2. 表格樣式設置

// 設置表格邊框
CTTblPr tblPr = table.getCTTbl().getTblPr();
CTBorder border = tblPr.addNewTblBorders();
border.addNewBottom().setVal(STBorder.SINGLE);
border.addNewTop().setVal(STBorder.SINGLE);
border.addNewLeft().setVal(STBorder.SINGLE);
border.addNewRight().setVal(STBorder.SINGLE);
border.addNewInsideH().setVal(STBorder.SINGLE);
border.addNewInsideV().setVal(STBorder.SINGLE);// 設置表頭背景色
for (XWPFTableCell cell : headerRow.getTableCells()) {cell.setColor("D3D3D3"); // 淺灰色背景
}

四、插入圖片

import org.apache.poi.util.Units;// 從文件插入圖片
try (FileInputStream is = new FileInputStream("logo.png")) {XWPFParagraph imagePara = document.createParagraph();imagePara.setAlignment(ParagraphAlignment.CENTER);XWPFRun imageRun = imagePara.createRun();imageRun.addPicture(is, Document.PICTURE_TYPE_PNG, "logo.png", Units.toEMU(200), // 寬度Units.toEMU(100)); // 高度
}// 從字節數組插入圖片
byte[] imageData = getImageData(); // 獲取圖片字節數組的方法
XWPFRun imageRun = document.createParagraph().createRun();
imageRun.addPicture(new ByteArrayInputStream(imageData),Document.PICTURE_TYPE_JPEG,"photo.jpg",Units.toEMU(150),Units.toEMU(150));

五、讀取和修改現有文檔

1. 讀取文檔內容

public void readDocument(String filePath) throws IOException {try (FileInputStream fis = new FileInputStream(filePath);XWPFDocument document = new XWPFDocument(fis)) {System.out.println("==== 段落 ====");for (XWPFParagraph para : document.getParagraphs()) {System.out.println(para.getText());}System.out.println("\n==== 表格 ====");for (XWPFTable table : document.getTables()) {for (XWPFTableRow row : table.getRows()) {for (XWPFTableCell cell : row.getTableCells()) {System.out.print(cell.getText() + "\t");}System.out.println();}}}
}

2. 修改現有文檔

public void modifyDocument(String inputPath, String outputPath) throws IOException {try (FileInputStream fis = new FileInputStream(inputPath);XWPFDocument document = new XWPFDocument(fis)) {// 修改第一個段落XWPFParagraph firstPara = document.getParagraphs().get(0);if (firstPara != null) {XWPFRun run = firstPara.createRun();run.setText("\n(本文件由系統自動生成)");run.setItalic(true);run.setColor("808080");}// 在文檔末尾添加新內容XWPFParagraph newPara = document.createParagraph();newPara.setAlignment(ParagraphAlignment.RIGHT);XWPFRun newRun = newPara.createRun();newRun.setText("生成時間: " + LocalDate.now());newRun.addBreak(BreakType.PAGE); // 分頁符// 保存修改后的文檔try (FileOutputStream fos = new FileOutputStream(outputPath)) {document.write(fos);}}
}

六、高級功能

1. 頁眉頁腳設置

// 創建頁眉
XWPFHeader header = document.createHeader(HeaderFooterType.DEFAULT);
XWPFParagraph headerPara = header.createParagraph();
headerPara.setAlignment(ParagraphAlignment.RIGHT);
XWPFRun headerRun = headerPara.createRun();
headerRun.setText("公司機密");
headerRun.setColor("FF0000");// 創建頁腳
XWPFFooter footer = document.createFooter(HeaderFooterType.DEFAULT);
XWPFParagraph footerPara = footer.createParagraph();
footerPara.setAlignment(ParagraphAlignment.CENTER);
XWPFRun footerRun = footerPara.createRun();
footerRun.setText("頁碼: ");
footerRun.getCTR().addNewFldSimple().setInstr("PAGE \\* MERGEFORMAT");

2. 目錄生成

// 創建目錄段落
XWPFParagraph tocPara = document.createParagraph();
tocPara.setStyle("TOCHeading");XWPFRun tocRun = tocPara.createRun();
tocRun.setText("目錄");
tocRun.setBold(true);
tocRun.setFontSize(16);
tocRun.addBreak();// 添加目錄字段
tocRun = tocPara.createRun();
tocRun.getCTR().addNewFldSimple().setInstr("TOC \\o \"1-3\" \\h \\z \\u");

3. 批注（注釋）添加

// 在第一個段落添加批注
XWPFParagraph firstPara = document.getParagraphs().get(0);
String commentText = "這是系統自動添加的批注";
String commentAuthor = "AutoSystem";
CTComment ctComment = document.getDocument().getBody().addNewComment();
ctComment.setAuthor(commentAuthor);
ctComment.setDate(new GregorianCalendar());
ctComment.addNewP().addNewR().addNewT().setStringValue(commentText);// 將段落與批注關聯
CTMarkupRange range = firstPara.getCTP().addNewCommentRangeStart();
range.setId(ctComment.getId());
firstPara.getCTP().addNewCommentRangeEnd().setId(ctComment.getId());
firstPara.getCTP().addNewR().addNewCommentReference().setId(ctComment.getId());

七、性能優化與最佳實踐

1. 大文件處理優化

對于大文檔，建議使用事件模型（XWPFEventAPI）而非DOM模型：

import org.apache.poi.xwpf.eventusermodel.*;public class LargeDocumentReader {public static void main(String[] args) throws Exception {OPCPackage pkg = OPCPackage.open("large.docx");XWPFEventBasedParser parser = new XWPFEventBasedParser();parser.parse(pkg, new XWPFVisitor() {@Overridepublic void visitParagraph(XWPFParagraph paragraph) {System.out.println("段落: " + paragraph.getText());}@Overridepublic void visitTable(XWPFTable table) {System.out.println("發現表格");}});pkg.close();}
}

2. 內存管理

及時關閉文檔對象和流
對于批量處理，考慮復用XWPFDocument對象
使用try-with-resources確保資源釋放

3. 樣式重用

// 創建并重用樣式
CTSectPr sectPr = document.getDocument().getBody().addNewSectPr();
CTPageSz pageSz = sectPr.addNewPgSz();
pageSz.setW(BigInteger.valueOf(12240)); // A4寬度
pageSz.setH(BigInteger.valueOf(15840)); // A4高度// 創建段落樣式
CTStyle ctStyle = CTStyle.Factory.newInstance();
ctStyle.setStyleId("MyStyle");
CTPPr pPr = ctStyle.addNewPPr();
pPr.addNewSpacing().setAfter(BigInteger.valueOf(200)); // 段后間距
document.getStyle().addStyle(ctStyle);// 應用樣式
XWPFParagraph para = document.createParagraph();
para.setStyle("MyStyle");

八、常見問題與解決方案

1. 中文亂碼問題

確保使用支持中文的字體：

run.setFontFamily("宋體");

或者在文檔級別設置默認字體：

document.getStyles().setDefaultFonts("宋體", null);

2. 格式不兼容問題

盡量使用.docx格式而非.doc格式
避免使用太新的Office特性
在生成文檔后進行兼容性測試

3. 性能問題

對于大文檔，分批次處理內容
避免頻繁創建/銷毀XWPFRun對象
考慮緩存常用樣式

九、總結

Apache POI提供了強大而靈活的API來操作Word文檔，從簡單的文本生成到復雜的格式設置、表格處理和圖片插入都能勝任。通過本文的介紹，您應該已經掌握了：

基本的文檔創建與保存
文本格式設置與段落控制
表格的創建與樣式設置
圖片插入方法
現有文檔的讀取與修改
高級功能如頁眉頁腳、目錄生成
性能優化技巧

在實際項目中，建議根據具體需求選擇合適的API，并注意資源管理和性能優化。對于更復雜的需求，可以結合模板引擎或考慮商業解決方案。

Apache POI的官方文檔和社區資源豐富，遇到問題時可以查閱：

官方文檔：https://poi.apache.org/
API文檔：https://poi.apache.org/apidocs/index.html
示例代碼：https://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/examples/