jquick-pdf 生成多区域分组柱状图 PDF:JMultiBarChartData 全套 API 速查与实战
摘要(meta description):华东、华南、华北、西部四区域 1-6 月业绩分组柱状图,jquick-pdf 4.7.0+(Apache-2.0 协议)JMultiBarChartData 一套 setter 走完配置。开篇先列本篇全部 API 速查表,再逐条展开:BarData 三件套、内置色常量、轴标签与数值的对应关系,附完整 Java 源码与模板。
标签:jquick-pdf、Java PDF、报表开发、分组柱状图
官网示例:
真实渲染效果预览
以下为上述代码 + 模板真实运行生成的 PDF 首屏预览(由 jquick-pdf 渲染输出,非示意图):

本篇用到的 API 一览
半年度经营分析会要一张四区域月度业绩对比图,JQuickBiz26MultiMetricBarTest 用的 JChartType.MultipleBar 是 jquick-pdf 里配置项最像传统图表库的一个:数据、轴、系列全在一个 JMultiBarChartData 上配,不用像雷达图那样先搭坐标系。配置面广意味着要查的东西多,先把本篇会碰到的 API 全列出来,后面逐条展开,模板是 report/biz/26_multi_metric_bar.txt,SVG 绑到 ${svg} 占位符;Java 侧的 factory.bind("svg", svg) 把渲染出的 SVG 文本喂进去,再 executeResource 出字节流写文件,整条链路和输出 D:\test\biz\26_multi_metric_bar.pdf 一并交代。(效果预览图 alt:jquick-pdf 多区域业绩对比 PDF,蓝灰主题,1-6 月四区域分组柱状图居中,四区速览表与经营分析结论铺底)
| API | 所属类 | 本篇用法 |
|---|---|---|
setTitleText / setSubtitleText |
JMultiBarChartData | 图内主副标题 |
setXAxisLabels |
JMultiBarChartData | 传 1-6 月六个类目 |
setXAxisTitle / setYAxisTitle |
JMultiBarChartData | "月份" / "业绩(万元)" |
setBarDataList |
JMultiBarChartData | 挂四个系列 |
setLegendText / setBarColor / setValues |
BarData | 系列名 / 颜色 / 数值 |
COLOR_A / COLOR_B / COLOR_C |
JMultiBarChartRenderer | 前三个区域用内置色 |
option.setData(chartData) |
JOption | 数据类挂载 |
JChartType.MultipleBar |
渲染入口 | 分组柱状图类型 |
逐条展开一:标题与轴的三组 setter
JMultiBarChartData regionalData = new JMultiBarChartData();
regionalData.setTitleText("2024年上半年各区域业绩对比");
regionalData.setSubtitleText("华东、华南、华北、西部四区月度表现(单位:万元)");
regionalData.setXAxisLabels(Arrays.asList("1月", "2月", "3月", "4月", "5月", "6月"));
regionalData.setXAxisTitle("月份");
regionalData.setYAxisTitle("业绩(万元)");
标题副标题画进 SVG,和模板抬头那份文案是两套:抬头 h1 是"2024年上半年各区域业绩对比",图内标题同文但带副标题说明单位。setXAxisLabels 的六个字符串就是横轴类目,顺序即渲染顺序,和四个系列 setValues 数组的下标一一对应——它是纯展示的字符串列表,排序逻辑不参与其中,想换月份顺序直接改这行列表就行。轴标题这组 setter 我第一版漏了 setYAxisTitle,图能出但纵轴光秃秃的,评审问"这轴是万元还是元",补上才闭环。这张图按 700pt 宽的横版比例设计,模板 svg 只声明宽度不声明高度,宽度被收窄时等比缩放,这套 Demo 的通用约定。
逐条展开二:BarData 三件套与四个区域
JMultiBarChartData.BarData eastChina = new JMultiBarChartData.BarData();
eastChina.setLegendText("华东");
eastChina.setBarColor(JMultiBarChartRenderer.COLOR_A);
eastChina.setValues(Arrays.asList(120.5, 135.2, 148.0, 162.5, 175.3, 190.8));
每个系列一个 BarData,三件套齐活:setLegendText 是图例文字,setBarColor 是柱色,setValues 是六个数值对应六个月。四个系列的数值我把增长形态捋了一遍:华东 120.5、135.2、148.0、162.5、175.3、190.8,每月增量 15 万上下,匀速爬坡;华南 98.3 到 172.5,中段 3、4 月增量放大到 16.8;华北 85.6 到 148.2,是四区里增速最匀的一条;西部 52.4 到 108.5,基数最小但 5、6 月连续两位数增长。这些形态写到第三节结论里就是"华北增速最均衡""西部 5-6 月环比增速回升至 12% 以上"的出处——BarData 喂进去的数,最终要在结论里被引用,配数时就该想好哪些值要被点名。setBarColor 的取值是个选型点:前三个区域直接用渲染器常量 JMultiBarChartRenderer.COLOR_A、COLOR_B、COLOR_C,注意常量挂在 JMultiBarChartRenderer 上而不是数据类上,import 时别拿错类——西部用 new Color(62, 107, 157) 自配——这个色值就是模板主色 #3E6B9D 的 RGB 形式,柱色和标题、表头同源,整页蓝灰统一。四个系列最后一个调用收口:
regionalData.setBarDataList(Arrays.asList(eastChina, southChina, northChina, westChina));
系列顺序决定分组柱的从左到右排列,这个顺序只有传递者自己控制,图例与柱子的对应关系虽然不会错,但按数值规模从大到小排(华东、华南、华北、西部)读起来顺序感才顺,乱序传参图例的扫描动线就乱了。
逐条展开三:挂载与渲染的两行
JOption option = new JOption();
option.setData(regionalData);
String svg = JChartRendererFactory.renderChart(JChartType.MultipleBar, option);
数据类走 option.setData(),不像雷达图、树图各有专属的 Option 挂载点——分组柱状图这类"数据驱动"的图表入口是统一的 setData,我一开始照雷达图的习惯找 setBarOption,翻了一圈没有,才确认这条路走的是 setData。渲染类型 JChartType.MultipleBar 驼峰大小写混排,抄 Demo 别手滑写成全大写。
模板收尾没有分析表的变体可讲,但输出环节的两行值得提:File dir = new File(path + "biz") 先建目录再写文件,path 来自 JQuickConstant.path,拼出 D:\test\biz\26_multi_metric_bar.pdf。目录不存在时 FileOutputStream 直接抛异常,这几行 mkdirs 的防御写法我从这份 Demo 抄进了自己的工具类。
逐条展开四:模板里的速览表为什么放在图前面
多数 Demo 是图在前表在后,这份模板反过来:"一、四区域业绩速览"是张标签-数值对的小表,每行四格——左格浅蓝底 #EDF2F8 放标签(150px),右格放数值(120px 右对齐),四格总宽正好对齐 540px 的表格规格:华东上半年合计 932.3 与华东 6 月单月 190.8 同行并排,华南 815.7 / 172.5,华北 682.9 / 148.2,西部 478.2 / 108.5,最后一行加粗"四区上半年合计 2,909.1"与"最高单月(华东6月)190.8"。标签格统一垫色、数值格白底右对齐,这是"键值对表"的标准画法,比传统明细表少一列表头,信息密度却不低。先给结论数字再看月度柱状,是经营分析会材料的读法:领导先要合计,图表是证据。我照这个思路改过别的报表,把核心指标前置,反馈确实更好。
分节标题的处理也和别的 Demo 不同:h2 加 borderBottom:1px solid #3E6B9D; paddingBottom:3px; marginBottom:8px,标题底下一条与文字同宽的主色细线,没有背景色块——和抬头 borderBottom:1px solid #B9C2CC; paddingBottom:8px 的浅灰线一个路数,整份模板走的是"细线分节"的轻量骨架,一页排得下三节内容不显挤。抬头本身也是这套轻骨架的样本:没有深色实底块,17 号 #3E6B9D 蓝字大标题直接压在白底上,配一行 9 号灰字元信息"统计周期:2024年1月 - 6月 | 数据来源:集团经营分析平台 | 金额单位:万元"。我做对比版时给抬头套了深蓝底块,页面立刻重了一档,和"细线分节"的骨架不搭——抬头形态要跟分节形态同一个重量级,这份模板两头都选了轻的,一致性就出来了。图表区是 display:flex; justifyContent:center 居中容器装 700pt 宽的 SVG,图下 9 号斜体图注"图 1 1-6月四区域业绩分组对比(单位:万元;数据来源:集团经营分析平台)"。
第三节结论是 listType="ordered" 的有序列表五条:华东领跑占四区合计 32.0%、月均复合增长约 9.6%;华南累计 815.7 万元、与华东差距稳定在 9%-19% 区间未见收窄;华北增速最均衡;西部仅为华东的 51.3% 但 5-6 月环比增速回升至 12% 以上;建议把西部大客户专项资源投入前置,全年区域差距收窄 5 个百分点。页尾居中两行 8 号字压 borderTop:1px solid #dee2e6 细线,数据来源、生成时间 2025年7月8日、"内部资料 · 未经许可请勿外传"提示齐了。Java 侧照例 config.getLayoutConfig().setFlexLayout(true),源码注释说明是使模板中的 display:flex 生效(图表居中)。
复现清单
- 依赖
io.github.paohaijiao:jquick-pdfx:4.7.0+(Apache-2.0 协议); JMultiBarChartData配标题、副标题、setXAxisLabels六类目、双轴标题;- 每区域一个
BarData:setLegendText+setBarColor(优先用JMultiBarChartRenderer内置常量)+setValues,setBarDataList收口; option.setData()挂载,JChartType.MultipleBar渲染 SVG;JPdfConfig开setFlexLayout(true);- 模板速览表前置,分节标题用主色 borderBottom 细线,抬头保持轻量细线骨架;
- 输出验证
D:\test\biz\26_multi_metric_bar.pdf。
完整源码附录
/*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Copyright (c) [2025-2099] Martin (goudingcheng@gmail.com)
*/
package com.github.paohaijiao.biz.chart;
import com.github.paohaijiao.JOption;
import com.github.paohaijiao.combol.JMultiBarChartData;
import com.github.paohaijiao.combol.JMultiBarChartRenderer;
import com.github.paohaijiao.config.JPdfConfig;
import com.github.paohaijiao.demo.constant.JQuickConstant;
import com.github.paohaijiao.enums.JChartType;
import com.github.paohaijiao.executor.JQuickPdfFactory;
import com.github.paohaijiao.factory.JChartRendererFactory;
import org.junit.Test;
import java.awt.Color;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.Arrays;
/**
* 业务场景 Demo 26:多区域多指标对比分组柱状图(企业经营分析)
*
* <p>业务场景:企业运营部对比华东、华南、华北、西部四个区域 1-6 月的业绩完成情况,用于半年度经营分析会。</p>
* <p>实际图表类型:{@link JChartType#MultipleBar} 分组柱状图,横轴为月份、每个月份并列四根区域柱。</p>
*
* <p>模板:{@code report/biz/26_multi_metric_bar.txt};图表以 SVG 文本形式绑定到模板的
* {@code ${svg}} 占位符,输出到 {@code D:\test\biz\26_multi_metric_bar.pdf}。</p>
*
* <p>图表尺寸说明:图表按 700pt 宽的横版比例设计;模板中 {@code <svg>} 只声明宽度、不声明高度,
* 宽度被页面自动收窄时高度会按原比例同步缩放,不会纵向拉伸变形。</p>
*
* @author Martin
* @version 1.0.0
*/
public class JQuickBiz26MultiMetricBarTest {
public static final String path = JQuickConstant.path;
@Test
public void biz26MultiMetricBar() throws IOException {
JMultiBarChartData regionalData = new JMultiBarChartData();
regionalData.setTitleText("2024年上半年各区域业绩对比");
regionalData.setSubtitleText("华东、华南、华北、西部四区月度表现(单位:万元)");
regionalData.setXAxisLabels(Arrays.asList("1月", "2月", "3月", "4月", "5月", "6月"));
regionalData.setXAxisTitle("月份");
regionalData.setYAxisTitle("业绩(万元)");
// 华东区域
JMultiBarChartData.BarData eastChina = new JMultiBarChartData.BarData();
eastChina.setLegendText("华东");
eastChina.setBarColor(JMultiBarChartRenderer.COLOR_A);
eastChina.setValues(Arrays.asList(120.5, 135.2, 148.0, 162.5, 175.3, 190.8));
// 华南区域
JMultiBarChartData.BarData southChina = new JMultiBarChartData.BarData();
southChina.setLegendText("华南");
southChina.setBarColor(JMultiBarChartRenderer.COLOR_B);
southChina.setValues(Arrays.asList(98.3, 112.6, 128.4, 145.2, 158.7, 172.5));
// 华北区域
JMultiBarChartData.BarData northChina = new JMultiBarChartData.BarData();
northChina.setLegendText("华北");
northChina.setBarColor(JMultiBarChartRenderer.COLOR_C);
northChina.setValues(Arrays.asList(85.6, 92.3, 105.8, 118.4, 132.6, 148.2));
// 西部区域
JMultiBarChartData.BarData westChina = new JMultiBarChartData.BarData();
westChina.setLegendText("西部");
westChina.setBarColor(new Color(62, 107, 157));
westChina.setValues(Arrays.asList(52.4, 61.8, 73.5, 85.2, 96.8, 108.5));
regionalData.setBarDataList(Arrays.asList(eastChina, southChina, northChina, westChina));
JOption option = new JOption();
option.setData(regionalData);
String svg = JChartRendererFactory.renderChart(JChartType.MultipleBar, option);
File dir = new File(path + "biz");
if (!dir.exists()) {
dir.mkdirs();
}
FileOutputStream fileOutputStream = new FileOutputStream(path + "biz/26_multi_metric_bar.pdf");
JPdfConfig config = new JPdfConfig();
// 开启 flex 行布局,使模板中的 display:flex 生效(图表居中)
config.getLayoutConfig().setFlexLayout(true);
JQuickPdfFactory factory = new JQuickPdfFactory(config);
factory.bind("svg", svg);
byte[] bytes = factory.executeResource("report/biz/26_multi_metric_bar.txt");
fileOutputStream.write(bytes);
fileOutputStream.close();
}
}
<pdf>
<body>
<div style="marginBottom:10px; borderBottom:1px solid #B9C2CC; paddingBottom:8px; keepTogether:true">
<h1 style="color:#3E6B9D; fontSize:17; bold:true; marginBottom:3px">'2024年上半年各区域业绩对比'</h1>
<p style="color:#6c757d; fontSize:9">'统计周期:2024年1月 - 6月 | 数据来源:集团经营分析平台 | 金额单位:万元'</p>
</div>
<div style="marginBottom:12px">
<h2 style="color:#3E6B9D; fontSize:13; bold:true; borderBottom:1px solid #3E6B9D; paddingBottom:3px; marginBottom:8px">'一、四区域业绩速览'</h2>
<table style="width:540px; fontSize:10">
<tr>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'华东上半年合计'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'932.3'</td>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'华东6月单月'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'190.8'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'华南上半年合计'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'815.7'</td>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'华南6月单月'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'172.5'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'华北上半年合计'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'682.9'</td>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'华北6月单月'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'148.2'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'西部上半年合计'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'478.2'</td>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; border:1px solid #DCE3EC">'西部6月单月'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'108.5'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; bold:true; border:1px solid #DCE3EC">'四区上半年合计'</td>
<td style="width:120px; padding:6px; textAlign:right; bold:true; border:1px solid #DCE3EC">'2,909.1'</td>
<td style="width:150px; backgroundColor:#EDF2F8; padding:6px; bold:true; border:1px solid #DCE3EC">'最高单月(华东6月)'</td>
<td style="width:120px; padding:6px; textAlign:right; bold:true; border:1px solid #DCE3EC">'190.8'</td>
</tr>
</table>
</div>
<div style="marginBottom:12px">
<h2 style="color:#3E6B9D; fontSize:13; bold:true; borderBottom:1px solid #3E6B9D; paddingBottom:3px; marginBottom:8px">'二、月度分组柱状走势'</h2>
<div style="display:flex; justifyContent:center">
<svg style="width:700pt">${svg}</svg>
</div>
<p style="fontSize:9; color:#6c757d; italic:true; marginTop:6px">'图 1 1-6月四区域业绩分组对比(单位:万元;数据来源:集团经营分析平台)'</p>
</div>
<div style="marginBottom:10px">
<h2 style="color:#3E6B9D; fontSize:13; bold:true; borderBottom:1px solid #3E6B9D; paddingBottom:3px; marginBottom:8px">'三、经营分析结论'</h2>
<list style="paddingLeft:18px; fontSize:10" listType="ordered">
<li style="marginBottom:6px">'华东领跑:上半年累计 932.3 万元,占四区合计的 32.0%,1-6 月由 120.5 万元升至 190.8 万元,月均复合增长约 9.6%。'</li>
<li style="marginBottom:6px">'华南次之:累计 815.7 万元,6月单月 172.5 万元,与华东的差距稳定在 9%-19% 区间,未见明显收窄。'</li>
<li style="marginBottom:6px">'华北稳步上行:累计 682.9 万元,6月 148.2 万元,为四区中增速最均衡的区域。'</li>
<li style="marginBottom:6px">'西部基数偏低:累计 478.2 万元,仅为华东的 51.3%,但 5-6 月环比增速已回升至 12% 以上。'</li>
<li style="marginBottom:6px">'建议:下半年将西部大客户专项资源投入前置,力争全年区域差距收窄 5 个百分点。'</li>
</list>
</div>
<div style="textAlignment:center; marginTop:10px; paddingTop:10px; borderTop:1px solid #dee2e6; color:#6c757d; fontSize:8">
<p>'数据来源:集团经营分析平台 | 生成时间:2025年7月8日 | 单位:万元'</p>
<p>'内部资料 · 未经许可请勿外传'</p>
</div>
</body>
</pdf>