29 金融报表开发jquick-pdf K 线图 PDF 可视化解决方案引入投研日报需要在一份可归档的 PDF 里同时呈现交易日、开高低收行情和风险说明。K 线图把四个价格压缩成一根蜡烛既能看清当日波动区间也能按时间顺序观察形态。本文基于静态行情数据生成 K 线 SVG 并嵌入 PDF不涉及实时刷新、指标叠加或交易接口。行情能力来自io.github.paohaijiao:jquick-pdf-svgJCandlestick承载蜡烛数据JKChartsRenderer负责渲染分类轴承载交易日、值轴承载价格尺度。依赖坐标与模板基础语法见入门篇《01 jquick-pdf 超详细入门教程》本文聚焦行情数据的字段约定与对齐问题。核心讲解选型依据K 线图是 OHLC开、高、低、收数据的专用表达实体表示开盘与收盘的差异上下影线表示当日最高与最低。它与折线图的分工在于信息密度——折线只给一个收盘价序列适合看长期趋势K 线保留当日波动区间适合看形态与振幅。选型判断要落在业务用途上收盘日报、投研归档、风险留痕适合 K 线需要展示月度均价走势时折线图更清晰。用于展示时K 线图不应被当作交易信号PDF 中必须附上免责声明明确数据仅用于报告展示。数据字段与顺序约定KCharTest已明确JCandlestick与JKChartsRenderer的调用方式以及示例中每个交易日四个数值的真实写法。字段顺序必须由接口层固定下来本文按业务惯例约定为开盘、最高、最低、收盘并在入图前统一校验最高价不小于开盘价与收盘价最低价不大于开盘价与收盘价。示例中四个数组的长度与分类轴的交易日数量一致任何调换字段位置的操作都会让图形语义整体错位因此建议在 DTO 中用明确的字段名open、high、low、close承载而不是依赖数组下标传递。交易日对齐与缺失交易日分类轴上的日期与 K 线数量必须严格一一对应。非交易日周末、法定节假日、停牌日在原始数据中不会出现记录如果聚合结果跳过了某一天而分类轴仍然按自然日连续生成图形就会整体错位。正确处理方式是分类轴直接由查询结果的交易日集合生成而不是由日期区间推算。停牌、新股上市首日等场景需要单独处理。停牌日是否补一根与前一日收盘价相同的蜡烛属于业务口径问题必须在报告说明中写明如果不补则保持断点让图形如实反映“当日无成交”。这两种策略都不应默认采用而应由业务确认后在聚合层固定。生成 SVG 与嵌入 PDF链路与其它图表相同renderer 把 SVG 写到磁盘读取文件得到字符串bind(svg, svg)注入上下文executeContent返回 PDF 字节。模板在图表之后紧跟免责声明段落这是金融类报表的固定要求pdfbodyh1投研日报/h1svg${svg}/svgp数据仅用于报告展示不构成投资建议。/p/body/pdf关键细节四元数据的开高低收顺序必须固定并写入接口约定任何跨模块传递都要带字段名。交易日缺失会导致轴与数据错位分类轴应来自真实交易日集合。浮点精度与复权口径必须在入图前处理。复权前后价格不可混用同一张图内只能是同一口径。K 线图不是实时行情PDF 中不能承诺刷新或盘中更新。异常价格应先拦截避免比例尺失真。例如把成交额误写成价格会让整张图的纵轴被拉到无意义的量级。空数据要显式处理输出“所选区间内无行情记录”的提示段落。输出文件应记录数据快照时间、来源与时区便于事后复现。报告权限与脱敏独立处理行情数据同样可能涉及授权范围。尺寸与分页方面K 线的可读性取决于单根蜡烛的宽度。区间点数越多蜡烛越窄形态越难辨认。日报场景通常展示二十到六十个交易日为宜更长区间建议按周或按月聚合或拆成多张图分页输出。嵌入 PDF 后要实测分页结果避免蜡烛图被切到下一页。实战说明下面程序输出当前目录的k-report.pdfimportcom.github.paohaijiao.JOption;importcom.github.paohaijiao.axis.JCategoryAxis;importcom.github.paohaijiao.axis.JValueAxis;importcom.github.paohaijiao.code.JTrigger;importcom.github.paohaijiao.config.JGraphConfig;importcom.github.paohaijiao.config.JPdfConfig;importcom.github.paohaijiao.data.JGraphContainer;importcom.github.paohaijiao.enums.JChartType;importcom.github.paohaijiao.executor.JQuickPdfFactory;importcom.github.paohaijiao.k.JKChartsRenderer;importcom.github.paohaijiao.series.JCandlestick;importjava.nio.file.Files;importjava.nio.file.Paths;importjava.nio.charset.StandardCharsets;publicclassKReportDemo{publicstaticvoidmain(String[]args)throwsException{JOptionoptionnewJOption();option.title().text(股票K线图);option.tooltip().trigger(JTrigger.axis);option.xAxis(newJCategoryAxis().data(01/01,01/02,01/03,01/04));option.yAxis(newJValueAxis());JCandlestickknewJCandlestick().name(股价).data(newObject[]{105.2,108.5,104.8,109.1},newObject[]{108.6,107.8,106.5,109.5},newObject[]{107.9,105.3,104.2,108.0},newObject[]{105.4,106.1,104.5,107.2});option.series(k);Stringtemplatepdfbodyh1投研日报/h1svg{svg}/svgp数据仅用于报告展示不构成投资建议。/p/body/pdf;JGraphContainergraphContainernewJGraphContainer();graphContainer.setType(JChartType.K);graphContainer.setOption(option);JGraphConfiggraphConfignewJGraphConfig();graphConfig.put(svg,graphContainer);JPdfConfigconfignewJPdfConfig();config.setGraphConfig(graphConfig);byte[]pdfnewJQuickPdfFactory(config).executeContent(template);Files.write(Paths.get(d://test//k-report.pdf),pdf);}}逐段说明先装配标题与触发方式JTrigger.axis是已验证的写法分类轴写入四个交易日标签值轴统一承载价格。JCandlestick的name作为系列标识data接收四个数值数组每个数组内部按交易日顺序排列转入生产前这四个数组的字段含义必须在接口注释或 DTO 中写明不能靠记忆。renderer 输出 SVG读回字符串后绑定变量svg模板用svg${svg}/svg嵌入并紧跟免责声明段落最后写盘。结果预期PDF 中出现标题“投研日报”、四根蜡烛及其影线以及免责声明文本。若图形只有一条水平线或蜡烛相互重叠到无法辨认通常是分类轴日期数量与数据量不一致应打印两个集合的长度核对。常见失败案例一是把open/high/low/close传成high/low/open/close图形看起来仍像蜡烛但形态整体错误二是分类轴按自然日生成而数据按交易日聚合导致日期与蜡烛错位三是未做复权口径统一长周期图上出现无法解释的跳空四是把免责声明省略金融类报告缺失说明会带来合规风险。性能与监控方面建议使用BigDecimal或统一行情精度做价格计算避免浮点误差在长序列中累积记录数据快照时间、来源与时区限制历史点数保存 SVG 便于问题复现。监控重点关注行情源可用性、交易日集合与图形点数是否一致以及渲染失败率。总结K 线图的正确性建立在两个约定上四元字段顺序固定分类轴来自真实交易日集合。适用边界是静态行情展示例如收盘日报、投研归档与风险留痕均线、成交量等扩展能力需要先在当前版本的源码或测试中确认本文不做假设实时能力也不在已验证范围内。常见误区是把非交易日的空缺当作零成交、在同一张图内混用复权口径、以及省略免责声明。版本基线jquick-pdfx 4.0.0、JDK 8更多示例见 GitHub 仓库。