JQuick-Excel 导出图表使用规范面向 Java 开发者的 JQuick-Excel 图表导出规范说明。本文聚焦EXPORT WITH GRAPH {...}的 DSL 配置、适用边界、代码约束与最佳实践。更多示例: JQuick-Excel 官网示例 https://www.jquick.org/jquick-excel/#demo-formulas00051. 适用范围JQuick-Excel 当前支持通过 DSL 方式直接导出 Excel 图表底层基于 Apache POI XSSF / XDDF 实现。当前支持的图表类型类型编码图表名称典型场景COLUMN柱状图分类对比、销售额对比BAR条形图排名展示、横向比较BAR3D3D 条形图强展示场景LINE折线图趋势分析PIE饼图占比分析AREA面积图累积趋势AREA3D3D 面积图强展示场景SCATTER散点图相关性分析RADAR雷达图多维能力评估SURFACE曲面图三维矩阵数据2. 基本设计原则图表导出和普通表格导出不同GRAPH 是“图表驱动”而不是“数据表驱动”。也就是说MAPPING/FORMAT/TRANSFORM主要作用于表格单元格导出GRAPH使用的是独立图表数据模型TYPE、TITLE、CATEGORIES、SERIES图表数据不会自动从ListMapString,Object中推导必须在 DSL 中显式声明建议把 GRAPH 理解为一段声明式图表配置 一组内嵌类别/序列数据 - 生成 Excel 图表 Sheet3. DSL 规范3.1 标准结构EXPORT WITH GRAPH { TYPE COLUMN, TITLE 销售数据统计, CATEGORY_AXIS 产品, VALUE_AXIS 销量, CATEGORIES [产品A, 产品B, 产品C, 产品D], SERIES [ { NAME 第一季度, DATA [120, 200, 150, 180] }, { NAME 第二季度, DATA [180, 210, 190, 220] } ] }3.2 字段说明字段是否必填类型说明TYPE是枚举图表类型TITLE是String图表标题CATEGORY_AXIS否String分类轴标题常用于 X 轴VALUE_AXIS否String数值轴标题常用于 Y 轴CATEGORIES是Array分类集合SERIES是Array数据系列集合SERIES[].NAME是String/Identifier系列名称SERIES[].DATA是Array系列数值集合4. 数据约束这是程序员最需要关注的部分。4.1CATEGORIES.size()必须与每个SERIES.DATA.size()一致图表工厂内部使用第一列写CATEGORIES后续列逐个写每个SERIES然后根据单元格区域创建图表数据源因此必须满足每个系列的数据点数量 分类数量正确示例CATEGORIES [Q1, Q2, Q3, Q4], SERIES [{ NAME 产品A, DATA [100, 120, 130, 150] }]错误示例CATEGORIES [Q1, Q2, Q3, Q4], SERIES [{ NAME 产品A, DATA [100, 120] }]后者会导致图表数据区域不匹配表现为图表数据缺失图表显示异常某些类型下直接生成错误图表4.2SERIES至少要有一组SERIES []这种配置没有业务意义也不应该用于生产环境。建议规范SERIES.size() 1每个SERIES.DATA.size() 14.3DATA中应全部为数值推荐使用intlongdoubleBigDecimal对应的数值字面量不推荐文本数字如120带单位字符串如120万空字符串 / null4.4PIE图建议只放一组系列虽然底层接口允许按统一模型传入多组SERIES但从业务语义上饼图通常应只有1 个系列CATEGORIES表示扇区名称DATA表示每个扇区值推荐写法TYPE PIE, CATEGORIES [Apple, Samsung, Xiaomi, Other], SERIES [{ NAME 市场份额, DATA [38.5, 22.3, 15.7, 23.5] }]5. 各图表类型使用建议5.1COLUMN适用于同维度多系列对比。TYPE COLUMN, TITLE 销售数据统计, CATEGORY_AXIS 产品, VALUE_AXIS 销量推荐场景产品销量对比班级成绩对比部门人力规模对比5.2BAR适用于排名型数据尤其分类名较长时优于COLUMN。推荐场景季度销售排行城市 GDP 排名TopN 指标横向比较5.3LINE适用于时间序列 / 趋势分析。推荐场景月度温度变化订单趋势活跃用户增长曲线5.4PIE适用于单组占比。不适合类别过多多系列并列比较时间趋势分析5.5AREA/AREA3D适用于累积型趋势展示强调面积感。5.6SCATTER适用于二维相关性分析。例如身高 / 体重价格 / 销量CPU 使用率 / 响应时间5.7RADAR适用于多维能力评估每组对象在多个维度下对比。5.8SURFACE适用于三维矩阵型数据。这是当前最不适合普通业务报表的图表类型建议仅在明确有三维展示诉求时使用。6. Java 调用方式6.1 最小可用示例Stringrule EXPORT WITH GRAPH { TYPE COLUMN, TITLE 销售数据统计, CATEGORY_AXIS 产品, VALUE_AXIS 销量, CATEGORIES [产品A, 产品B, 产品C, 产品D], SERIES [{ NAME 第一季度, DATA [120, 200, 150, 180] }, { NAME 第二季度, DATA [180, 210, 190, 220] }] } ;JQuickExcelCommonExportExecutorexecutornewJQuickExcelCommonExportExecutor();JExcelExportModelconfig(JExcelExportModel)executor.execute(rule);JExcelExportHandlerhandlernewJExcelExportHandler(config,newArrayList());try(FileOutputStreamoutnewFileOutputStream(D://test//column.xlsx)){handler.getWorkBook().write(out);}6.2 推荐调用姿势如果只是导出图表数据行可传空集合new ArrayList()只通过GRAPH生成独立图表工作表如果要同时导出表格和图表当前更适合拆成两份导出逻辑一份专门生成表格一份专门生成图表原因见第 8 节。7. 底层行为说明7.1 图表实际写入的是一个新 Sheet当前实现里图表工厂会workbook.createSheet(sheetName)把CATEGORIES SERIES先写到这个 sheet在这个 sheet 上创建 drawing / anchor / chart所以图表不是附着在已有业务表格的指定区域上TITLE同时也会被用作 sheetName 传入图表工厂若标题重复可能引发工作表重名问题7.2 GRAPH 会触发“禁用流式导出”图表导出需要回头访问 workbook 中已写入内容并创建图表锚点因此会触发needsRandomRowAccess(config)从而禁用 SXSSF 流式导出。这意味着即使全局开启了流式导出只要配置了GRAPH当前导出也会降级为XSSFWorkbook对程序员的含义是GRAPH 不适合超大数据量导出主链路。建议图表导出用于汇总结果页、统计页大批量明细数据导出与图表导出分离8. 使用边界与限制8.1 当前图表数据来源不是业务表格区域引用当前实现是先把 DSL 中的CATEGORIES、SERIES.DATA写到图表 sheet 中再基于写入后的区域创建图表这意味着当前不支持从已有 Excel 数据区域自动绑定图表直接引用业务 sheet 某一列作为图表数据源在同一个业务 sheet 指定任意位置插图表8.2 不适合复杂图表布局当前没有 DSL 字段可以控制图表显示位置图表大小多图排版图例位置数据标签颜色主题次坐标轴组合图柱线混合图所以这套 GRAPH 更适合快速生成标准报表图自动化导出中的基础统计展示而不适合高定制 BI 报表PPT 级视觉排版复杂 dashboard8.3TITLE建议唯一由于当前会把标题作为 sheetName 传入图表创建逻辑因此建议同一个 workbook 中每个图表标题保持唯一避免同名图表导致 sheetName 冲突不推荐TITLE 统计图推荐TITLE 2025年第一季度销售统计图9. 推荐规范9.1 DSL 编写规范建议统一风格EXPORT WITH GRAPH { TYPE COLUMN, TITLE 销售数据统计, CATEGORY_AXIS 产品, VALUE_AXIS 销量, CATEGORIES [产品A, 产品B, 产品C], SERIES [{ NAME 第一季度, DATA [120, 200, 150] }] }规范要求TYPE使用大写枚举值TITLE、CATEGORY_AXIS、VALUE_AXIS使用引号包裹CATEGORIES明确按展示顺序写入SERIES中DATA长度必须与CATEGORIES保持一致业务上没有意义时不要使用 3D 图9.2 业务建模规范在程序层建议先做图表 DTO再拼 DSL不要直接在 Controller 层硬编码字符串。推荐模型classChartRequest{Stringtype;Stringtitle;StringcategoryAxis;StringvalueAxis;ListStringcategories;ListSeriesRequestseries;}classSeriesRequest{Stringname;ListNumberdata;}这样好处是便于参数校验便于单元测试便于后续扩展图表模板9.3 导出前校验规范在执行executor.execute(rule)前建议先做以下校验type非空且属于支持列表title非空categories非空series非空每个series.name非空每个series.data非空所有series.data.size()与categories.size()相同10. 常见错误清单错误 1分类数量和数据点数量不一致CATEGORIES [Q1, Q2, Q3], SERIES [{ NAME 产品A, DATA [120, 130] }]错误 2饼图传多组系列TYPE PIE, SERIES [{...}, {...}]虽然 DSL 可能可解析但业务上通常不合理。错误 3把 GRAPH 当成表格图表绑定器错误理解先导出表格再让 GRAPH 自动引用表格列生成图表。当前不是这个模式。错误 4大数据量场景仍强依赖 GRAPH图表会禁用流式导出不适合海量明细导出主流程。错误 5图表标题过于泛化TITLE 图表可能带来 sheetName 冲突也不利于后续维护。11. 推荐模板11.1 柱状图模板EXPORT WITH GRAPH { TYPE COLUMN, TITLE 年度销售统计, CATEGORY_AXIS 产品, VALUE_AXIS 销量, CATEGORIES [产品A, 产品B, 产品C, 产品D], SERIES [{ NAME 2025, DATA [120, 200, 150, 180] }] }11.2 折线图模板EXPORT WITH GRAPH { TYPE LINE, TITLE 月度访问趋势, CATEGORY_AXIS 月份, VALUE_AXIS 访问量, CATEGORIES [1月, 2月, 3月, 4月], SERIES [{ NAME 官网, DATA [1000, 1200, 1150, 1500] }, { NAME 小程序, DATA [800, 900, 980, 1300] }] }11.3 饼图模板EXPORT WITH GRAPH { TYPE PIE, TITLE 渠道占比, CATEGORIES [官网, 小程序, App, 线下], SERIES [{ NAME 占比, DATA [35, 25, 20, 20] }] }11.4 雷达图模板EXPORT WITH GRAPH { TYPE RADAR, TITLE 工程师能力评估, CATEGORIES [编码, 设计, 沟通, 测试, 学习], SERIES [{ NAME 张三, DATA [90, 85, 75, 80, 95] }, { NAME 李四, DATA [80, 88, 82, 78, 85] }] }12. 最佳实践总结推荐用COLUMN / BAR / LINE / PIE解决 80% 报表图需求导出前先做数据长度一致性校验图表导出和大批量明细导出分离保持TITLE唯一且可读在服务层先构建图表 DTO再拼 DSL不推荐在 Controller 直接手写复杂 GRAPH DSL在一个超大导出任务里混用 GRAPH依赖 GRAPH 自动绑定已有表格区域给PIE、RADAR配置不合理的多系列结构使用含义不明确的标题和类别值13. 一句话结论如果你站在程序员角度使用 JQuick-Excel 的图表能力最重要的认知是GRAPH 是一套“声明式图表数据模型”适合生成标准化统计图它不是 BI 画布也不是对已有表格区域的自动绑定器。因此最佳用法是先在业务层整理好 categories series再用 DSL 生成标准图表导出。