Apache POI XWPFTableCell 表格单元格排版踩坑总结

Apache POI XWPFTableCell 表格单元格排版踩坑总结

适用：Apache POI（5.4.1） 生成 Word，表格单元格文字对齐、行距、多余换行问题

一、问题背景

使用 Apache POI XWPFTable + XWPFTableCell 生成 Word 表格，需求：单元格文字水平靠左、单元格内垂直居中。

开发过程遇到连锁问题：

二、知识点梳理

1. 段落行间距 setSpacingBetween

方法签名：paragraph.setSpacingBetween(double spacing, LineSpacingRule rule)

配套段落间距（段前 / 段后，单位 twips，1 磅 = 20twips）

paragraph.setSpacingBefore(0); // 段前间距清零
paragraph.setSpacingAfter(0); // 段后间距清零

2. XWPFTableCell 表格单元格核心坑点

坑 1：单元格天生自带 1 个默认段落

只要创建 XWPFTableCell，内部默认存在第 0 号段落。

• ❌ 错误写法：cell.addParagraph() → 在原有段落后面追加新段落，单元格存在空段落 + 正文段落，打开 Word 可见多余换行；
• ✅ 推荐写法：复用原生段落 XWPFParagraph p = cell.getParagraphs().get(0);；

如果业务需要动态新增多个段落，先清空原有段落：

while (cell.getParagraphs().size() > 0) {
cell.removeParagraph(0);
}

坑 2：两个对齐属性，归属层级完全不一样（重点区分）

需求【靠左、单元格垂直居中】组合：VAlign=CENTER + ParagraphAlignment.LEFT

坑 3：Word 格式刷的局限

✅ 格式刷可以复制：字体、字号、水平对齐、行距、段前段后等段落格式

❌ 格式刷无法复制单元格属性：单元格垂直居中、单元格边距、单元格底纹

客户端操作提醒：设置垂直居中，必须选中整个单元格（不是只拖选文字）→【表格工具 – 布局】→对齐方式

坑 4：多倍行距造成 “垂直居中看起来失效”（本次核心根因）

单元格垂直居中生效逻辑：将整个段落块作为一个整体，在单元格内居中

• 设置 1.5倍行距(AUTO)：段落盒子高度被 Word 自动放大，段落内部上方自带空白，视觉上文字贴单元格顶部；
• 取消 1.5 倍行距，段落盒子收缩，文字即可正常视觉居中；

业务如果必须保留 1.5 倍行距的两个方案：

方案 A：改用固定值行距近似替代（如 21 磅），段落高度可控；

方案 B：保留 AUTO 多倍行距，同时关闭网格对齐 SnapToGrid=OFF，段前段后清零。

三、最终可用标准代码模板（单元格靠左垂直居中）

import org.apache.poi.xwpf.usermodel.*;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STVerticalJc;

XWPFTableCell cell = table.getRow(pos).getCell(col);
// 底层设置单元格垂直居中（兼容性兜底）
if(cell.getCTTc().getTcPr() == null){
cell.getCTTc().addNewTcPr();
}
cell.getCTTc().getTcPr().addNewVAlign().setVal(STVerticalJc.CENTER);

// 复用单元格原生段落，避免多余空段落
XWPFParagraph p = cell.getParagraphs().get(0);
// 水平靠左
p.setAlignment(ParagraphAlignment.LEFT);
// 段前段后清零，消除额外留白
p.setSpacingBefore(0);
p.setSpacingAfter(0);
// 按需开启行距：如果需要1.5倍，优先考虑EXACT固定磅值，避免视觉偏移
// p.setSpacingBetween(21, LineSpacingRule.EXACT);

XWPFRun run = p.createRun();
run.setFontFamily(fontFamily);
run.setFontSize(fontSize);
run.setText(textContent);

四、排查清单（后续遇到同类问题直接对照）

给 AI 快速理解用的精简版文本

Apache POI XWPFTableCell 表格单元格排版问题总结：