泡海椒头像
Java 生成月度营收 PDF:jquick-pdf 双折线加季度汇总表的完整调用链封面图

Java 生成月度营收 PDF:jquick-pdf 双折线加季度汇总表的完整调用链

jquick-pdf 月度营收报表实战:Java 生成带折线图的经营分析 PDF,我把调用链拆成五段

官网示例:

  • FORMULAS 示例页:https://www.jquick.org/jquick-pdf
  • github 地址:https://github.com/paohaijiao/jquick-pdf

摘要(meta description):集团财务部每月要出一份经营分析材料,四张指标卡、一张双折线图、一张季度汇总表,全部压在一页 A4 里。用 jquick-pdf 做这件事,代码只有二十来行,但链路上有五处衔接,接错一处就出不了图。本文按依赖入口、配置对象、图表装配、SVG 渲染、模板落盘的顺序拆这条管线,顺带核对模板里的合计数与图表数据是否自洽(jquick-pdfx 4.7.0+,Apache-2.0)。

标签:jquick-pdf、Java PDF、报表开发、折线图

真实渲染效果预览

以下为上述代码 + 模板真实运行生成的 PDF 首屏预览(由 jquick-pdf 渲染输出,非示意图):

在这里插入图片描述

这条链路一共五站,先把地图画出来

素材是 JQuickBiz16MonthlyRevenueTest,一个测试方法跑到尾,产物落在 D:\test\biz\16_monthly_revenue.pdf,模板取自 classpath 下的 report/biz/16_monthly_revenue.txt。成品是一份集团财务部报给经营分析例会的月度材料:深蓝抬头色块、四张 136px 指标卡、一张双折线图、五行的季度汇总表、四条结论,页脚三联。

我习惯先把"数据经过谁"画成一条线:Maven 坐标把类拉进来 → JPdfConfig 定运行期行为 → JOption 装图表 → 渲染器吐出 SVG 字符串 → 工厂执行模板、交回字节数组。五站里真正写业务的只有第三站,其余四站全是接线,但接错任何一处,第三站写得再漂亮也没用。(效果预览图 alt:jquick-pdf 生成的月度营收统计 PDF,深蓝抬头色块、四张浅蓝指标卡横排、下方双折线图与季度汇总表)

依赖进来之后,入口只剩一个工厂

坐标是 io.github.paohaijiao:jquick-pdfx:4.7.0+,Apache-2.0。类路径上有两个入口值得记住:JChartRendererFactory 是纯静态的图表渲染器,不持有状态;JQuickPdfFactory 是有状态的文档工厂,构造时吃一份 JPdfConfig,之后所有绑定和执行都挂在它身上。

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");

这段是我从 Demo 里摘出来的骨架。工厂只有一个,config 在构造时就交了出去,所以我把所有开关都放在 new 之前设完——顺序一反过来,注意力就跑到 bind 上了,LayoutConfig 那几行很容易漏。

配置对象里只动了一行

JPdfConfig 在这份 Demo 里的用法极简:new 出来,然后 getLayoutConfig().setFlexLayout(true),注释写得很直白——「开启 flex 行布局,使模板中的 display:flex 生效(图表居中)」。

这一行的分量比它看起来重。模板里有四处 display:flex:抬头里左右两栏的分布、四张指标卡横排、图表容器的居中、页脚三联的左右分布。不开这个开关,四处一起退化成块级堆叠——指标卡会一张一行竖着排下去,页高直接翻倍,图表贴左,整份材料从一页变两页。flex 在 PDF 排版里不是浏览器的默认行为,得显式打开,这是这份模板能成立的前提。

配置对象上别的地方我一个都没碰。字号、行距、页边距的默认值对这份 A4 材料够用,真要调,也应该在模板的 style 里调,而不是散在 Java 里。

图表配置:标题、提示框、两根轴、两条线

JOption 是图表的唯一装配点,这份 Demo 对它调了五次:

option.title().text("2024年月度营收统计").subtext("营业收入与净利润走势(单位:万元)");
option.tooltip().trigger(JTrigger.axis);
JCategoryAxis xAxis = new JCategoryAxis();
xAxis.data("1月", "2月", "3月", "4月", "5月", "6月", "7月", "8月", "9月", "10月", "11月", "12月");
option.xAxis(xAxis);
option.yAxis(new JValueAxis());
option.series(revenue, profit);

