jquick-pdf 关系图实战:11 个节点、16 条连线,把部门成本流向钉进成本管控 PDF
摘要(meta description):集团财务共享中心要一张"成本从哪个科目出来、落到哪个部门、最后归进哪个会计科目"的图,桑基图最合适,可 jquick-pdf 里没有桑基渲染器。这篇记录用关系图(JChartType.RELATION)替代的整条集成路径:JGraph 上挂 11 个节点、16 条有向连线、3 个分类,坐标手写死避免力导向漂移,<svg> 只声明宽度交给页面等比缩放,最后由 executeResource 落成 PDF。附完整 Java 源码与模板(jquick-pdfx 4.7.0+,Apache-2.0)。
标签:jquick-pdf、Java PDF、报表开发、关系图
官网示例:
- FORMULAS 示例页:https://www.jquick.org/jquick-pdf/demo/28_cost_relation/
- github 地址:https://github.com/paohaijiao/jquick-pdf
真实渲染效果预览
以下为上述代码 + 模板真实运行生成的 PDF 首屏预览(由 jquick-pdf 渲染输出,非示意图):

一、先把集成的边界钉住:五个类,一条渲染入口
评审会上第一句话就是"这不叫桑基图"。确实不叫。源码类注释里写得很清楚:jquick-pdf 暂无桑基图渲染器,本 Demo 以关系图(节点 + 有向连线)替代桑基图表达成本流向,所以模板图注老老实实标注成"桑基图替代视图"。想清楚这一点,后面所有参数取舍才有依据——我要画的不是带宽度的流,而是"谁指向谁"。
整条链路上真正要用到的类只有五个,全部在 com.github.paohaijiao 下:JGraph 装整张图的节点、连线和分类,JNode 是一个圆点,JLink 是一条有向边,JCategory 是图例分类,JLayout 是布局枚举。渲染入口是静态方法 JChartRendererFactory.renderChart(JChartType.RELATION, option),返回的是一段 SVG 字符串,不是图片文件。这个返回类型决定了后半程怎么写:SVG 是文本,要靠 factory.bind("svg", svg) 挂到模板占位符上,而不是塞一张 BufferedImage 进去。
依赖只有一条 io.github.paohaijiao:jquick-pdfx,版本 4.7.0 起。
二、渲染管线按顺序过一遍,每一步都能单独验
五步摆开,出错时好定位断在哪一段。
第一步,JGsonOption option = new JGsonOption(),option.title("部门成本构成与流向关系图")。关系图走的是 option.series(graph),把 JGraph 当成一个 series 塞进去。
第二步,造 JGraph,起名 name("成本流向"),设布局 layout(JLayout.force),再链式给 force().repulsion(100),最后 draggable(true)。这三行是"图的骨架",下面再谈。
第三步,graph.setData(nodes)、graph.setLinks(links)、graph.setCategories(categories)。顺序无所谓,但三个集合必须齐全,缺 categories 图例就空了。
第四步,renderChart 出 SVG。
第五步,JPdfConfig config = new JPdfConfig(),config.getLayoutConfig().setFlexLayout(true)。这行的源码注释是"开启 flex 行布局,使模板中的 display:flex 生效(图表居中)"——模板里那个 display:flex; justifyContent:center 的包裹层,不加这行图会顶在左边。接着 bind("svg", svg)、executeResource("report/biz/28_cost_relation.txt") 取回 byte[],写进 FileOutputStream,落盘到 D:\test\biz\28_cost_relation.pdf。
executeResource 的参数是 classpath 相对路径,模板真实位置在 src/test/resources/report/biz/28_cost_relation.txt。按绝对路径传进不去——它不是文件系统 API,是资源加载。
三、力导向布局开了,为什么坐标还要手写
这是最容易被问住的一处:layout(JLayout.force) 明明开了力导向,代码里却又给每个节点 put("x", ...)、put("y", ...)。工具方法就三行:
private JNode position(JNode node, int x, int y) {
node.put("x", x);
node.put("y", y);
return node;
}
类注释给了答案:每个节点固定写入 x/y 坐标(取值 180~800),以避免力导向随机分布导致的重叠与布局漂移。翻译成业务语言——这张图是给成本管控专题会看的,评审关心"人工成本在最左、归集终点在最右",要是每次渲染力导向都把节点甩到别处,同一份报表两次打开长得不一样,评审第一反应是数据出问题了。
repulsion(100) 是斥力系数,作用在力导向计算上;节点坐标一旦写死,它对这个 Demo 的观感影响很小,但留着不算错——万一某个节点没写坐标,也不至于和邻居叠死。
(效果预览图 alt:左侧一列四个深色圆点标着人工成本、采购与外包成本、资产折旧与摊销、运营与能耗费用,中间一列四个圆点是研发中心、生产制造部、市场营销部、行政管理部,右侧三个圆点是主营业务成本、期间费用、研发资本化,连线一律从左往右。)
四、三列坐标是这么排出来的
11 个节点分三列,x 只有三个值:180、480、800。第一列 4 个一级成本中心,y 从 150 到 750,步长 200;第二列 4 个二级责任部门,y 完全相同;第三列 3 个归集终点,y 是 250、500、750。
第二列和第一列同 y,是为了让连线接近水平——评审扫图时视线不用上下跳,一眼能看出"人工成本这条线主要往哪几个部门散"。第三列故意错开,因为 4 个二级部门要汇到 3 个终点,如果 y 也一一对齐,交叉线会叠在中轴上糊成一团。
symbolSize 也不统一,按"分量感"给了六档:46、44、40、38、36、34。人工成本和采购与外包是 46,资产折旧、运营与能耗是 40;二级部门里研发中心和生产制造部 38,市场营销部 36,行政管理部 34;归集终点主营业务成本 44,是终点里最大的那个,期间费用 40,研发资本化 34。数字大小本身就是信息:体量大,点就大一圈。节点上二十个就该改成按金额算了,十来个手调最快。
有个边界要提一句:类注释写渲染器默认画布是 800pt × 600pt,第三列 x 正好取到 800。圆点以坐标为中心画,右列就压在画布右边界上。现在 symbolSize 最大 46,视觉上撑得住;哪天调到 60,右半圈就会被裁掉。
五、16 条连线,跟模板里的表逐条对得上
连线是纯字符串 ID 配对,new JLink("1", "5") 表示节点 1 指向节点 5,方向就是成本流向,没有权重参数——这也是它不能当桑基图用的根本原因,桑基的宽度即流量,关系图的线宽是固定的。
数一遍:一级到二级 11 条(人工成本 4 条打满全部二级部门,采购与外包 3 条,资产折旧 2 条,运营与能耗 2 条),二级到终点 5 条(研发中心指向主营业务成本和研发资本化,生产制造部指向主营业务成本,市场营销部与行政管理部指向期间费用)。11 + 5 = 16,和模板第二节表格里那行"流向连线 16 条"必须一致。
模板这张表是 2 列 × 4 组的对照卡写法,540px 宽,左格浅底 #F5F0EE 放标签、右格右对齐放数字,下面三行拆细项。它其实是给改代码的人核对用的——Java 里加一条 JLink,表里那个 16 要跟着改成 17,对不上报表就自相矛盾。
JCategory 三个,名称依次是"一级成本中心""二级责任部门""成本归集终点",与节点的 category(0/1/2) 对应。分类名只影响图例文本,但三个 name 要跟模板里"三、成本管控结论"的措辞统一,否则读者得自己翻译。
六、模板执行:svg 只给宽度,是把缩放交给版面
模板里图表那一块长这样:
<div style="display:flex; justifyContent:center">
<svg style="width:700pt">${svg}</svg>
</div>
只写 width:700pt,不写 height,是刻意的:关系图画布 800×600,宽高比 4:3,页面版心收窄时高度按比例跟着缩,不会把圆点压成椭圆。要是手写 height:600pt,窄版心下一页里就是一张被挤扁的图。
同一段模板里还有三处值得记:抬头是 borderBottom:2px solid #4E342E 的深棕细线加三栏 flex,配色跟图表主色一路;图注是 9 号灰斜体,把"桑基图替代视图"写进了正文;结尾用 <lineSeparator strokeColor="#DCE3EC"> 拉一条浅灰线,再三栏页脚放密级、生成时间、编制单位。
结论区用的是 <list style="list-style-type:none; padding-left:0"> 加四个 <li>,每条 backgroundColor:#F5F0EE 配 border-left:3px solid #4E342E。四条结论都能回溯到图上:人工成本打满四个二级部门、归集终点三元化、生产制造部单一出口、按 16 条流向核对口径。写结论我给自己定了条规矩——每条必须能在 11 个节点里指出对应的点,指不出来就删。
七、失败场景:三处容易踩的地方
第一处,输出目录。new File(path + "biz") 加 if (!dir.exists()) dir.mkdirs(),path 取自 JQuickConstant.path,最终落在 D:\test\biz\28_cost_relation.pdf。用 mkdirs 不用 mkdir,因为 D:\test 可能整个不存在。
第二处,流没关。FileOutputStream 是裸 new 的,写完 write(bytes) 再 close(),中间抛异常就漏了。测试用例跑完进程就退,问题不大;搬进生产我一般换成 try-with-resources,或者 Files.write(Paths.get(...), bytes) 一行解决。
第三处,渲染失败没有兜底。节点 ID 写错(比如 new JLink("1", "99") 指向不存在的节点)编译期不报错,出来是一张少线的图或者直接异常。我的做法是渲染完数一遍 SVG 里的连线元素,跟 links.size() 对上再往下走。
真要出问题,最可能的形态是图出来了但和表对不上,而不是报错。所以我固定按节点数、连线数、表格数字三段核对,对不上就不交付。
复现清单
- 依赖
io.github.paohaijiao:jquick-pdfx:4.7.0+(Apache-2.0 协议); JGsonOption设标题,JGraph起名并layout(JLayout.force),按需force().repulsion(100);- 建
JNode(id, 名称),用put("x"/"y")写死坐标、symbolSize定圆点直径、category归到 0/1/2; JLink(fromId, toId)逐条描述流向,条数要和模板表格里的数字一致;JCategory().name(...)三个分类按层级顺序加,graph.setData/setLinks/setCategories挂全;renderChart(JChartType.RELATION, option)取 SVG,setFlexLayout(true)后bind("svg", svg),executeResource("report/biz/28_cost_relation.txt")出 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.code.JLayout;
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 com.github.paohaijiao.json.JGsonOption;
import com.github.paohaijiao.series.JGraph;
import com.github.paohaijiao.series.force.JCategory;
import com.github.paohaijiao.series.force.JLink;
import com.github.paohaijiao.series.force.JNode;
import org.junit.Test;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
/**
* 业务场景 Demo 28:部门成本构成与流向图(集团成本管控)
*
* <p>业务场景:集团财务共享中心展示「一级成本中心 → 二级责任部门 → 成本归集终点」的成本构成与流向,
* 用于成本管控专题会定位成本增量的责任归属。</p>
* <p>实际图表类型:{@link JChartType#RELATION} 关系图。<b>说明:jquick-pdf 暂无桑基图渲染器,
* 本 Demo 以关系图(节点 + 有向连线)替代桑基图表达成本流向,故模板图注中标注为「桑基图替代视图」。</b></p>
*
* <p>模板:{@code report/biz/28_cost_relation.txt};关系图以 SVG 文本形式绑定到模板的 {@code ${svg}} 占位符,
* 输出到 {@code D:\test\biz\28_cost_relation.pdf}。</p>
*
* <p>图表尺寸说明:关系图按渲染器默认画布 800pt × 600pt(宽 × 高)绘制,共 11 个节点(三列:成本中心 / 责任部门 /
* 归集终点),每个节点固定写入 x/y 坐标(取值 180~800)以避免力导向随机分布导致的重叠与布局漂移;
* 模板中 {@code <svg>} 只声明宽度、不声明高度,宽度被页面自动收窄时高度按原比例同步缩放,不会纵向拉伸变形。</p>
*
* @author Martin
* @version 1.0.0
*/
public class JQuickBiz28CostRelationTest {
public static final String path = JQuickConstant.path;
@Test
public void biz28CostRelation() throws IOException {
JGsonOption option = new JGsonOption();
option.title("部门成本构成与流向关系图");
JGraph graph = new JGraph();
graph.name("成本流向");
graph.layout(JLayout.force);
graph.force().repulsion(100);
graph.draggable(true);
// 节点分三列:第一列一级成本中心、第二列二级责任部门、第三列成本归集终点
List<JNode> nodes = new ArrayList<>();
nodes.add(position(new JNode("1", "人工成本").symbolSize(46).category(0), 180, 150));
nodes.add(position(new JNode("2", "采购与外包成本").symbolSize(46).category(0), 180, 350));
nodes.add(position(new JNode("3", "资产折旧与摊销").symbolSize(40).category(0), 180, 550));
nodes.add(position(new JNode("4", "运营与能耗费用").symbolSize(40).category(0), 180, 750));
nodes.add(position(new JNode("5", "研发中心").symbolSize(38).category(1), 480, 150));
nodes.add(position(new JNode("6", "生产制造部").symbolSize(38).category(1), 480, 350));
nodes.add(position(new JNode("7", "市场营销部").symbolSize(36).category(1), 480, 550));
nodes.add(position(new JNode("8", "行政管理部").symbolSize(34).category(1), 480, 750));
nodes.add(position(new JNode("9", "主营业务成本").symbolSize(44).category(2), 800, 250));
nodes.add(position(new JNode("10", "期间费用").symbolSize(40).category(2), 800, 500));
nodes.add(position(new JNode("11", "研发资本化").symbolSize(34).category(2), 800, 750));
graph.setData(nodes);
// 成本流向连线:一级成本中心 → 二级责任部门 → 成本归集终点
List<JLink> links = new ArrayList<>();
links.add(new JLink("1", "5"));
links.add(new JLink("1", "6"));
links.add(new JLink("1", "7"));
links.add(new JLink("1", "8"));
links.add(new JLink("2", "5"));
links.add(new JLink("2", "6"));
links.add(new JLink("2", "8"));
links.add(new JLink("3", "6"));
links.add(new JLink("3", "9"));
links.add(new JLink("4", "6"));
links.add(new JLink("4", "8"));
links.add(new JLink("5", "9"));
links.add(new JLink("5", "11"));
links.add(new JLink("6", "9"));
links.add(new JLink("7", "10"));
links.add(new JLink("8", "10"));
graph.setLinks(links);
List<JCategory> categories = new ArrayList<>();
categories.add(new JCategory().name("一级成本中心"));
categories.add(new JCategory().name("二级责任部门"));
categories.add(new JCategory().name("成本归集终点"));
graph.setCategories(categories);
option.series(graph);
String svg = JChartRendererFactory.renderChart(JChartType.RELATION, option);
File dir = new File(path + "biz");
if (!dir.exists()) {
dir.mkdirs();
}
FileOutputStream fileOutputStream = new FileOutputStream(path + "biz/28_cost_relation.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/28_cost_relation.txt");
fileOutputStream.write(bytes);
fileOutputStream.close();
}
/**
* 为节点写入固定坐标(渲染器读取 node 的 x/y,缺省时随机分布)
*/
private JNode position(JNode node, int x, int y) {
node.put("x", x);
node.put("y", y);
return node;
}
}
<pdf>
<body>
<div style="borderBottom:2px solid #4E342E; paddingBottom:8px; marginBottom:12px; keepTogether:true">
<div style="display:flex; justifyContent:space-between">
<div style="width:150px">
<p style="color:#4E342E; fontSize:10; bold:true">'集团财务共享中心'</p>
</div>
<div style="width:250px; textAlignment:center">
<h1 style="color:#4E342E; fontSize:16; bold:true; textAlignment:center">'部门成本构成与流向'</h1>
</div>
<div style="width:150px; textAlignment:right">
<p style="color:#6c757d; fontSize:9">'2025年10月10日'</p>
</div>
</div>
</div>
<div style="marginBottom:12px">
<h2 style="color:#4E342E; fontSize:13; bold:true; marginBottom:6px">'一、成本构成与流向关系'</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 一级成本中心 → 二级责任部门 → 成本归集终点(桑基图替代视图:节点 + 有向连线;数据来源:成本管控平台)'</p>
</div>
<div style="marginBottom:12px">
<h2 style="color:#4E342E; fontSize:13; bold:true; marginBottom:6px">'二、节点与流向对照'</h2>
<table style="width:540px; fontSize:10">
<tr>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'一级成本中心'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'4 类'</td>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'成本归集终点'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'3 类'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'二级责任部门'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'4 个'</td>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'流向连线'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'16 条'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'人工成本流向部门'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'4 个'</td>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'采购与外包流向部门'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'3 个'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'资产折旧流向部门'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'2 个'</td>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'运营与能耗流向部门'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'2 个'</td>
</tr>
<tr>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'研发中心归集终点'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'2 个'</td>
<td style="width:150px; backgroundColor:#F5F0EE; padding:6px; border:1px solid #DCE3EC">'生产制造部归集终点'</td>
<td style="width:120px; padding:6px; textAlign:right; border:1px solid #DCE3EC">'1 个'</td>
</tr>
</table>
</div>
<div style="marginBottom:10px">
<h2 style="color:#4E342E; fontSize:13; bold:true; marginBottom:6px">'三、成本管控结论'</h2>
<list style="list-style-type:none; padding-left:0; fontSize:10">
<li style="marginBottom:6px; padding:8px; backgroundColor:#F5F0EE; border-left:3px solid #4E342E">
'人工成本覆盖面最广:由研发中心、生产制造部、市场营销部、行政管理部四个部门共同承担,是唯一流向全部二级部门的成本项。'
</li>
<li style="marginBottom:6px; padding:8px; backgroundColor:#F5F0EE; border-left:3px solid #4E342E">
'归集终点三元化:人力与采购类成本最终汇入主营业务成本,市场营销部与行政管理部汇入期间费用,研发中心另有一路指向研发资本化。'
</li>
<li style="marginBottom:6px; padding:8px; backgroundColor:#F5F0EE; border-left:3px solid #4E342E">
'生产制造部为单一终点出口:其全部成本仅流向主营业务成本,成本归属清晰,便于按产品线直接分摊。'
</li>
<li style="marginBottom:6px; padding:8px; backgroundColor:#F5F0EE; border-left:3px solid #4E342E">
'管控建议:按上图 16 条流向逐条核对成本归集口径,重点复核跨两个终点出口的研发中心成本分摊比例。'
</li>
</list>
</div>
<lineSeparator style="strokeColor:#DCE3EC"></lineSeparator>
<div style="display:flex; justifyContent:space-between; marginTop:8px">
<div style="width:180px">
<p style="color:#6c757d; fontSize:8">'密级:内部'</p>
</div>
<div style="width:200px; textAlignment:center">
<p style="color:#6c757d; fontSize:8; opacity:0.8">'生成时间:2025年10月10日'</p>
</div>
<div style="width:180px; textAlignment:right">
<p style="color:#6c757d; fontSize:8">'编制:财务共享中心'</p>
</div>
</div>
</body>
</pdf>