以下是針對 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 文檔，滿足企業級應用需求。