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

Question

在使用 poi-tl 模板引擎进行 Word 文档生成时，常遇到合并单元格后数据丢失的问题。该问题通常发生在动态表格中，当模板定义了跨行或跨列合并的单元格，并结合循环渲染数据时，poi-tl 未能正确保留原单元格内容或未按预期填充数据，导致部分数据被覆盖或清空。尤其在使用 `{{#list}}` 循环与 `{{text}}` 占位符共存于合并单元格中时更为明显。如何在保持格式合并的同时确保数据完整渲染，是开发者频繁面临的挑战。

Answer 1

1. 问题背景与现象描述

在使用 poi-tl 模板引擎生成 Word 文档时，动态表格是常见需求之一。开发者通常通过模板中的 {#list} 标签实现数据的循环渲染，同时结合单元格合并来优化文档可读性。然而，当合并单元格（尤其是跨行或跨列）与 {text} 占位符共存于同一单元格，并被 {#list} 包裹时，常出现数据丢失或覆盖的问题。

典型表现为：仅首行数据正确填充，其余行对应合并区域内容为空；或合并前的原始文本被清空，无法保留静态信息。例如，在“项目汇总表”中，第一列“类别”进行跨3行合并，其内含 {categoryName} 和 {#list items}，结果只有第一条记录显示类别名称，其余两条为空。

2. 技术原理剖析：poi-tl 的解析机制

• poi-tl 基于 Apache POI 构建，采用 DOM 模式解析 Word 模板（.docx），将占位符替换为实际数据。
• 模板中的 {#list} 被识别为“循环指令”，引擎会复制当前段落或表格行作为模板行进行多次渲染。
• 但当单元格已合并时，底层 XML 结构包含 vMerge 或 hMerge 属性，poi-tl 在复制行过程中未能正确继承这些合并状态及原始内容。
• 更关键的是，若合并单元格中同时存在多个指令（如 {#list} 和 {text}），引擎执行顺序可能导致占位符被提前清除或重复插入。

3. 常见错误场景示例

场景编号	模板结构	预期行为	实际表现
1	合并3行单元格含 {category} + {#list items}	每组数据块显示类别名	仅首行显示，其余为空
2	横向合并列中嵌套 {#list} 循环	横向展开数据	列数错乱，合并失效
3	合并单元格位于循环外但与循环行相邻	保持原格式不变	格式错位，边框断裂
4	多级嵌套 list 中涉及跨行合并	层级清晰展示	子项错位，父项内容丢失
5	合并单元格内仅含 {text} 无 list	正常填充文本	偶尔清空（缓存问题）

4. 分析过程：从日志到 XML 结构追踪

解决此类问题需深入分析 .docx 文件的实际结构。.docx 本质是 ZIP 包，解压后查看 word/document.xml 可发现：

<w:tc>
  <w:tcPr>
    <w:vMerge w:val="restart"/>
  </w:tcPr>
  <w:p><w:r><w:t>{categoryName}</w:t></w:r></w:p>
</w:tc>
    

当 poi-tl 执行 {#list} 时，它复制整行，但新行中的 w:vMerge 若未设置为 "continue"，则 Word 不再视其为合并部分，导致视觉断开。此外，原始文本节点可能在渲染前被清除，造成数据不可恢复。

5. 解决方案一：重构模板结构避免冲突

最稳妥的方式是分离逻辑与格式。建议将合并控制移出数据渲染区域：

1. 将需合并的内容提取至循环外部单独处理。
2. 使用辅助字段标记是否为首项，仅在首项输出合并单元格。
3. 利用自定义插件（CustomObject）控制单元格属性。

示例代码：

Map data = new HashMap<>();
data.put("isFirst", true);
data.put("categoryName", "电子产品");
List items = Arrays.asList(item1, item2, item3);
// 在插件中判断 isFirst 并设置 vMerge
    

6. 解决方案二：使用 CustomRenderPolicy 自定义渲染策略

通过继承 AbstractRenderPolicy 实现对合并单元格的精细控制：

public class MergedCellRenderPolicy extends AbstractRenderPolicy<List<Data>> {
    @Override
    protected void afterRender(RenderContext<List<Data>> context) {
        // 手动修复 vMerge 和 hMerge 标志
        for (int i = 0; i < dataList.size(); i++) {
            setVMergeValue(tableRow(i), i == 0 ? "restart" : "continue");
        }
    }
}
    

注册该策略：XWPFTemplate.registerPolicy("items", new MergedCellRenderPolicy());

7. 解决方案三：预处理模板，拆分合并逻辑

在模板设计阶段规避风险：

• 避免在合并单元格内部放置 {#list}。
• 使用“隐藏列”存储分类信息，渲染后再通过程序合并相同值的行。
• 采用“分组标题行”模式：每组前插入一个独立标题行，不参与循环，直接写入类别名。

8. 高级技巧：结合 Mermaid 流程图理解渲染流程

graph TD
            A[加载模板.docx] --> B{是否存在合并单元格?}
            B -- 是 --> C[检查是否包含{#list}]
            B -- 否 --> D[正常渲染]
            C -- 是 --> E[应用CustomRenderPolicy]
            C -- 否 --> F[直接替换{text}]
            E --> G[遍历数据集]
            G --> H[首行设vMerge=restart]
            G --> I[后续行设vMerge=continue]
            I --> J[保留原始文本]
            J --> K[输出最终文档]

9. 工具推荐与最佳实践总结

为提升开发效率，推荐以下工具链：

工具	用途	优势
OpenXML SDK Tool	查看.docx内部结构	精准定位vMerge/hMerge
Apache POI Browser	调试XWPF对象树	实时观察TableCell状态
Lombok	简化Java模型类	减少样板代码
JUnit + AssertJ	验证输出文档	自动化测试合并效果

最佳实践包括：模板最小化指令嵌套、优先使用外部控制合并、启用调试日志跟踪渲染过程、定期升级 poi-tl 至最新版本以获取修复补丁。

10. 社区反馈与未来展望

目前 GitHub 上已有多个关于合并单元格丢失数据的 issue（如 #187、#203），社区普遍呼吁增强对复杂表格的支持。未来版本有望引入“智能合并感知渲染器”，自动推断并维护 vMerge/hMerge 状态。同时，有开发者提出基于 XPath 的选择器机制，允许精确绑定数据到特定单元格，绕过现有循环限制。

随着企业级文档自动化需求增长，对 poi-tl 的稳定性与灵活性要求不断提升，掌握其底层机制将成为高级 Java 开发者的核心竞争力之一。