标题走的是链式写法,text 是主标、subtext 是副标,单位"万元"写在副标里——这是全图唯一交代量纲的地方,模板抬头也重复了一遍,两处口径要一致。

trigger(JTrigger.axis) 是沿袭 Web 图表的配置习惯。静态 PDF 里没有悬停这回事,我的判断是这行留着只为保持配置结构完整,删掉不影响出图,但也没必要删。

两根轴:JCategoryAxis 收 12 个月份标签,JValueAxis 空构造让渲染器自己算范围。这里有个不能错的地方——x 轴的 12 个标签必须和每条 JLine 的 12 个数值一一对齐。对不上时图照样出得来,只是月份和数据错位地贴在一起,这种错比抛异常难查得多。

两条线的数据是这样的:

JLine revenue = new JLine();
revenue.name("营业收入").data(1860, 1720, 2140, 2380, 2260, 2510, 2680, 2540, 2820, 3050, 3180, 3460);
JLine profit = new JLine();
profit.name("净利润").data(232, 205, 286, 322, 298, 351, 384, 342, 415, 462, 486, 538);

两条线共用一根 Y 轴,量级差得很远:营收在 1860 到 3460 之间,净利只有 232 到 538,后者的峰值不过是前者的六分之一。画出来净利线会被压在画布底部一条窄带里,起伏看着很平。这是这份 Demo 的取舍——例会要看的是"两条线一起往上走"这个同步性,压扁反而让结论更干净;如果换成要精读净利的场合,我会拆成两张图,或者上双 Y 轴。

渲染产物是一段字符串,不是文件

String svg = JChartRendererFactory.renderChart(JChartType.LINE, option);

一行,返回 String。这一步之后,图表已经和 Java 对象没关系了,就是一坨 SVG 文本。两个细节:枚举名是全大写 LINE,别按驼峰直觉写;渲染器是静态调用,不需要实例,也不需要提前初始化上下文。

我一开始以为这个 String 里带的是图片的 Base64,拆开看了才知道是完整的 <svg> 标签树——所以模板里必须有一个 <svg> 容器接住它,而不是 <img src>。这也解释了为什么模板那段写的是 <svg style="width:700pt">${svg}</svg>,外面套容器、里面塞内容,两层结构。

中间别做编码转换。这段文本里全是标签和坐标数字,来回转一次编码,中文标签就成乱码了。

模板执行与字节落盘

File dir = new File(path + "biz");
if (!dir.exists()) {
    dir.mkdirs();
}
FileOutputStream fileOutputStream = new FileOutputStream(path + "biz/16_monthly_revenue.pdf");

path 来自 JQuickConstant.path,Demo 里拼出来是 D:\test\biz\...。先建目录再开流,这个顺序不能反——FileOutputStream 不会帮你创建父目录,目录不存在直接抛 FileNotFoundException。

executeResource 收的是相对 classpath 的路径,前面不带斜杠,report/biz/16_monthly_revenue.txt 对应 src/test/resources/report/biz/ 下那个文件。它返回 byte[],整份 PDF 一次给全,不是流式吐。写入就用最朴素的 write 加 close。

Demo 里这个流没包 try-with-resources,异常路径上会漏关闭。我在自己项目里改成了 try (FileOutputStream out = ...) { out.write(bytes); },业务代码里这么写更稳。

模板里的数字,得和图表对得上

这份模板最容易被忽略的是四张指标卡:30,600、4,321、+18.6%、3,460。它们不在 Java 代码里,是硬编码在模板文本中的,也就是说——模板和图表是两份数据源,靠人对齐。

我拿计算器核了一遍。营收 12 个月加起来 1860+1720+…+3460 正好 30,600;净利 12 个月加起来 232+205+…+538 正好 4,321。季度表四行 5,720 / 7,150 / 8,040 / 9,690 加起来也是 30,600,净利 723 / 971 / 1,141 / 1,486 加起来 4,321,全年净利率 4,321÷30,600 等于 14.1%,和合计行一致。第四张卡的 3,460 就是 12 月单月营收,538 是 12 月净利,模板结论第三条也引用了这两个数。

