Java在Word中绘制折线图时图表数据不显示

Question

在使用Java通过Apache POI操作Word文档绘制折线图时，常出现图表已生成但数据未正确显示的问题。主要原因包括：数据区域未正确绑定到图表、CTChart对象的数据源配置缺失或路径错误、未刷新图表数据缓存，以及行索引计算偏差导致数据写入空白单元格。此外，若未按POI要求的格式将数据写入关联的表格，图表引擎无法读取有效数据，也会造成图表为空。该问题多发生在动态生成数据并插入图表的场景中。

Answer 1

使用Java通过Apache POI操作Word文档绘制折线图的深度解析

1. 问题背景与常见现象

在企业级文档自动化场景中，Java开发者常借助Apache POI库动态生成包含图表的Word文档（.docx）。其中，折线图作为展示趋势数据的重要形式，广泛应用于报表、分析报告等场景。然而，尽管图表框架成功插入文档，但实际运行时常出现“图表为空”或“数据显示异常”的问题。

典型表现为：图表容器可见，坐标轴存在，但无任何数据点或折线未渲染。该问题多发生于动态数据写入流程中，尤其当数据源来自数据库、API或实时计算模块时更为显著。

2. 根本原因分析（由浅入深）

1. 数据区域未正确绑定到图表：POI创建图表后，需显式将CTChart中的series引用指向XSSFTable中的具体单元格范围，若绑定路径错误，则图表无法获取数据。
2. CTChart对象的数据源配置缺失：未设置ctChart.plotArea().getPlotCharts().get(0)中的catCache和valCache缓存对象，导致图表引擎无数据上下文。
3. 未刷新图表数据缓存：即使数据已写入表格，若未调用chart.getCTChart().getPlotArea().getLineChartArray()并更新其缓存值，图表仍显示旧状态。
4. 行索引计算偏差：动态生成数据时，若循环起始行号偏移（如从第0行开始而非第1行），可能导致数据写入空白或标题行，造成读取失败。
5. 数据格式不符合要求：数值未以XSSFRichTextString或Double类型写入，或日期格式未标准化，导致图表引擎解析失败。

3. 技术实现流程图

    graph TD
        A[初始化XWPFDocument] --> B[创建表格并写入数据]
        B --> C[插入图表占位符]
        C --> D[获取CTChart对象]
        D --> E[绑定数据区域至series]
        E --> F[更新catCache与valCache]
        F --> G[强制刷新图表缓存]
        G --> H[保存文档]
    

4. 关键代码示例

// 创建数据表
XWPFTable table = document.createTable();
for (int i = 0; i < data.length; i++) {
    XWPFTableRow row = table.getRow(i);
    if (row == null) row = table.createRow();
    for (int j = 0; j < data[i].length; j++) {
        row.getCell(j).setText(String.valueOf(data[i][j]));
    }
}

// 绑定图表数据源
CTChart ctChart = chart.getCTChart();
CTPlotArea plotArea = ctChart.getPlotArea();
CTLineChart lineChart = plotArea.getLineChartArray(0);

// 设置分类轴缓存（X轴标签）
CTAxDataSource catDS = CTAxDataSource.Factory.newInstance();
CTStrRef strRef = catDS.addNewStrRef();
strRef.setF("Sheet1!$A$2:$A$" + (data.length)); // 注意起始行为2
lineChart.getSerArray(0).setCat(catDS);

// 设置值轴缓存（Y轴数据）
CTNumDataSource valDS = CTNumDataSource.Factory.newInstance();
CTNumRef numRef = valDS.addNewNumRef();
numRef.setF("Sheet1!$B$2:$B$" + (data.length));
lineChart.getSerArray(0).setVal(valDS);
    

5. 数据绑定校验表

检查项	正确做法	常见错误	修复建议
数据起始行	从第2行开始（第1行为标题）	从第1行写入数据	调整索引+1
单元格格式	数值用setCellValue(double)	全部使用setText()	区分字符串与数字类型
区域引用语法	Sheet1!$A$2:$A$10	缺少$符号或拼写错误	严格遵循Excel命名规则
缓存更新	手动设置catCache与valCache	依赖自动绑定	显式调用setCache()
图表刷新机制	调用chart.getPackagePart().revert()	未触发刷新	保存前强制重载
行列对应关系	X轴为时间/类别，Y轴为数值	行列颠倒	检查series配置方向
多系列支持	每个ser独立配置数据源	共用同一range	逐个绑定series
命名工作表	明确指定sheetName	默认sheet名变更	固定名称或动态获取
内存释放	及时关闭流资源	频繁生成导致OOM	使用try-with-resources
版本兼容性	使用poi-ooxml-full最新版	旧版本API不支持	升级至5.2.5+

6. 高级调试策略

对于复杂场景，建议采用以下方法进行诊断：

• 导出生成的.docx文件，解压后查看word/charts/chart1.xml中是否包含正确的f字段引用。
• 使用ZipFile类程序化读取内部XML，验证<c:f>Sheet1!$B$2:$B$10</c:f>是否存在且路径有效。
• 在开发阶段启用System.out.println(ctChart.xmlText())输出完整结构，定位缺失节点。
• 利用XWPFChart的getOrCreateLegend()和setVisible(true)辅助判断数据系列是否被识别。
• 模拟静态数据先行验证流程，再逐步替换为动态逻辑，缩小排查范围。