如何使用Apache POI在Java生成的.docx表格中合并列单元格？

问题分析 #

你当前的代码存在两个核心问题：

• 跨列设置逻辑错误：给多个单元格重复设置gridSpan，导致表格布局混乱，正确做法是仅对需要合并的单个单元格设置对应跨列数。
• 依赖版本不兼容：poi-ooxml（5.2.5）与poi-ooxml-schemas（4.1.2）版本不匹配，会引发API调用异常。

你需要实现的是第三行第二个单元格跨3列（表格总列数为4），让长文本能跨剩余全部宽度显示。

修正后的代码 #

// 添加预订详情标题
XWPFParagraph reservationDetailsHeader = document.createParagraph();
XWPFRun reservationDetailsRun = reservationDetailsHeader.createRun();
reservationDetailsRun.setText("预订详情");
reservationDetailsRun.setFontFamily("DejaVu Serif");
reservationDetailsRun.setFontSize(12);
reservationDetailsRun.setBold(true);

// 在标题下方添加空行
addLineSpace(document);

// 创建预订详情表格（初始1行4列，统一表格网格结构）
XWPFTable reservationDetailsTable = document.createTable(1, 4);

// 第一行数据
XWPFTableRow reservationRow1 = reservationDetailsTable.getRow(0);
reservationRow1.getCell(0).setText("入住日期:");
reservationRow1.getCell(1).setText("2024-12-20"); // 示例日期
reservationRow1.getCell(2).setText("入住晚数:");
reservationRow1.getCell(3).setText("1");

// 第二行数据
XWPFTableRow reservationRow2 = reservationDetailsTable.createRow();
reservationRow2.getCell(0).setText("退房日期:");
reservationRow2.getCell(1).setText("2024-12-22"); // 示例日期
reservationRow2.getCell(2).setText("房间数量:");
reservationRow2.getCell(3).setText("1");

// 第三行：第一个单元格为标签，第二个单元格跨3列显示内容
XWPFTableRow reservationRow3 = reservationDetailsTable.createRow();
reservationRow3.getCell(0).setText("房型及价格:");

// 获取第二单元格，设置跨列数为3（占据剩余3列）
XWPFTableCell spanCell = reservationRow3.getCell(1);
CTTcPr tcPr = spanCell.getCTTc().getTcPr();
if (tcPr == null) tcPr = spanCell.getCTTc().addNewTcPr();
CTGridSpan gridSpan = tcPr.addNewGridSpan();
gridSpan.setVal(BigInteger.valueOf(3));

// 设置长文本，此时文本会跨3列宽度显示
spanCell.setText("传统客房（最多2人）- 1张大床/固定房型");

// 删除该行多余的单元格，避免布局错乱
reservationRow3.removeCell(3);
reservationRow3.removeCell(2);

修正后的依赖配置 #

<dependencies>
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml</artifactId>
        <version>5.2.5</version>
    </dependency>
    <!-- 与poi-ooxml版本保持一致，避免兼容性问题 -->
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml-schemas</artifactId>
        <version>5.2.5</version>
    </dependency>
    <dependency>
        <groupId>org.apache.xmlbeans</groupId>
        <artifactId>xmlbeans</artifactId>
        <version>5.1.1</version>
    </dependency>
    <dependency>
        <groupId>org.apache.logging.log4j</groupId>
        <artifactId>log4j-core</artifactId>
        <version>2.20.0</version>
    </dependency>
</dependencies>

关键说明 #

• 统一表格网格：创建表格时直接指定1行4列，确保整个表格的列数结构一致。
• 精准跨列设置：仅对需要合并的单元格设置gridSpan，值为需要跨越的列数（这里是3，因为第一个单元格占1列，剩余3列合并）。
• 清理多余单元格：设置跨列后删除该行后续不需要的单元格，防止布局冲突。
• 依赖版本对齐：poi-ooxml与poi-ooxml-schemas必须使用相同版本，否则会出现API不兼容问题。

内容的提问来源于stack exchange，提问作者Gehan