简介这份Jasper报表制作小技巧文档面向使用Jaspersoft进行报表开发的IT人员与数据分析从业者帮助解决报表结构理解不清、中文显示异常、分组与序号列配置繁琐等常见问题。资源包为1个docx文件大小约599KB内容以图文笔记形式整理便于随时查阅与对照实践。文档系统梳理了Title、Page Header、Column Header、Detail、Column Footer、Page Footer、Summary等七个基本Band的用途与显示位置并给出Json数据源接入、中文字段PDF打印设置、手工新增字段、明细分组、序号列添加、自定义纸张大小以及交叉报表Crosstab使用等实用技巧还涉及控件显示隐藏与打印配置思路。目前已有242人学习下载适合刚接触Jasper报表或希望提升报表制作效率的开发者参考可快速掌握报表结构要点与常见问题的处理方式。1. Jasper报表制作小技巧为什么你的第一版报表总是对不齐做过企业级报表的人大概都有过这种体验需求文档写得清清楚楚字段、分组、汇总逻辑全对可导出的 PDF 一打开列宽忽宽忽窄、数字右边缘参差不齐、中文字体莫名变成方块。这不是玄学是 JasperReports 的布局引擎在按它自己的规则办事而多数人第一次上手时根本没意识到这套规则的存在。Jasper报表制作小技巧这个方向说的不是某个冷门 API而是围绕 JasperReports 这套开源报表引擎把 jrxml 模板设计、数据源绑定、表达式计算、导出格式适配这几件事做扎实的实战经验。它解决的核心问题是让一份报表在预览、打印、导出 Excel 和 PDF 时表现一致而不是每换一个输出格式就翻一次车。适合谁适合已经能跑通一个 Hello World 报表、但被分页、分组、字体、子报表这些细节反复折磨的后端开发和报表工程师。下面按我实际踩过的顺序从模板结构讲到参数调优再到那些文档里不会明说的坑。2. jrxml 模板的骨架先搞懂 Band 的执行顺序再动手JasperReports 的模板文件 jrxml 本质上是一棵由若干 Band 组成的树每个 Band 在报表生成的不同阶段被触发。很多人拿到需求直接往 Detail 里堆字段结果页眉页脚错位、分组汇总算错根源就是没理清 Band 的触发时机。这一章先把骨架讲透再落到具体怎么写。2.1 六种 Band 的触发时机与典型用途一份标准 jrxml 里常见的 Band 有 Title、Page Header、Column Header、Detail、Column Footer、Page Footer、Summary加上 Group Header 和 Group Footer。它们的执行顺序不是从上到下简单排列而是按报表引擎的渲染流程走。Title 只在报表最开头出现一次适合放报表名称、打印时间、公司抬头这类全局信息。Page Header 和 Page Footer 每页都会重复页码、页眉线、每页固定说明放这里。Column Header 在多列布局时每列顶部重复单列报表里它和 Page Header 容易混淆实际项目中我一般只在需要横向分栏时才用。Detail 是数据行主体每一条记录触发一次。Group Header 和 Group Footer 围绕分组字段成对出现分组汇总必须写在 Group Footer 里写在 Detail 里会逐行计算结果完全不对。Summary 在报表末尾出现一次适合放总计。这里有个容易翻车的点Page Footer 里的页码变量$V{PAGE_NUMBER}在渲染过程中是动态的如果你在 Page Footer 里直接引用它做条件判断可能拿到的是上一页的值。常见做法是用$V{PAGE_NUMBER}配合evaluationTimeNow属性或者在 Summary 里用$V{PAGE_NUMBER}取总页数。2.2 一个可复用的最小模板结构下面这段 jrxml 是我在多个项目里反复用的骨架去掉了具体业务字段保留结构。你可以直接拿它当起点改。?xml version1.0 encodingUTF-8? jasperReport xmlnshttp://jasperreports.sourceforge.net/jasperreports xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd nameBaseReport pageWidth595 pageHeight842 columnWidth555 leftMargin20 rightMargin20 topMargin20 bottomMargin20 languagejava !-- 参数外部传入用于动态标题和条件过滤 -- parameter namereportTitle classjava.lang.String/ parameter namestartDate classjava.util.Date/ !-- 字段与数据源列名一一对应 -- field nameorderNo classjava.lang.String/ field nameamount classjava.math.BigDecimal/ field namedeptName classjava.lang.String/ !-- 变量分组汇总resetType 决定何时归零 -- variable namedeptTotal classjava.math.BigDecimal resetTypeGroup resetGroupdeptGroup calculationSum variableExpression![CDATA[$F{amount}]]/variableExpression /variable !-- 分组定义按部门分组 -- group namedeptGroup groupExpression![CDATA[$F{deptName}]]/groupExpression groupHeader band height24 textField reportElement x0 y0 width200 height20/ textElement fontWeightbold/ textFieldExpression![CDATA[$F{deptName}]]/textFieldExpression /textField /band /groupHeader groupFooter band height24 textField reportElement x400 y0 width100 height20/ textFieldExpression![CDATA[$V{deptTotal}]]/textFieldExpression /textField /band /groupFooter /group title band height40 textField reportElement x0 y0 width555 height30/ textElement fontSize16 fontWeightbold/ textFieldExpression![CDATA[$P{reportTitle}]]/textFieldExpression /textField /band /title pageHeader band height20 staticText reportElement x0 y0 width555 height18/ textElement textAlignmentRight fontSize9/ text![CDATA[打印时间]]/text /staticText /band /pageHeader detail band height20 textField reportElement x0 y0 width150 height18/ textFieldExpression![CDATA[$F{orderNo}]]/textFieldExpression /textField textField pattern#,##0.00 reportElement x150 y0 width100 height18/ textElement textAlignmentRight/ textFieldExpression![CDATA[$F{amount}]]/textFieldExpression /textField /band /detail summary band height30 textField reportElement x0 y0 width200 height24/ textElement fontWeightbold/ textFieldExpression![CDATA[总计 $V{deptTotal}]]/textFieldExpression /textField /band /summary /jasperReport这段模板的关键点在于变量deptTotal的resetTypeGroup和resetGroupdeptGroup。它告诉引擎每进入一个新的部门分组时这个变量归零重新累加。如果你把 resetType 写成 Report那它会在整个报表范围内累加分组小计就变成了全局累计这是新手最常见的错误之一。calculationSum表示求和其他可选值还有 Count、Average、Highest、Lowest、Variance 等。参数说明pageWidth和pageHeight单位是像素A4 纸在 72dpi 下大约是 595×842。columnWidth是实际内容区宽度等于 pageWidth 减去左右边距。languagejava表示表达式用 Java 语法如果团队用 Groovy 可以改成 groovy表达式里就能用更简洁的集合操作。2.3 编译与填充从 jrxml 到可导出文件的完整链路模板写好后不能直接导出需要经过编译和填充两步。编译是把 jrxml 转成二进制 .jasper 文件填充是把数据源和参数灌进去生成 JasperPrint 对象。下面是一段典型的 Java 调用代码。// 编译模板jrxml - jasper JasperCompileManager.compileReportToFile( src/main/resources/reports/BaseReport.jrxml, target/classes/reports/BaseReport.jasper ); // 准备参数 MapString, Object params new HashMap(); params.put(reportTitle, 2024年度部门费用明细); params.put(startDate, startDate); // 数据源这里用 JRBeanCollectionDataSource 包装 JavaBean 列表 ListOrderBean dataList orderService.queryOrders(startDate); JRBeanCollectionDataSource dataSource new JRBeanCollectionDataSource(dataList); // 填充生成 JasperPrint JasperPrint print JasperFillManager.fillReport( target/classes/reports/BaseReport.jasper, params, dataSource ); // 导出 PDF JasperExportManager.exportReportToPdfFile(print, output/report.pdf); // 导出 Excel JRXlsExporter xlsExporter new JRXlsExporter(); xlsExporter.setExporterInput(new SimpleExporterInput(print)); xlsExporter.setExporterOutput(new SimpleOutputStreamExporterOutput(output/report.xlsx)); SimpleXlsReportConfiguration xlsConfig new SimpleXlsReportConfiguration(); xlsConfig.setOnePagePerSheet(false); xlsConfig.setDetectCellType(true); xlsExporter.setConfiguration(xlsConfig); xlsExporter.exportReport();逻辑说明compileReportToFile只在模板变更时需要重新执行生产环境通常把编译放在构建阶段运行时直接加载 .jasper。fillReport的第三个参数是数据源除了 JRBeanCollectionDataSource还有 JRResultSetDataSourceJDBC ResultSet、JRMapCollectionDataSourceMap 列表等。导出 Excel 时setDetectCellType(true)让引擎自动识别数字和文本类型否则所有单元格都会变成文本格式Excel 里没法直接求和。参数方面setOnePagePerSheet(false)表示多个逻辑页放在同一个 sheet 里如果报表分页严格且希望每页一个 sheet改成 true。setDetectCellType开启后性能会略降数据量超过十万行时建议关掉并手动指定列类型。3. 表达式与参数让报表逻辑从硬编码里解放出来模板结构搭好后真正决定报表灵活性的就是表达式和参数。很多人把过滤条件、格式化逻辑全写死在 SQL 里结果每换一个查询条件就要改模板。这一章讲怎么用参数和表达式把逻辑外置以及几个高频表达式的写法。3.1 参数、字段、变量的区别与选用场景这三者在 jrxml 里长得像用途完全不同。字段field对应数据源的列每行数据取一次值不能跨行。变量variable是在报表生成过程中计算的值可以跨行累加、计数、求平均它的值随 Band 的推进而变化。参数parameter是外部传入的在报表填充前就确定整个报表生命周期内不变。选用原则很简单数据源里有的列用字段需要跨行计算的用变量需要外部控制的用参数。比如按日期范围过滤日期范围应该做成参数在 SQL 的 where 条件里引用而不是在模板里用表达式过滤。模板里做过滤会导致所有数据都被查出来再丢弃数据量大时性能灾难。参数在 SQL 里的引用方式是在 queryString 里用$P{paramName}注意不是$F{}。如果参数是集合类型用于 in 查询需要配合$X{IN, column, param}语法。parameter namedeptList classjava.util.List/ queryString ![CDATA[ SELECT order_no, amount, dept_name FROM orders WHERE dept_name IN ($X{IN, dept_name, deptList}) AND order_date $P{startDate} ]] /queryString$X{IN, dept_name, deptList}会被引擎展开成dept_name IN (?, ?, ?)并自动绑定集合元素避免了手动拼 SQL 的注入风险。这是 JasperReports 里少数几个能显著减少代码量的语法糖值得记住。3.2 数字与日期格式化的三个必调参数报表里数字和日期的显示格式靠的是 pattern 属性。这个属性写在 textField 上语法遵循 Java 的 DecimalFormat 和 SimpleDateFormat。数字千分位用pattern#,##0.00负数用括号表示用pattern#,##0.00;(#,##0.00)百分比用pattern#,##0.00%。日期格式patternyyyy-MM-dd带时分秒用patternyyyy-MM-dd HH:mm:ss。这些看起来简单但有两个坑一是 pattern 里的特殊字符需要转义比如想显示#本身要写成#二是 locale 会影响月份和星期的显示语言如果报表要输出中文月份需要在填充时传入REPORT_LOCALE参数为Locale.CHINA。// 设置报表区域影响日期和数字的本地化显示 params.put(JRParameter.REPORT_LOCALE, Locale.CHINA); // 设置时区避免跨时区服务器上日期偏移 params.put(JRParameter.REPORT_TIME_ZONE, TimeZone.getTimeZone(Asia/Shanghai));这两个参数在分布式部署时尤其重要。我遇到过服务器时区是 UTC、数据库存的是本地时间、报表导出后日期少一天的案例排查了半天才发现是时区没设。加上 REPORT_TIME_ZONE 之后问题消失。3.3 条件样式用 printWhenExpression 控制显示报表里经常有这种需求金额为负时显示红色库存为零时隐藏某一行某个字段为空时不显示标签。这些都用 printWhenExpression 和条件样式实现。printWhenExpression 写在 reportElement 里返回 Boolean为 false 时该元素不渲染。注意是不渲染而不是隐藏占位所以如果同一行有多个元素要保证它们的显示条件一致否则会出现错位。textField reportElement x150 y0 width100 height18 !-- 金额为负时才显示 -- printWhenExpression![CDATA[$F{amount} ! null $F{amount}.doubleValue() 0]]/printWhenExpression /reportElement textElement textAlignmentRight forecolor#CC0000/ textFieldExpression![CDATA[$F{amount}]]/textFieldExpression /textField条件样式则用conditionalStyle定义适合根据字段值动态改变背景色、字体等。它比 printWhenExpression 更适合做「同一元素在不同条件下不同外观」的场景。style nameamountStyle conditionalStyle conditionExpression![CDATA[$F{amount}.doubleValue() 0]]/conditionExpression style forecolor#CC0000 isBoldtrue/ /conditionalStyle /style定义好样式后在 textField 上引用styleamountStyle即可。条件样式的判断顺序是从上到下第一个匹配的条件生效所以要把最具体的条件放在前面。4. 子报表与分组复杂报表结构的组织方式单层 Detail 能应付的报表有限实际项目里更多是主从结构、多层分组、跨页汇总。这一章讲子报表的传参机制和分组嵌套的注意事项这两个是复杂报表里最容易出问题的地方。4.1 子报表的数据源传递与参数映射子报表的本质是一个独立的 jrxml被主报表在某个 Band 里调用。它有自己的数据源和参数需要显式传递。常见做法是在主报表的 Detail 或 Group Header 里放一个 subreport 元素用 dataSourceExpression 指定子报表的数据源。subreport reportElement x0 y0 width555 height20/ subreportParameter namesubTitle subreportParameterExpression![CDATA[$F{deptName} 明细]]/subreportParameterExpression /subreportParameter dataSourceExpression ![CDATA[new net.sf.jasperreports.engine.data.JRBeanCollectionDataSource( $P{detailService}.queryByDept($F{deptName}))]] /dataSourceExpression subreportExpression ![CDATA[target/classes/reports/DeptDetail.jasper]] /subreportExpression /subreport这里的关键是 dataSourceExpression 里可以调用 Java 方法。$P{detailService}是一个传入的服务对象参数通过它按部门查子数据。这种写法把数据查询逻辑放在了表达式里灵活但要注意性能如果主报表有 1000 行子报表查询会被调用 1000 次数据库压力很大。优化方式是在主报表填充前一次性查好所有子数据用 Map 缓存子报表从 Map 里取。子报表参数用subreportParameter传递主报表的参数和字段都可以传过去。注意子报表里要用$P{subTitle}接收而不是$F{}。如果子报表需要用到主报表的某个字段值做过滤必须通过参数传子报表无法直接访问主报表的字段。4.2 多层分组嵌套时 resetGroup 的依赖顺序多层分组是报表里最常见的复杂结构比如「部门 → 项目 → 订单」三级分组。每级分组都有自己的 Header 和 Footer变量在不同层级归零。这里最容易翻车的是 resetGroup 的依赖顺序。假设有三个变量订单级小计、项目级小计、部门级总计。订单级变量 resetType 是 None不归零逐行累加项目级变量 resetType 是 Group、resetGroup 是项目分组部门级变量 resetType 是 Group、resetGroup 是部门分组。引擎在渲染时会按分组从内到外的顺序触发 reset如果依赖顺序写反了比如项目级变量依赖了部门分组那它会在部门切换时才归零项目小计就变成了部门累计。判断方法很简单变量的 resetGroup 必须是它所在层级或更内层的分组。项目级变量的 resetGroup 只能是项目分组或订单分组不能是部门分组。这个规则在 jrxml 里没有强制校验写错了不报错但结果不对只能靠人工检查。4.3 分组内排序与去重的实现分组默认按 groupExpression 的值排序但有时候需要按另一个字段排序而按当前字段分组。比如按订单日期排序、按客户分组。这时候要用sortField显式指定排序。sortField nameorderDate orderAscending/ sortField namecustomerName orderAscending/sortField 的 name 必须是字段名order 可选 Ascending 或 Descending。多个 sortField 按声明顺序依次排序先按第一个排第一个相同再按第二个排。注意 sortField 会影响整个数据集的行顺序分组表达式依赖这个顺序所以 sortField 里必须包含分组字段否则分组会错乱。去重则用变量配合calculationCount和resetTypeReport在 Group Header 里判断该分组是否首次出现。更简单的做法是在 SQL 里用 distinct把去重交给数据库。模板层做去重性能差且容易出错不推荐。5. 避坑与排查那些文档里不会写的翻车现场这一章记录几个我在实际项目里踩过的坑每个都按现象、原因、解决三步写。这些问题的共同点是不报错、不崩溃但结果就是不对排查起来很费时间。5.1 中文导出 PDF 变成方块或乱码现象预览时中文正常导出 PDF 后所有中文变成方块或问号。原因JasperReports 导出 PDF 时默认使用的字体不包含中文字形。预览用的是系统字体导出时用的是内置的 SansSerif 等字体这些字体没有中文字符。解决在 jrxml 里显式指定一个支持中文的字体并把字体文件打包进项目。常见做法是用 iText 的字体扩展在填充前注册字体。// 注册中文字体字体文件放在 resources/fonts 下 InputStream fontStream getClass().getResourceAsStream(/fonts/simsun.ttf); JasperReportsContext context DefaultJasperReportsContext.getInstance(); SimpleFontExtensionsRegistryFactory factory new SimpleFontExtensionsRegistryFactory(); // 实际项目中通常用 font extension jar 或 XML 配置更省事的方式是用 JasperReports 的 font extension 机制把 ttf 文件和一个 fonts.xml 打包成 jar放在 classpath 下jrxml 里直接引用字体名。这样不用改代码换字体也方便。注意字体文件有版权商用项目要确认授权。5.2 大数据量导出内存溢出现象小数据量导出正常数据超过几万行时抛 OutOfMemoryError。原因默认填充模式会把整个 JasperPrint 对象放在内存里数据量大时内存扛不住。解决开启虚拟化让引擎把中间结果写到磁盘临时文件。// 开启虚拟化超过阈值的数据写到磁盘 params.put(JRParameter.IS_IGNORE_PAGINATION, Boolean.FALSE); JasperFillManager.fillReportToFile( jasperPath, params, dataSource, tempFile );fillReportToFile会把填充结果直接写到文件避免内存中保留完整对象。另外导出 Excel 时如果不需要复杂样式用JRXlsExporter的流式模式边读边写。数据量特别大时考虑在 SQL 层分页分批生成多个文件再合并。5.3 分页时 Group Header 重复出现现象一个分组的内容跨页时第二页开头又出现了一次 Group Header。原因Group Header 默认在每页重复这是isReprintHeaderOnEachPage属性的默认行为。如果分组内容跨页第二页会重新打印 Header。解决在 group 定义里设置isReprintHeaderOnEachPagefalse或者设置isResetPageNumber控制页码。如果希望跨页时 Header 重复但只显示一次汇总把汇总放在 Group Footer 里Footer 只在分组结束时出现一次。group namedeptGroup isReprintHeaderOnEachPagefalse isResetPageNumberfalse这个属性在 jrxml 的 schema 里是 group 元素的属性不是 band 的。改的时候注意位置写错地方不生效。5.4 导出 Excel 时数字变成文本现象PDF 里数字正常导出 Excel 后数字列左上角有绿色三角无法求和。原因Excel 导出器默认把所有单元格当文本处理除非开启类型检测。解决设置setDetectCellType(true)或者在 jrxml 里给 textField 显式指定pattern导出器会根据 pattern 推断类型。更可靠的做法是在 Excel 配置里指定列类型。SimpleXlsReportConfiguration config new SimpleXlsReportConfiguration(); config.setDetectCellType(true); config.setWhitePageBackground(false); config.setRemoveEmptySpaceBetweenRows(true); // 指定特定列的格式 config.setCellTypeMapping(new HashMap());setRemoveEmptySpaceBetweenRows(true)去掉空行导出的 Excel 更紧凑。setWhitePageBackground(false)去掉白色背景避免打印时浪费墨水。这两个配置在报表要直接打印时很有用。5.5 参数为 null 时表达式报空指针现象某个参数没传值时报表填充抛 NullPointerException堆栈指向某个表达式。原因表达式里直接对可能为 null 的参数做了方法调用比如$P{date}.getTime()。解决在表达式里做 null 判断用三元运算符或$P{date} null ? : $P{date}。对于日期格式化用new SimpleDateFormat(yyyy-MM-dd).format($P{date})之前先判断 null。更彻底的做法是在填充前给所有参数设默认值避免 null 传入模板。// 填充前统一处理 null 参数 params.putIfAbsent(startDate, new Date(0L)); params.putIfAbsent(deptList, Collections.emptyList());putIfAbsent只在 key 不存在时放入如果调用方传了 null 值它不会覆盖。所以更稳妥的是显式判断if (params.get(startDate) null) params.put(startDate, defaultDate);。这个习惯能省掉大量排查空指针的时间。6. 进阶技巧用样式模板和脚本let让报表可维护报表做多了会发现真正难的不是做出第一版而是三个月后需求变更时还能快速改。这一章讲两个让报表长期可维护的技巧样式模板化和脚本 let 的用法。6.1 把样式抽成独立模板文件多个报表共用一套配色和字体时把样式定义抽到一个独立的 jrxml 里其他报表通过template引用。这样改一次配色所有报表同步生效。!-- styles.jrxml -- jasperTemplate style nameheaderStyle fontSize12 isBoldtrue forecolor#333333 backcolor#EEEEEE/ style nameamountStyle pattern#,##0.00 hAlignRight/ style namewarningStyle forecolor#CC0000/ /jasperTemplate主报表里引用template![CDATA[classpath:/reports/styles.jrxml]]/template引用后直接用styleheaderStyle即可。注意 template 的路径要用 classpath 或文件路径编译时需要能访问到。样式模板里不能定义参数和字段只能是纯样式。6.2 用脚本 let 做复杂计算JasperReports 支持在变量表达式里用脚本语言做复杂计算比如 Groovy。开启方式是在 jasperReport 元素上设languagegroovy然后变量表达式里就能写多行脚本。// 变量表达式计算加权平均 $F{amount} ! null ? ($V{totalAmount}.doubleValue() $F{amount}.doubleValue()) / ($V{count}.doubleValue() 1) : 0Groovy 脚本里可以定义局部变量、循环、条件判断比 Java 表达式灵活。但要注意性能脚本在每行都会执行复杂脚本会拖慢填充速度。我的习惯是只在确实需要多行逻辑时用脚本简单计算还是用 Java 表达式。6.3 验证报表输出的三个检查点报表改完后怎么确认没改坏我一般做三个检查。第一用同一份测试数据分别导出 PDF 和 Excel对比关键字段的值是否一致特别是汇总数字。第二检查分页边界把数据量调到刚好跨页看 Group Header 和 Footer 是否重复或丢失。第三用空数据源跑一次确认不会因为 null 报错空报表的提示信息是否友好。这三个检查能覆盖大部分回归问题。如果项目有 CI可以把报表填充和导出写成单元测试每次提交自动跑。测试数据用固定的 JSON 或 CSV断言导出的 PDF 页数和关键文本。这样改模板时心里有底不用每次手动点一遍。说到底JasperReports 的坑大多不在 API 本身而在布局引擎的隐式规则和导出格式的差异上。我自己的习惯是每做一个新报表先把 Band 结构和变量 reset 规则在纸上画一遍确认无误再写 jrxml。这个习惯帮我省掉了大量返工。希望帮到你。本文还有配套的精品资源点击获取