核完这一遍我才敢改数据。做这类单据,图表数据一改,模板里好几处要跟着动:四张卡、季度表五行、结论里的具体数字。少改一处,PDF 上就会出现"图上 12 月最高、卡里写 3,180"这种自相矛盾的硬伤,评审一眼就能看出来。

模板的视觉结构也值得说两句。抬头色块里左栏 300px 放标题加副标、右栏 240px 右对齐放统计周期和编制单位,右栏带一根 borderLeft:1px solid #6E8FBF 的竖线做分隔。图表区不是裸放,外面包了一层 backgroundColor:#F7F9FC 加 borderTop:2px solid #2F5597 的容器,顶上那根 2px 蓝线把"图表区"和上面的指标卡切开,章节标题再带 underline:true,等于一个区域给了两道视觉入口。季度表的斑马纹用的也是 #F7F9FC,和图表区底色同值,整页的浅色只有一个色号。合计行反白成 #2F5597 深蓝,是整张表唯一的实底行,视线落到表尾会自动停住。

有个小坑:这份模板里底色出现了两种写法,抬头和指标卡写 background,图表区写 backgroundColor;表格单元格的对齐写 textAlign,段落的对齐写 textAlignment。改模板时别只搜一种关键词,搜漏了就会以为自己改过而实际没生效。

三处最容易断的地方

一处是模板路径。executeResource 的入参要和 resources 下的相对位置一字不差,我漏写过 biz/ 这一层,跑起来直接失败,不会给你一份空白 PDF 蒙混过去——这算好事,问题暴露得早。

二处是占位符名。factory.bind("svg", svg) 的第一个参数是名字,不带 ${},模板里写 ${svg}。两边大小写要一致,SVG 和 svg 是两回事。

三处是 flex。这份模板离开 setFlexLayout(true) 就是另一份版式,指标卡竖排、图表贴左、页高失控。新建 config 的时候顺手带上这一行,比出问题再回头找省事得多。

复现清单

  1. 依赖 io.github.paohaijiao:jquick-pdfx:4.7.0+(Apache-2.0 协议);
  2. new JOption(),链式设 title().text().subtext(),tooltip().trigger(JTrigger.axis);
  3. JCategoryAxis.data(...) 给 12 个月份,option.yAxis(new JValueAxis());
  4. 两个 JLine 分别 name() 加 data(),12 个数与 x 轴标签严格对齐,再 option.series(revenue, profit);
  5. JChartRendererFactory.renderChart(JChartType.LINE, option) 取回 SVG 字符串;
  6. JPdfConfig 先 setFlexLayout(true),再用它构造 JQuickPdfFactory;
  7. factory.bind("svg", svg) 必须在 executeResource("report/biz/16_monthly_revenue.txt") 之前;
  8. 建目录、写字节,验证 D:\test\biz\16_monthly_revenue.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.axis.JCategoryAxis;
import com.github.paohaijiao.axis.JValueAxis;
import com.github.paohaijiao.code.JTrigger;
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.series.JLine;
import org.junit.Test;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;

/**
 * 业务场景 Demo 16:月度营收统计表(企业运营)
 *
 * <p>业务场景:企业运营管理系统按月汇总营业收入与净利润,用于管理层月度经营例会。</p>
 * <p>实际图表类型:{@link JChartType#LINE} 折线图(多重折线,用于观察两项指标的月度走势)。</p>
 *
 * <p>模板:{@code report/biz/16_monthly_revenue.txt};图表以 SVG 文本形式绑定到模板的
 * {@code ${svg}} 占位符,输出到 {@code D:\test\biz\16_monthly_revenue.pdf}。</p>
 *
 * <p>图表尺寸说明:图表按 700pt × 380pt(宽 × 高)的横版比例设计;模板中 {@code <svg>}
 * 只声明宽度、不声明高度,因此宽度被页面自动收窄时高度会按原比例同步缩放,不会纵向拉伸变形。</p>
 *
 * @author Martin
 * @version 1.0.0
 */
public class JQuickBiz16MonthlyRevenueTest {

    public static final String path = JQuickConstant.path;

