poi-tl模板合并单元格后数据丢失如何解决？

Question

在使用 poi-tl 模板引擎进行 Word 文档导出时，常遇到“合并单元格后数据丢失”的问题。当模板表格中存在跨行或跨列合并的单元格，poi-tl 在解析时可能无法正确识别数据填充位置，导致动态数据未写入或被覆盖。尤其在循环插入数据（如 List 填充）场景下，合并单元格会破坏原有单元格映射关系，造成后续数据错位或丢失。该问题根源在于 poi-tl 对合并单元格的坐标处理逻辑不完善，未能同步更新合并区域的数据绑定。如何在保留合并格式的同时确保数据准确渲染，成为实际开发中的典型难题。

Answer 1

1. 问题现象与典型场景

在使用 poi-tl 模板引擎导出 Word 文档时，开发者常遇到“合并单元格后数据丢失”的问题。该问题多出现在包含复杂表格结构的模板中，尤其是财务报表、合同明细、项目汇总等需跨行/跨列合并的业务文档。

• 模板中某一行标题单元格被横向合并（如 A1:D1），用于展示分类标题；
• 后续行使用 {{#list}} 循环插入动态数据；
• 实际渲染后发现：部分数据未写入、内容错位、甚至整个表格结构崩溃；
• 通过日志和调试发现，poi-tl 在解析时未能正确映射合并单元格的逻辑坐标与物理存储位置。

2. 根本原因分析

poi-tl 基于 Apache POI 构建，其核心机制是通过正则匹配模板占位符并替换为真实数据。但在处理表格时，它依赖于单元格的行列索引进行绑定。当存在合并单元格时，多个物理单元格共享一个值，但只保留起始坐标（如 MergeRegion: (0,0)-(0,3)），其余单元格为空。

行号	列A	列B	列C	说明
0	分类标题（合并A0-C0）			仅A0有值，B0/C0为空
1	{{name}}	{{age}}	{{dept}}	循环数据起始行
2	{{name}}	{{age}}	{{dept}}	预期第二条记录

在执行数据填充时，poi-tl 可能错误地将第一条数据写入已被合并“覆盖”的空单元格，导致跳过有效位置或覆盖已有文本。

3. 技术栈影响与限制

该问题不仅限于 poi-tl 本身，也反映出 Apache POI 在处理 Office Open XML (OOXML) 表格模型中的深层挑战。Word 的表格结构由 <w:tbl> 定义，合并通过 <w:vMerge> 和 <w:hMerge> 实现，而 poi-tl 缺乏对这些标签的完整语义理解。

<w:tc>
  <w:tcPr>
    <w:vMerge w:val="restart"/>
  </w:tcPr>
  <w:p><w:r><w:t>合并单元格内容</w:t></w:r></w:p>
</w:tc>
    

当前版本（如 poi-tl 1.9.x）未提供钩子接口来干预单元格坐标的重映射过程，使得开发者难以介入修复坐标偏移。

4. 解决方案演进路径

1. 规避法：避免在数据区域上方使用合并单元格，或将合并内容移至独立段落；
2. 预处理模板：在生成前用 POI 手动拆分所有合并单元格，填充静态内容后再恢复合并状态；
3. 自定义插件：继承 TableRenderPolicy，重写 renderRow 方法，加入合并区域检测逻辑；
4. 坐标映射表：构建运行时的“逻辑行→物理行”映射缓存，动态调整插入位置；
5. 替代引擎：评估使用 docx4j 或 FreeMarker + XSL-FO 等更灵活的方案处理复杂布局。

5. 自定义策略代码示例

public class SmartTableRenderPolicy extends AbstractRenderPolicy<List<Map<String, Object>>> {
    @Override
    protected boolean validate(List<Map<String, Object>> data) {
        return data != null && !data.isEmpty();
    }

    @Override
    public void doRender(RenderContext<List<Map<String, Object>>> context) throws Exception {
        List<Map<String, Object>> dataList = context.getData();
        Tbl table = context.getParagraph().getCTP().getParent().getTable();
        List<TblGridCol> cols = table.getTblGrid().getGridColList();
        
        // 获取所有合并区域
        List<CellRangeAddress> merges = getMerges(table);
        
        int startRow = context.getStartRowIndex();
        for (int i = 0; i < dataList.size(); i++) {
            int actualRowIdx = startRow + i;
            if (isInMergeRegion(actualRowIdx, merges)) {
                // 跳过被合并占据的行
                continue;
            }
            renderDataRow(table, actualRowIdx, dataList.get(i));
        }
    }

    private boolean isInMergeRegion(int row, List<CellRangeAddress> merges) {
        return merges.stream().anyMatch(m -> row >= m.getFirstRow() && row <= m.getLastRow());
    }
}
    

6. 流程图：数据渲染控制逻辑

graph TD
            A[开始渲染表格] --> B{是否存在合并单元格?}
            B -- 否 --> C[按默认策略逐行填充]
            B -- 是 --> D[解析所有MergeRegion]
            D --> E[构建逻辑行索引映射]
            E --> F[遍历数据列表]
            F --> G{当前行是否属于合并区?}
            G -- 是 --> H[跳过该行]
            G -- 否 --> I[执行占位符替换]
            I --> J[更新实际行指针]
            J --> F
            F --> K[结束渲染]