Apache POI 如何实现Word表格单元格的垂直合并?
Apache POI 实现Word表格前三列垂直合并的实操方法
核心实现逻辑
Word表格的垂直合并没有POI封装的开箱即用直接API,本质是靠单元格底层XML的vMerge属性生效:作为合并块起点的单元格要标记为合并重启状态,后面同列连续行需要合并进来的单元格标记为接续合并状态,Word渲染时会自动把这些单元格拼成一个纵向的整体。
你开发的是6列表格,列索引从0开始计数,前三列对应索引0、1、2,按列逐列执行上面的属性设置就能完成合并。
可直接复用的代码实现
- 先编写通用的垂直合并工具方法,支持指定列、指定连续行范围的合并操作,同时规避XML节点重复创建的问题:
import org.apache.poi.xwpf.usermodel.XWPFTable; import org.apache.poi.xwpf.usermodel.XWPFTableCell; import org.openxmlformats.schemas.wordprocessingml.x2006.main.STMerge; /** * 表格指定列的连续行垂直合并 * @param table 目标6列Word表格对象 * @param colIndex 要合并的列索引(前三列对应0、1、2) * @param fromRow 合并起始行(行索引从0开始) * @param toRow 合并结束行 */ private static void mergeVertically(XWPFTable table, int colIndex, int fromRow, int toRow) { for (int rowIndex = fromRow; rowIndex <= toRow; rowIndex++) { XWPFTableCell currentCell = table.getRow(rowIndex).getCell(colIndex); // 避免重复创建TcPr节点,防止文档结构损坏 if (currentCell.getCTTc().getTcPr() == null) { currentCell.getCTTc().addNewTcPr(); } if (rowIndex == fromRow) { // 合并起点:标记为合并重启 currentCell.getCTTc().getTcPr().addNewVMerge().setVal(STMerge.RESTART); } else { // 合并续接点:标记为接续合并 currentCell.getCTTc().getTcPr().addNewVMerge().setVal(STMerge.CONTINUE); // 必须清空续接单元格的原有内容,避免合并后文本残留、错位 currentCell.setText(""); } } }
- 结合6列表格的业务场景调用方法即可,举个常见场景的调用示例:
// 初始化完成的6列表格对象 XWPFTable myTable = document.createTable(totalRowCount, 6); // 对第一列(索引0):跳过表头行(第0行),合并从第1行到第10行的单元格 mergeVertically(myTable, 0, 1, 10); // 对第二列(索引1):同样合并从第1行到第10行的单元格 mergeVertically(myTable, 1, 1, 10); // 对第三列(索引2):按业务需求指定合并的行范围 mergeVertically(myTable, 2, 1, 10);
实操中容易踩的坑
- 垂直合并仅支持同一列的连续行范围,如果业务需要把前三列先横向打通、再做跨行合并,需要先对每行的前三列做水平合并,再将水平合并后的单元格块按上面的逻辑做垂直合并
- 执行合并操作必须在所有表格行、单元格内容全部填充完成后进行,如果边插行边做合并,很容易出现行索引错位、合并位置错误的问题
- 续接状态的单元格不要单独设置字体、边距、段落格式,所有格式统一在合并起点的单元格上配置,避免出现格式错乱
- 如果合并后Word打开提示“表格有错误”,通常是vMerge的标记漏写、或者合并范围不连续导致的,需要逐行核对目标列的vMerge属性值
内容的提问来源于stack exchange,提问作者Ekaterina Ivanova iceja.net
相关产品推荐
相关产品推荐

