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

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

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

一、问题背景

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

开发过程遇到连锁问题：

1. cell.addParagraph() 新增段落，导出 Word 单元格多出空换行 / 空白段落标记；
2. 代码设置 cell.setVerticalAlignment、客户端 Word 格式刷，视觉上文字始终贴单元格上部，垂直居中看起来不生效；
3. 排查后定位核心诱因：段落设置 1.5倍多倍行距(LineSpacingRule.AUTO)。

二、知识点梳理

1. 段落行间距 setSpacingBetween

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

枚举	含义	参数单位	特点
LineSpacingRule.AUTO	多倍行距	倍数（1.0 /1.5 /2.0）	Word 自动弹性计算段落高度；会改变段落整体盒子高度，干扰单元格垂直居中视觉效果
LineSpacingRule.EXACT	固定值行距	磅	段落高度固定，排版稳定，不容易影响垂直居中
LineSpacingRule.AT_LEAST	最小值行距	磅	文字大于磅值自动撑开

配套段落间距（段前 / 段后，单位 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：两个对齐属性，归属层级完全不一样（重点区分）

1. 单元格垂直对齐（单元格属性 TcPr.VAlign）：控制【整个段落块】在单元格上下位置

   • 上层 API：cell.setVerticalAlignment(XWPFTable.XWPFVertAlign.CENTER)

   • 底层兜底（兼容性更好，旧 POI 推荐）：

     if(cell.getCTTc().getTcPr() == null){
     cell.getCTTc().addNewTcPr();
     }
     cell.getCTTc().getTcPr().addNewVAlign().setVal(STVerticalJc.CENTER);

2. 段落水平对齐（段落属性 PPr）：控制文字在段落内部左右位置

   p.setAlignment(ParagraphAlignment.LEFT);

需求【靠左、单元格垂直居中】组合：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);

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

1. 是否存在多余段落标记：打开 Word 显示编辑标记 ¶，检查单元格内空段落；
2. 对齐层级是否搞混：垂直居中是单元格属性，不是段落属性；
3. 是否使用 LineSpacingRule.AUTO 多倍行距，拉高段落盒子导致视觉偏移；
4. 段前 / 段后间距是否不为 0；
5. 是否开启文档网格对齐 SnapToGrid；
6. 客户端设置垂直居中时，是否选中了整个单元格而不是仅选中文字；
7. 不要依赖格式刷传递单元格垂直居中属性。

---

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

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

1. XWPFTableCell 自带默认第 0 段，直接 addParagraph 会新增段落，导出 Word 出现多余换行；优先复用 getParagraphs ().get (0)；
2. 对齐分两层：单元格 VAlign 垂直居中（单元格属性，格式刷刷不走），ParagraphAlignment 水平对齐（段落属性）；想要靠左垂直居中：VAlign=CENTER + LEFT；
3. 核心踩坑：段落设置 LineSpacingRule.AUTO 1.5 倍多倍行距时，Word 是把整个段落块在单元格居中；多倍行距会自动撑高段落盒子，造成文字视觉贴顶、误以为垂直居中失效；取消多倍行距，排版恢复正常；
4. 替代方案：需要 1.5 倍视觉效果优先使用 EXACT 固定磅值行距，段落高度稳定；
5. 辅助排查点：段前段后间距清零、关闭 SnapToGrid 网格对齐；客户端设置垂直居中必须选中整个单元格，格式刷无法复制单元格垂直对齐属性。