    @Test
    public void biz16MonthlyRevenue() throws IOException {
        JOption option = new JOption();
        option.title().text("2024年月度营收统计").subtext("营业收入与净利润走势(单位:万元)");
        option.tooltip().trigger(JTrigger.axis);
        JCategoryAxis xAxis = new JCategoryAxis();
        xAxis.data("1月", "2月", "3月", "4月", "5月", "6月", "7月", "8月", "9月", "10月", "11月", "12月");
        option.xAxis(xAxis);
        option.yAxis(new JValueAxis());
        // 两条折线分别表示营业收入与净利润,颜色沿用政务/企业系统低饱和主色
        JLine revenue = new JLine();
        revenue.name("营业收入").data(1860, 1720, 2140, 2380, 2260, 2510, 2680, 2540, 2820, 3050, 3180, 3460);
        JLine profit = new JLine();
        profit.name("净利润").data(232, 205, 286, 322, 298, 351, 384, 342, 415, 462, 486, 538);
        option.series(revenue, profit);

        String svg = JChartRendererFactory.renderChart(JChartType.LINE, option);

        File dir = new File(path + "biz");
        if (!dir.exists()) {
            dir.mkdirs();
        }
        FileOutputStream fileOutputStream = new FileOutputStream(path + "biz/16_monthly_revenue.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/16_monthly_revenue.txt");
        fileOutputStream.write(bytes);
        fileOutputStream.close();
    }
}
<pdf>
<body>
  <div style="background:#2F5597; padding:14px; borderRadius:4px; marginBottom:10px; keepTogether:true">
    <div style="display:flex; justifyContent:space-between">
      <div style="width:300px">
        <h1 style="color:white; fontSize:18; bold:true; marginBottom:4px">'月度营收统计'</h1>
        <p style="color:#C7D6EA; fontSize:9; characterSpacing:0.5pt">'营业收入与净利润走势(单位:万元)'</p>
      </div>
      <div style="width:240px; textAlignment:right; borderLeft:1px solid #6E8FBF; paddingLeft:10px">
        <p style="color:white; fontSize:9">'统计周期:2024年1月 - 2024年12月'</p>
        <p style="color:#C7D6EA; fontSize:9">'编制单位:集团财务部'</p>
        <p style="color:#C7D6EA; fontSize:9">'报送对象:经营分析例会'</p>
      </div>
    </div>
  </div>

  <div style="display:flex; justifyContent:space-between; marginBottom:12px; keepTogether:true">
    <div style="width:136px; minHeight:56px; background:#EAF1F8; borderRadius:4px; padding:8px; verticalAlignment:middle">
      <p style="color:#2F5597; fontSize:17; bold:true; textAlignment:center; marginBottom:2px">'30,600'</p>
      <p style="color:#5A6B7C; fontSize:9; textAlignment:center">'全年营业收入(万元)'</p>
    </div>
    <div style="width:136px; minHeight:56px; background:#EAF1F8; borderRadius:4px; padding:8px; verticalAlignment:middle">
      <p style="color:#2F5597; fontSize:17; bold:true; textAlignment:center; marginBottom:2px">'4,321'</p>
      <p style="color:#5A6B7C; fontSize:9; textAlignment:center">'全年净利润(万元)'</p>
    </div>
    <div style="width:136px; minHeight:56px; background:#EAF1F8; borderRadius:4px; padding:8px; verticalAlignment:middle">
      <p style="color:#1B5E20; fontSize:17; bold:true; textAlignment:center; marginBottom:2px">'+18.6%'</p>
      <p style="color:#5A6B7C; fontSize:9; textAlignment:center">'营收同比增幅'</p>
    </div>
    <div style="width:136px; minHeight:56px; background:#EAF1F8; borderRadius:4px; padding:8px; verticalAlignment:middle">
      <p style="color:#BF360C; fontSize:17; bold:true; textAlignment:center; marginBottom:2px">'3,460'</p>
      <p style="color:#5A6B7C; fontSize:9; textAlignment:center">'12月单月新高(万元)'</p>
    </div>
  </div>

  <div style="marginBottom:10px; padding:10px; backgroundColor:#F7F9FC; borderRadius:4px; borderTop:2px solid #2F5597">
    <h2 style="color:#2F5597; marginTop:0; marginBottom:6px; fontSize:13; bold:true; underline:true">'一、全年营收与利润走势'</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  2024年1-12月营业收入与净利润走势(数据来源:集团财务核算系统)'</p>
  </div>

  <div style="marginBottom:10px">
    <h2 style="color:#2F5597; marginBottom:6px; fontSize:13; bold:true">'二、季度营收汇总'</h2>
    <table style="width:560px; fontSize:10">
      <tr>
        <th style="backgroundColor:#2F5597; color:white; padding:6px; textAlign:center; border:1px solid #C7D6EA">'季度'</th>
        <th style="backgroundColor:#2F5597; color:white; padding:6px; textAlign:center; border:1px solid #C7D6EA">'营业收入(万元)'</th>
        <th style="backgroundColor:#2F5597; color:white; padding:6px; textAlign:center; border:1px solid #C7D6EA">'净利润(万元)'</th>
        <th style="backgroundColor:#2F5597; color:white; padding:6px; textAlign:center; border:1px solid #C7D6EA">'净利润率'</th>
      </tr>
      <tr>
        <td style="padding:5px; border:1px solid #DCE3EC">'第一季度'</td>
        <td style="padding:5px; textAlign:right; border:1px solid #DCE3EC">'5,720'</td>
        <td style="padding:5px; textAlign:right; border:1px solid #DCE3EC">'723'</td>
        <td style="padding:5px; textAlign:right; border:1px solid #DCE3EC">'12.6%'</td>
      </tr>
      <tr>
        <td style="padding:5px; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'第二季度'</td>
        <td style="padding:5px; textAlign:right; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'7,150'</td>
        <td style="padding:5px; textAlign:right; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'971'</td>
        <td style="padding:5px; textAlign:right; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'13.6%'</td>
      </tr>
      <tr>
        <td style="padding:5px; border:1px solid #DCE3EC">'第三季度'</td>
        <td style="padding:5px; textAlign:right; border:1px solid #DCE3EC">'8,040'</td>
        <td style="padding:5px; textAlign:right; border:1px solid #DCE3EC">'1,141'</td>
        <td style="padding:5px; textAlign:right; border:1px solid #DCE3EC">'14.2%'</td>
      </tr>
      <tr>
        <td style="padding:5px; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'第四季度'</td>
        <td style="padding:5px; textAlign:right; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'9,690'</td>
        <td style="padding:5px; textAlign:right; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'1,486'</td>
        <td style="padding:5px; textAlign:right; backgroundColor:#F7F9FC; border:1px solid #DCE3EC">'15.3%'</td>
      </tr>
      <tr>
        <td style="padding:6px; backgroundColor:#2F5597; color:white; bold:true; border:1px solid #2F5597">'全年合计'</td>
        <td style="padding:6px; textAlign:right; backgroundColor:#2F5597; color:white; bold:true; border:1px solid #2F5597">'30,600'</td>
        <td style="padding:6px; textAlign:right; backgroundColor:#2F5597; color:white; bold:true; border:1px solid #2F5597">'4,321'</td>
        <td style="padding:6px; textAlign:right; backgroundColor:#2F5597; color:white; bold:true; border:1px solid #2F5597">'14.1%'</td>
      </tr>
    </table>
  </div>

  <div style="marginBottom:10px">
    <h2 style="color:#2F5597; marginBottom:6px; fontSize:13; bold:true">'三、经营分析结论'</h2>
    <list style="listStyleType:disc; paddingLeft:16px; fontSize:10">
      <li style="marginBottom:6px"><span style="bold:true; color:#2F5597">'营收逐季走高:'</span>'四季度营收分别为 5,720 / 7,150 / 8,040 / 9,690 万元,环比增幅稳定在 12% 以上。'</li>
      <li style="marginBottom:6px"><span style="bold:true; color:#2F5597">'盈利质量改善:'</span>'净利润率由一季度 12.6% 提升至四季度 15.3%,全年 14.1%,成本管控成效显现。'</li>
      <li style="marginBottom:6px"><span style="bold:true; color:#2F5597">'12月创单月新高:'</span>'营业收入 3,460 万元、净利润 538 万元,为全年峰值,与年末集中交付确认收入有关。'</li>
      <li style="marginBottom:6px"><span style="bold:true; color:#2F5597">'建议:'</span>'关注一季度基数偏低问题,2025年可将部分交付节点前移以平滑季节性波动。'</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年1月8日'</p>
    </div>
    <div style="width:180px; textAlignment:right">
      <p style="color:#6c757d; fontSize:8">'批准人:财务总监'</p>
    </div>
  </div>
</body>
</pdf>

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/PaoHaiJiao/article/details/170404685

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--