【JAVA - POI 实战】之动态生成Word图表：从模板渲染到代码绘制的进阶指南-平芜编程栈

1. POI操作Word图表的两大核心模式

用Java生成Word文档中的图表，POI库提供了两种截然不同的实现路径。我刚接触这个需求时，也曾纠结该选哪种方案，直到在三个实际项目中踩遍所有坑才真正理解它们的本质差异。

模板填充模式就像给预制房屋刷漆装修。你首先需要在Word里手动插入图表模板，设置好所有样式细节，代码只负责往内置的Excel表格填充数据。这种方式下，图表的坐标轴刻度、图例位置、数据标签格式等视觉元素都能在Office软件里精细调整。我做过一个财务分析系统，其中20多种固定格式的报表就是靠这套方案实现的，连CEO都夸呈现效果专业。

动态绘制模式则更像用乐高积木搭建筑。代码需要完全控制图表从无到有的创建过程，包括设置每个数据点的颜色、调整柱状图间距、配置折线图标记点等。去年开发动态报告生成器时，由于每个用户需要的图表类型和数量都不固定，我们不得不采用这种方案。虽然样式调校很痛苦，但能实现"千人千面"的个性化报告。

这两种模式最根本的区别在于：模板方案把样式配置前移到设计阶段，而动态方案将样式控制后置到代码阶段。就像装修房子，前者是精装房拎包入住，后者是毛坯房自己装修。

2. 模板填充方案的实战细节

2.1 模板制作的关键技巧

制作模板时有个容易翻车的细节：图表对应的内置Excel表格。有次我直接复制现有模板，结果数据总是错位，后来发现是Excel数据范围没同步更新。正确做法是：

在Word插入图表后，右键"编辑数据"
在Excel里预留足够行列（建议10x10起步）
删除示例数据但保留表头格式
特别注意第一行和第一列的特殊作用

// 刷新模板数据的核心代码片段 Workbook wb = new XSSFWorkbook(); Sheet sheet = wb.createSheet("Sheet1"); // 设置表头 sheet.createRow(0).createCell(0).setCellValue(""); for (int i = 1; i < titleArr.size(); i++) { sheet.getRow(0).createCell(i).setCellValue(titleArr.get(i)); } // 填充数据行 for (int i = 0; i < dataList.size(); i++) { Row row = sheet.createRow(i+1); row.createCell(0).setCellValue(dataList.get(i).getString(keyList.get(0))); for (int j = 1; j < keyList.size(); j++) { row.createCell(j).setCellValue(dataList.get(i).getDouble(keyList.get(j))); } }

2.2 多图表管理的经验之谈

当文档包含多个图表时，我总结出两种定位方式：

标题定位法更稳定可靠。通过chart.getTitle()获取图表标题，匹配时建议用contains()而非equals()，因为Office可能会自动添加换行符等隐藏字符。

for (POIXMLDocumentPart part : doc.getRelations()) { if (part instanceof XWPFChart) { XWPFChart chart = (XWPFChart)part; String title = chart.getTitleText(); if (title != null && title.contains("年度营收")) { // 找到目标图表 } } }

顺序定位法风险较高。依赖getRelations()返回的顺序，但不同版本的POI可能顺序不同。有次POI升级导致所有图表错乱，不得不紧急回滚。

3. 动态绘制方案的深度解析

3.1 创建图表的基础框架

动态创建图表就像在代码里组装一台精密仪器，每个部件都要精确配置。这个代码片段展示了如何搭建基础骨架：

// 创建图表基本框架 XWPFChart chart = document.createChart(run, (int)(14.5 * Units.EMU_PER_CENTIMETER), // 宽度 9 * Units.EMU_PER_CENTIMETER); // 高度 // 坐标轴设置 XDDFCategoryAxis xAxis = chart.createCategoryAxis(AxisPosition.BOTTOM); XDDFValueAxis yAxis = chart.createValueAxis(AxisPosition.LEFT); yAxis.setCrossBetween(AxisCrossBetween.BETWEEN); // 数据准备 String[] categories = {"Q1", "Q2", "Q3", "Q4"}; Double[] values = {1200.0, 1800.0, 1600.0, 2100.0}; XDDFCategoryDataSource xData = XDDFDataSourcesFactory.fromArray(categories); XDDFNumericalDataSource<Double> yData = XDDFDataSourcesFactory.fromArray(values); // 图表类型选择 XDDFBarChartData data = (XDDFBarChartData)chart.createData(ChartTypes.BAR, xAxis, yAxis); XDDFBarChartData.Series series = (XDDFBarChartData.Series)data.addSeries(xData, yData); chart.plot(data);

3.2 样式控制的六个关键点

柱状图变条形图：只需设置barDirection参数，但要注意坐标轴也要相应调整
```
data.setBarDirection(BarDirection.COL); // COL为条形图，BAR为柱状图
```
图例位置精控：除了常规的上下左右，还可以通过setOverlay()让图例覆盖在图表上
```
legend.setPosition(LegendPosition.TOP_RIGHT); legend.setOverlay(true);
```

数据标签定制：这个功能坑最多，比如百分比格式化需要特殊处理

CTDLbls dLbls = ser.addNewDLbls(); dLbls.addNewShowVal().setVal(true); dLbls.addNewDLblPos().setVal(STDLblPos.OUT_END); dLbls.addNewNumFmt().setFormatCode("0.00%");

颜色自定义方案：RGB值要转成字节数组，透明度设置经常被忽略

CTSRgbColor rgb = CTSRgbColor.Factory.newInstance(); rgb.setVal(new byte[]{(byte)255, (byte)0, (byte)0}); // 红色

折线图样式：平滑曲线与直角转折的视觉差异很大

lineSeries.setSmooth(true); // 平滑曲线 lineSeries.setMarkerStyle(MarkerStyle.CIRCLE); // 圆形标记点

坐标轴刻度：对数刻度需要特别注意零值和负值处理

yAxis.setLogBase(10); // 对数刻度 yAxis.setMinimum(0.1); // 最小值

4. 版本兼容性避坑指南

POI不同版本对图表的支持差异巨大，我整理了几个关键版本的分水岭：

3.17及以下：图表功能基本不可用，很多API直接抛出NotImplementedException
4.0.0：首次支持基础图表，但样式控制极其有限
4.1.2：里程碑版本，支持大多数图表类型和基础样式
5.0.0：引入XDDF新API，部分旧API被标记为@Deprecated

典型版本冲突案例：在POI 4.1.2运行正常的代码，在5.0.0上出现类找不到异常。这是因为org.apache.poi.xddf包进行了重构。解决方案是统一使用XDDF前缀的新类，如将XWPFChart改为XDDFChart。

// 新旧API对比 // 旧版 (4.1.2) CTChart ctChart = chart.getCTChart(); CTPlotArea plotArea = ctChart.getPlotArea(); // 新版 (5.0.0+) XDDFChart xddfChart = new XDDFChart(chart.getCTChart()); XDDFPlotArea plotArea = xddfChart.getPlotArea();

依赖冲突解决方案：建议使用Maven的dependencyManagement统一管理版本：

<dependencyManagement> <dependencies> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>5.2.3</version> </dependency> <!-- 其他POI组件版本保持一致 --> </dependencies> </dependencyManagement>