ARTICLE · 1360857
折线图数据改了,PDF 合计数没变:模板里那四个数是写死的
折线图数据改了,PDF 合计数没变:模板里那四个数是写死的标签jquick-pdf · Java PDF · 报表开发 · 折线图 · 经营分析 摘要集团财务部每月一页 A4 的经营分析材料,四张指标卡、一张双折线、一张季度表。用 jquick-pdf 做完之后我发现,最容易出错的不是画图,而是模板里那四个写死的合计数——图表数据和模板文本是两份数据源,靠人对齐。本文按依赖、配置、装配、渲染、落盘五站拆这条链路,并把两份数据源的核对过程写清楚。 
一、一页 A4 里的四张卡 集团财务部每月八号前要交一份经营分析材料:深蓝抬头、四张指标卡、一张双折线图、五行季度汇总表、四条结论,全部压在一页 A4 里,报给经营分析例会。 数据从财务核算系统出,格式固定,每月真正变的只有数字。这种版式不变、数据滚动的单据,正好适合模板加数据绑定的做法。Java 侧二十来行就够: ●●● JPdfConfig config = new JPdfConfig(); config.getLayoutConfig() .setFlexLayout(true); JQuickPdfFactory factory = new JQuickPdfFactory(config); factory.bind("svg", svg); byte[] bytes = factory .executeResource("report/biz/16_monthly_revenue.txt"); 骨架就这么点。但动手之前有三个问题得先想清楚,否则图照样出得来,只是出的是错图: 模板里那个 <svg> 标签,接的是一张图片,还是一段文本? 卡片上"全年营业收入 30,600"这个数,是谁算出来的? 同样是这份模板,为什么少一行配置,整页就从一页变两页? 三个问题对应三个坑。第二个最隐蔽,先说它。 二、那四个合计数是写死的 写这类报表时,人的默认认知大概是这样的:图表数据都是从 Java 传进去的,那卡片上的"全年营业收入 30,600"当然也是程序累加出来的。毕竟没人会把合计数硬编码吧。 是写死的。 打开 report/biz/16_monthly_revenue.txt,四张卡那一段长这样: ●●● <!-- 指标卡:数字是字面量 --> <div style="width:136px;background:#EAF1F8"> <p>'30,600'</p> <p>'全年营业收入(万元)'</p> </div> 30,600、4,321、+18.6%、3,460 全是字面量。整份模板里唯一的动态位置,只有图表那一段的 ${svg}。季度表的五行、结论里的具体数字,同样是写死的。 也就是说这份 PDF 有两份数据源: 数据源一 · 图表 Java 里的两个 JLine 数组,有类型检查兜着。 数据源二 · 模板 四张卡、季度表、结论里的数字,全是模板文本,没有任何校验。 两边没有任何校验关系。少改一处,PDF 一样能生成、一样能打开、一样不报错,只是同一页上两个数字互相打脸。 这不是某个库的问题,是"Java 传数据加模板排版"这条路本身的性质。接受它,然后想办法管住它。 三、五站链路,写业务的只有一站 先把"数据经过谁"画成一条线:Maven 坐标把类拉进来 → JPdfConfig 定运行期行为 → JOption 装图表 → 渲染器吐出 SVG 字符串 → 工厂执行模板、交回字节数组。 五站里真正写业务的只有第三站,其余四站全是接线。但接错任何一处,第三站写得再漂亮也没用。 第一站 · 依赖入口 坐标 io.github.paohaijiao:jquick-pdfx:4.7.0+,Apache-2.0。两个入口:JChartRendererFactory 纯静态、不持有状态;JQuickPdfFactory 有状态,构造时吃一份 JPdfConfig。 第二站 · 配置对象 这份 Demo 只动了一行:setFlexLayout(true)。模板里有四处 display:flex——抬头左右栏、四卡横排、图表居中、页脚三联。不开它,四处一起退化成块级堆叠,指标卡竖排、页高翻倍、整份材料从一页变两页。 第三站 · 图表装配 JOption 是唯一装配点。标题走链式,单位"万元"写在副标里,是全图唯一交代量纲的地方,模板抬头也重复了一遍,改一处得改两处。 ●●● option.title().text("2024年月度营收统计") .subtext("营业收入与净利润走势(万元)"); JCategoryAxis xAxis = new JCategoryAxis(); xAxis.data("1月", "2月", "3月", ...); option.yAxis(new JValueAxis()); option.series(revenue, profit); 这里有个不能错的地方:x 轴的 12 个标签必须和每条 JLine 的 12 个数值一一对齐。对不上时图照样出得来,只是月份和数据错位贴在一起,这种错比抛异常难查得多。 第四站 · SVG 渲染 一行 JChartRendererFactory.renderChart() 返回 String。这一步之后,图表已经和 Java 对象没关系了,就是一坨 SVG 文本。 第五站 · 模板执行与落盘 executeResource 收相对 classpath 的路径,返回 byte[],整份 PDF 一次给全,不是流式吐。 四、模板的三条隐性规则 链路讲完了,但有三个约束不在代码里,在模板和配置的夹缝里。它们不写进文档,只能靠踩。 规则一 · flex 必须显式打开 flex 在 PDF 排版里不是浏览器的默认行为。新建 config 时顺手带上这一行,比出问题再回头找省事。 规则二 · 占位符名不带 ${} bind("svg", svg) 第一个参数是裸的 svg,模板里写 ${svg}。两边大小写严格一致,SVG 和 svg 是两回事。 规则三 · 模板路径一字不差 对应 src/test/resources/report/biz/,前面不带斜杠。我漏写过 biz/ 这一层,跑起来直接失败。 三条规则有个共同点:全是"少一点就全崩"的开关,没有"差不多能用"的中间态。这也是模板类报表省心的地方——错了就报错,不像数据错位那样安静。 五、SVG 从对象到纸面 把第四站的产物往细里看,因为这里有两个判断,我当时都想错了。 其一,它是一段完整的 <svg> 树,不是 Base64。我一开始以为 String 里带的是图片编码,拆开看了才知道是标签树。所以模板里必须有一个 svg 容器接住它,而不是 img 标签: ●●● <div style="display:flex;justifyContent:center"> <svg style="width:700pt">${svg}</svg> </div> 外面套容器、里面塞内容,两层结构。写成 <img src="${svg}"> 就什么都不会显示。 其二,容器只声明宽度,不声明高度。图表按 700pt × 380pt 的横版比例设计,只给宽度、不给高度,宽度被页面收窄时高度会按原比例同步缩放,不会纵向拉伸变形。一旦补上一句 height,比例就锁死了,页面窄的时候图会被压扁。 还有一个操作层面的问题:中间不要做编码转换。这段文本里全是标签和坐标数字,来回转一次编码,中文月份标签就成了乱码。 六、改数据的联动清单 回到第二节那个靶。图表数据一改,模板里要跟着动的地方一共三类: 一 · 四张指标卡 全年营收 30,600、全年净利 4,321、同比 +18.6%、12 月单月 3,460。 二 · 季度表五行 5,720 / 7,150 / 8,040 / 9,690,净利 723 / 971 / 1,141 / 1,486,加四行净利率与合计行 14.1%。 三 · 结论里的具体数字 12 月的 3,460 和 538 两处。 第一版我是拿计算器逐项核的,核完才敢改。用代码更省事,12 个月各自累加,和卡上、表上、结论里的数字逐个比对: ●●● // ★ 核对:模板里的合计数必须等于数组累加 int[] revenue = {1860,1720,2140,2380, 2260,2510,2680,2540,...}; Arrays.stream(revenue).sum(); // 30600 累加结果:营收 30,600、净利 4,321,和卡上一致;四季度分组和 5,720 / 7,150 / 8,040 / 9,690 一致;净利率 4,321÷30,600 = 14.12%,合计行写 14.1%,对得上。 不核就改的后果很具体:PDF 上会出现"图上 12 月最高、卡里写 3,180"这种自相矛盾的硬伤,评审一眼就能看出来,而且解释不清——因为两个数都是你自己生成的。 还有两处容易搜漏的地方。这份模板里同一个语义有两种写法:底色,抬头和指标卡写 background,图表区写 backgroundColor;对齐,表格单元格写 textAlign,段落写 textAlignment。 改模板时别只搜一种关键词。搜漏了会以为自己改过,实际没生效,然后你在 PDF 上找半天。 Demo 那段写文件的代码没包 try-with-resources,异常路径上流不会关。我在自己项目里改成了这样: ●●● File dir = new File(path + "biz"); if (!dir.exists()) dir.mkdirs(); try (FileOutputStream out = new FileOutputStream(pdfPath)) { out.write(bytes); } 先建目录再开流,顺序不能反——FileOutputStream 不帮你建父目录,目录不存在直接抛 FileNotFoundException。 还有一个取舍要说清楚。两条线共用一根 Y 轴,量级差得远:营收 1,860 到 3,460,净利只有 232 到 538,后者峰值不过是前者的六分之一。画出来净利线会被压在画布底部一条窄带里,起伏看着很平。 这是这份 Demo 的选择:例会要看的是"两条线一起往上走"这个同步性,压扁反而让结论更干净。如果换成要精读净利的场合,我会拆成两张图,或者上双 Y 轴。选之前先想清楚读者要看的是趋势还是数值。 最后说顺序。config 在 new JQuickPdfFactory(config) 那一刻就交出去了,所以所有开关都得在 new 之前设完。这一条不是运行时约束,是注意力约束——顺序一反过来,注意力就跑到 bind 上了,LayoutConfig 那几行很容易漏。 另外两处是硬顺序:bind 必须在 executeResource 之前,建目录必须在 new FileOutputStream 之前。前者错了模板里的 ${svg} 取不到值,后者直接抛 FileNotFoundException。 七、收尾 整条链路回头看,技术难度不高,难的是记住数据有两个源头。图表那一半有类型检查兜着,模板那一半全靠人。把联动清单写进发布流程,比任何技巧都实用。 下期写《jquick-pdf 的 keepTogether 挡不住跨页断行:一页 A4 塞不下时的三种排法》,还是这份模板,讲页高失控之后怎么办。 需要这份模板和 Demo 源码的,公众号后台回复 016。 最后一个问题想听听同行的做法:改数据时你们是手改模板,还是把合计数也做成占位符从 Java 传进去?后者更稳,但模板会多出一堆 ${...},写和读都变慢。这个取舍我一直没定下来。 jquick-pdf 实战 Vol.16 项目地址:https://github.com/paohaijiao/jquick-pdf 官网示例:https://www.jquick.org/jquick-pdf/demo/16_monthly_revenue/
















































































