简介：这是一份面向使用 Jaspersoft Studio 进行报表开发的技术人员整理的实操技巧文档，适合已具备一定报表基础、希望提升制作效率与排错能力的中级开发者参考。内容围绕报表七大 Band 结构展开，逐一说明 Title、Page Header、Column Header、Detail、Column Footer、Page Footer 与 Summary 的显示位置和适用场景，并补充 Group Header、Group Footer、Last Page Footer 等扩展区域；同时覆盖 JSON 数据源接入、字段遗漏时手工补建、报表明细分组、序号列变量创建、自定义纸张尺寸，以及 PDF 中文标签乱码的全局样式写法与交叉报表字段类型调整等常见难点。资源包内为 1 个 docx 文档，约 599KB，便于随时查阅与二次整理。目前已有 242 人浏览学习，可作为日常报表开发中的速查手册与问题排查参考。

1. Jasper 报表制作小技巧：模板在预览里好好的，一上传就掉字

设计器里预览，中文字段清清楚楚；点导出 PDF，标签变成一片空白；再传进系统打开，连数字都没了。这是 Jasper 报表制作里最常见的失败情况，问题基本不出在拖控件上，而出在“设计器看到的”和“系统里跑出来的”不是同一个东西：Band 的显示时机没对齐、数据源字段和 SQL 对不上、PDF 字体没做全局配置，三件事任意一件没处理，都能让一张看着完美的模板在交付当天失效。下面按「结构 → 数据源 → 字体 → 版面 → 排错 → 上线」拆开讲，适合已经能画出表格、但一导出和上线就容易出问题的从业者。

2. 七个 Band 的版面契约：谁只出现一次，谁每页都来

Jasper 报表的版面并不靠拖坐标堆叠而成，它按 Band 的显示规则切分。把某个控件拖进哪个 Band，决定了它出现一次、每页出现还是每组出现。搞不清这套规则，就会出现“标题只在第一页有”“合计跑到中间页”“列名压在数据行上”这些看起来像 bug 的现象——它们其实都是设计好的行为被误用了。这一章把七个主 Band 加三个分组/收尾 Band 的触发时机、典型用途和设置位置过一遍，最后用一张对照表把常见需求映射到具体 Band，下次接需求先查表再动手。

2.1 一次性 Band 与重复 Band：Title、pageHeader、columnHeader、Detail

Title 段只在整个报表的第一页最上面显示。除第一页外，不管报表有多少页，Title Band 的内容都不会再出现——它的定位就是“报表标题”，不是“页眉”。不少模板把公司名、报表全称、打印日期一股脑塞进 Title，结果第二页开始光秃秃，误以为是渲染出错，其实是按契约干活。判断标准很简单：这段内容希望只出现一次，还是希望每页都有？只出现一次放 Title，每页都要放 pageHeader。

pageHeader 的显示规则稍微绕一点：它在每一页都会出现，位置在页面上部；第一页时，它显示在 Title Band 下面，从第二页起，它顶到页面最上端。页码、创建时间、创建人、打印人这类公共要素放这里最合适，因为它们本来就该每页重复。需要注意的是 pageHeader 的高度会直接挤占 Detail 的可用空间，做快递面单这种寸土寸金的版式时，这一块要压到 0。

columnHeader 放的是列名，不是列数据，这点原文特意强调过。它在每一页（或每个列组）顶部重复，作用是给下面的 Detail 行做字段标注。把列名直接写成一行 Static Text 扔在 Detail 里，第一页看着没问题，翻页之后就露馅了。Detail 则是真正的数据区，放需要重复出现的内容，比如一条销售记录占一行，一页能放多少行由 Band 高度和纸张高度共同决定。

2.2 收尾 Band：columnFooter、pageFooter、Summary、lastPageFooter 的分工

这四个 Band 都带“统计”属性，但统计的范围完全不同，混用是最容易出错的地方。columnFooter 是列级别的统计计算值或列说明，跟在 Detail 之后、按列对齐，适合放“本列合计”“本列均值”这类紧贴数据列的内容。pageFooter 在所在页面的最下端，即页脚，管的是页级统计，比如本页小计、本页行数，以及“第 X 页 / 共 Y 页”这种页码信息。

Summary 出现在整个报表最后一页的 Detail Band 之后，管的是全局合计。举个例子：50 条销售记录占用了 3 页，需要统计这 50 条的总金额，这个值放在 pageFooter 里只会统计到最后一页的数据，放在 columnFooter 里可能被列宽切碎，正确的落点就是 Summary。很多人把跨页合计写成 Detail 里的一个变量文本，翻页就错位，根因就是没分清“页级”和“报表级”。

lastPageFooter 是最后一页专用的页脚，内容会出现在报表最后一页的最后部分。一旦设置了它，最后一页的 pageFooter 位置会被它替换掉。典型用途是最后一页要放签收栏、签字盖章区、或者“本报表共 N 页，到此结束”的结束语，而前面几页仍然用普通页脚。

2.3 groupHeader 与 groupFooter：分组的边界在哪里

报表内容经常需要按某个属性划分显示和计算，比如希望以月份为单位，每组分开显示销售记录。这时就要定义一个组，groupHeader 放组说明或组标志——月份、店铺名、供应商名这类信息，groupFooter 放这一组的统计值或说明。组的价值不只是“分块显示”，它还是变量重置的边界：一个 Sum 变量如果把 resetType 设在组上，每进入新组就自动归零重新累加，这是手写文本永远做不到的。

创建组的入口在报表大纲里，右键报表名选 Create Group，选中分组字段即可。创建之后设计器会多出对应的 groupHeader 和 groupFooter 两个 Band，高度默认不为 0，不处理就会在报表里留下两条空白带。后面 2.4 节讲的分页分组做法，核心动作就是把这两个 Band 的高度压到 0 或者把内容重新分配。

2.4 自定义纸张：快递面单只保留 Detail 区的设置方法

快递面单、标签、小票这类输出，纸张尺寸往往不是 A4。做法是：新建完报表初始页面后，点击页面最边框外侧的空白部分，在 Report 属性区选择 Edit Page Format，在 Format 下拉里选 Custom，然后在下方 Units 里把单位切成 mm，再按实际面单量出来的宽高填进去。单位这一步千万别跳过，默认单位可能是 inch 或 pixel，填 100 进去出来就是 100 英寸，打印机直接走纸错乱。

面单版式的通行做法是只保留 Detail 区域，其他区域高度全部设为 0。原因在于面单上没有“页眉页脚”的概念，Title、pageHeader、columnHeader、columnFooter、pageFooter、Summary 只要有高度，就会把 Detail 往下推，最终打印位置整体偏移。把用不到的 Band 高度设 0 而不是删掉，是为了保留结构、后续改版时还能把内容放回去。

2.5 需求到 Band 的映射表

提示：Band 高度设 0 之后在设计器里看不见，但在大纲树里还在，改版时从大纲选中再改回数值即可，不要直接删除 Band。

3. 把 JSON 接成可预览的报表：字段兜底、序号变量与类型转换

以 JSON 作为常用数据源时，整条链路是有固定顺序的：添加数据源（主要供预览使用，没有数据源也能生成报表）、新建报表页、关联数据源、添加数据字段、添加并修改字段标签、属性设置、分组、预览、编译。顺序颠倒会带来一堆莫名其妙的空值问题，比如先拖控件再关联数据源，字段表达式里的路径就对不上。这一章按这条链路走一遍，重点讲三个最容易卡住的地方：字段漏了怎么补、序号列怎么做、交叉表要的 Integer 类型怎么改。

3.1 数据源与字段的创建顺序

先准备一份能代表最终结构的 JSON 样本，字段名和类型都按真实接口来，不要用a、b、c占位：

{ "receiptCode": "RK202401001", "shipFromName": "某供应商", "itemCode": "IT-0001", "totalQty": 120, "openQty": 20, "closedAt": "2024-01-18 10:22:31" }

在设计器里新建数据源，类型选 JSON，指向这个文件或填一个可访问的地址。接着新建报表页，在向导里关联刚建好的数据源，向导会把 JSON 的每个键解析成一个 field。这里有个细节：向导解析出来的类型是根据样本值推断的，totalQty: 120会被识别成 Integer，但如果样本里写成"120"，就会被识别成 String，后面做 Sum 统计会直接失效。所以样本文件里的值类型必须和真实数据一致，这是最容易留下隐患的一步。

关联完成后，把字段拖到 Detail 区，设计器会自动生成对应的 Text Field 和字段标签。标签默认是字段名，需要手工改成中文列名，改的时候在属性面板的 Text 属性里改，不要直接改字段的 Name——Name 是和数据源绑定的键，改了之后取不到值。字段标签和字段 Name 是两个概念，这一点在 3.2 节还会再强调一次。

3.2 漏字段兜底：fields 右键新增与 Name 对齐

JSON 数据源用久了总会遇到字段漏掉的情况：接口加了新字段，但报表模板是早前建的，向导解析时没有它。这时不用重建数据源，直接在左下角的报表大纲里右键 fields，选择新增字段，然后在属性面板里重命名 Name 和描述，并选择对应的字段类型。

关键约束只有一条：Name 必须与数据库查询字段保持一致，大小写也要一致。JSON 是大小写敏感的，totalQty和totalqty在两个世界里完全不是一回事。类型同样要对，日期字段选java.util.Date或java.sql.Timestamp，数量字段选java.lang.Integer，如果类型选错，预览时表现为空白或者null，而不是报错，排查起来很费时间。

字段补完之后，记得把新字段拖进 Detail 区并改中文标签，然后重新编译。设计器里的预览用的是编译后的.jasper文件，只改 jrxml 不编译，预览看到的还是旧结构，这个失败情况我在第 5 章会单独展开。

3.3 序号列：用 Variable 做自增，不要手写文本

明细里加序号列是高频需求，常见做法是利用报表大纲里的 Fx 函数区，右键选 Create Variable，建一个整型变量，然后在属性面板里设置名称、类型、初始值和表达式。对应的 jrxml 片段是这样：

<!-- 明细行序号：按页重置，每页从 1 开始 --> <variable name="ROW_NO" class="java.lang.Integer" resetType="Page"> <initialValueExpression><![CDATA[Integer.valueOf(0)]]></initialValueExpression> <variableExpression><![CDATA[$V{ROW_NO} + 1]]></variableExpression> </variable>

逐项说明：name是变量名，拖到 Detail 区时用$V{ROW_NO}引用；class必须是包装类型java.lang.Integer，写int会编译不过；resetType决定重置时机，Page表示每页从 1 重新开始，改成Report就是全表连续编号，改成组名则是每组重新计数；initialValueExpression给初值 0，配合variableExpression里的加 1，第一行输出就是 1；variableExpression里做的是“读自己、加一、写回”，这是 Jasper 变量的标准自增写法。

建好之后直接把变量拖到 Detail 区作为第一列显示，字号和对齐方式和其他列保持一致。这里有个常见误用：拿$V{PAGE_NUMBER}当行号。它是页码变量，一页里所有行拿到的值都一样，做出来就是“1、1、1、1”。行号必须自己建变量，页码才用内置的那个。

3.4 交叉表前置：把 String 改成 Integer

做交叉表（Crosstab）之前，有一个必须提前处理的类型问题。如果统计字段在 JSON 里读过来默认是 String，比如ReceiptCount或者TotalQty，那么在 Crosstab 向导里把 calculation 设成 Sum 之后，合计结果会不对，甚至整块空白。原因是 String 没有求和语义，聚合函数拿不到数值。

处理方式是在报表大纲里选中该字段，把类型改成java.lang.Integer，对应的 jrxml 是：

<!-- 参与 Crosstab 求和的字段，类型必须是数值型 --> <field name="totalQty" class="java.lang.Integer"> <fieldDescription><![CDATA[totalQty]]></fieldDescription> </field>

fieldDescription里写的是数据源中的键路径，class是目标类型。改完类型后要重新编译再进 Crosstab 向导，向导才会把它识别为可聚合字段。这一步的顺序不能反：先进向导再改类型，向导生成的聚合表达式仍然是按 String 处理的，得把 Crosstab 删掉重做。

3.5 分组分页的两种做法

报表明细分组有两种常见实现路径，效果接近但适用场景不同。

第一种，在报表大纲里右键报表名，选择 Create Group，选中分组字段。然后在右下角属性面板里找到 band properties，把 Height 设为 0，并勾选 Start New Column、Start New Page 前面的复选框。Height 归零是为了让分组带本身不占版面，勾选分页则是让同一组的明细归到同一页。注意 Height 要填数字 0，不是删掉这个 Band，删掉之后分组关系也跟着没了。

第二种，针对单个分组字段直接改 columnHeader：把 columnHeader 的 Height 设为 0，同时把 columnHeader 里原有的列名全部移到 groupHeader 中，分组字段在创建分组时已经选过，也可以一并放进来、必要时隐藏显示。这样做的实际效果类似“按店铺分页”——同店铺的明细归档在同一页，页首直接是列名，没有多余的空白带。

两种做法都要配合变量重置。组统计变量的 resetType 要设成组名，而不是 Page 或 Report，否则每组的合计会累加上一组的数据，最终数字越往后越大，这种错误在预览阶段很容易被忽略，因为前几页看着都对。

4. PDF 里的中文字段为什么消失：全局 pdfStyle 与四个参数

“预览有字、导出没字”是 Jasper 报表制作里最经典的一个问题，也是新手最容易怀疑自己操作有误的地方。这一章把它拆开：先讲清楚为什么屏幕渲染和 PDF 渲染是两套逻辑，再给出全局 style 的具体写法和四个参数的含义，最后说明单个标签的局部设置与排查顺序。

4.1 预览正常、导出掉字的成因

设计器里的预览走的是屏幕渲染，用的是操作系统已经装好的字体，中文标签能正常显示是理所当然的。PDF 导出走的是另一套字体子系统，它只认 PDF 规范里内置的标准字体，或者被显式嵌入的字体文件。中文不在 PDF 标准字体集合里，如果不指定 CJK 字体名和对应编码，导出时这些字符就没有可用的字形，结果就是空白或者方框。

原文里描述的现象很准确：不设置的话，在报表预览中可以显示，但上传到系统中字就没了。原因在于系统侧导出 PDF 时用的是服务端环境，服务端往往没有设计器机器上那套字体回退链，屏幕渲染那一层兜底彻底失效，问题就暴露出来了。所以字体配置不能靠“我这台机器上看着没问题”来判断，必须显式写进模板。

4.2 全局 style 的 XML 写法与参数说明

最省事的办法是在 jrxml 的源码界面里插入一个全局 style，让所有没有单独指定字体的元素都继承它：

<!-- 全局 PDF 字体样式：放在 jasperReport 根节点下，isDefault 让所有元素默认继承 --> <style name="pdfStyle" isDefault="true" pdfFontName="STSong-Light" pdfEncoding="UniGB-UCS2-H" isPdfEmbedded="true"/>

四个参数逐个解释：

isDefault="true"是这套配置能一次性解决问题的关键。如果只对某一个 Text Field 单独设字体，那么模板里几十个中文标签得挨个设一遍，漏一个就是一个空白块，而且后续新增字段时还得记得再设一次。设成默认样式之后，全局生效，新增字段自动继承，维护成本降到最低。

4.3 单个标签的 Advanced 面板设置与替换顺序

个别标签需要不同字体时——比如标题要用黑体、正文用宋体——可以单独设置。选中标签，在属性框里切到 Advanced 面板，找到 PDF Font name、PDF Encoding、Embedded 三项，分别填字体名、编码和是否嵌入。这和在源码里给单个元素写pdfFontName属性是等价的，只是图形化的入口更直观。

这里有个顺序问题值得说清楚：全局 style 和单标签设置冲突时，单标签的优先级更高。所以正确流程是先把全局 style 配好、导出验证一遍，确认所有中文都正常，再去逐个调整需要特殊字体的标签。反过来先调单个标签、最后加全局样式，很容易出现某个标签被之前的局部设置覆盖、看起来“全局样式没生效”的假象。

排查时按这个顺序走：先看 jrxml 源码里有没有pdfStyle且isDefault="true"；再看目标标签有没有被单独设成了别的字体或空值；然后核对pdfEncoding是不是UniGB-UCS2-H；最后确认导出 PDF 的那台机器上字体包是否就位。四步走完还没解决，基本可以判定问题不在字体，而在 5.1 节讲的编译缓存上。

5. 五个高频失败情况：从掉字到走纸偏移的排查顺序

前面几章讲的是“应该怎么配”，这一章讲“配完了还是不对怎么办”。下面五条都是从实际项目里攒出来的，每条按「现象 → 原因 → 解决」写，顺序大致按出现频率排。遇到问题时从上往下对照，多数情况能在前三步定位。

5.1 上传到系统后中文字段变空白

现象：设计器里预览、导出 PDF 都正常，模板上传到系统后，页面上所有中文标签消失，数字和英文还在。

原因：模板里只对个别标签设了字体，没有全局默认样式；或者加了全局样式但上传的是旧的编译产物。系统侧导出走的是服务端字体环境，缺一个标签就缺一块。

解决：在 jrxml 源码里补上pdfStyle且isDefault="true"，保存后重新编译，确认生成的.jasper时间戳是新的，再重新上传。上传后先别急着走完整流程，直接在系统里导一页 PDF 看中文是否完整，这一步能省掉后面大量返工。

5.2 预览有数据，系统里查不出记录

现象：设计器预览时明细行满满一屏，上传配置后在系统里查询，结果是空表或者只有表头。

原因：打印配置里的条件 JSON 和 SQL 里的命名参数对不上。field、id、name、type四个是必填项，field和id尽量保持一致；type决定 SQL 里这个参数按什么类型传，日期字段写成string，SQL 里又用日期比较，条件就永远不成立。

解决：把打印配置里的字段名和 SQL 里的:param逐个对照，重点查大小写和类型。日期、时间必须是date或datetime，入库单号、供应商名才是string。改完之后重新保存配置，再进查询界面验证。

5.3 分组之后每页只有一行，或者多出空白页

现象：设置了按店铺分组并勾了分页，结果每组第一页只有一行数据，后面跟着大片空白，或者每组之间多出一整页空白。

原因：分组 Band 的 Height 没有归零，groupHeader 自身占了一段高度，把 Detail 往下推；另一种情况是 columnHeader 还留着高度，而列名已经移到 groupHeader，等于两份列名各占一次空间。

解决：进属性面板把 groupHeader 的 Height 设为数字 0，勾选 Start New Page；如果用的是第二种做法，把 columnHeader 的 Height 也设为 0，确认列名只在 groupHeader 里出现一份。改完预览翻几页，看每组的分页位置是否正确。

5.4 Crosstab 明细显示不全，或者合计是空的

现象：交叉表拖进 Summary 区后，行列表头出来了，但明细数字挤在一起看不全，或者合计列一片空白。

原因：两个独立问题。显示不全是默认字体太大，深蓝色 Static Text 和明细字段都是默认字号，塞进交叉表格子里放不下；合计为空是统计字段类型还是 String，Sum 聚合拿不到数值。

解决：先回大纲把参与统计的字段类型改成java.lang.Integer，重新编译后再做 Crosstab；然后选中 Crosstab 中全部明细字段，把字体大小调到 6 号、对齐方式设为居中。最后把 Crosstab 拉大覆盖到整个界面，双击进去改深蓝色 Static Text 的上部、左部字段名，改成业务上看得懂的中文。

5.5 面单打印走纸偏移、内容被截断

现象：面单打印机打出来，内容整体偏左上或者偏下，右边和下边的条码被切掉一截。

原因：纸张格式设了 Custom 但单位没改成 mm，填进去的数值被当成英寸或像素；或者 Title、pageHeader、pageFooter 这些区域还留着默认高度，把 Detail 整体往下推了几毫米。

解决：点页面最边框外侧进入 Report 属性，Edit Page Format 里 Format 选 Custom、Units 选 mm，宽高按实际面单量出来的毫米数填；然后把除 Detail 以外的所有 Band 高度设为 0。打印机侧再把纸张规格设成和模板一致，两边对齐之后偏移就消失了。

6. 模板挂上菜单之前：打印配置 JSON、SQL 条件与三步验证

模板编译完之后还有一段路要走：上传、配置打印参数、挂到菜单上。这段流程在作业报表和管理报表上略有差别，前者结构固定，后者要支持用户自定义查询条件，差别全在条件 JSON 和 SQL 的参数绑定上。

6.1 打印配置里的条件 JSON 结构

作业报表的配置基本是模板化的，除了name之外其他字段几乎不用动。管理报表则要按查询需求补条件。以入库商品明细为例，用户要按起止日期、商品编码、供应商名查询，条件 JSON 大致是这样：

[ { "field": "", "id": "h1_basic", "name": "基本信息", "type": "h1" }, { "field": "beg", "id": "beg", "name": "起始日期", "type": "date" }, { "field": "end", "id": "end", "name": "结束日期", "type": "date" }, { "field": "itemCode", "id": "itemCode", "name": "商品编码", "type": "string" }, { "field": "code", "id": "code", "name": "入库单号", "type": "string" }, { "field": "shipFromName", "id": "shipFromName", "name": "供应商名", "type": "string" } ]

field、id、name、type四个是必填项，field和id尽量保持一致；type为h1的那一条是分组标题，不参与查询，只负责在界面上把条件分块。这个type必须和下一步 SQL 里用到的条件字段类型严格对应，日期填date、文本填string，填错不会报错，只会让查询条件静默失效。

6.2 SQL 里 :param 的写法与 IS NULL 兜底

条件定义好之后，SQL 里的参数名要和field一一对应，并且每一项都要加空值兜底，否则用户不填某个条件时整条查询会返回零行：

SELECT rh.closedAt, rd.receiptCode, rh.shipFromName, it.name, rd.totalQty, rd.openQty, (rd.totalQty - rd.openQty) AS redQty FROM RECEIPT_HEADER rh INNER JOIN RECEIPT_DETAIL rd ON rh.id = rd.receiptId INNER JOIN ITEM it ON rd.itemCode = it.code WHERE rh.leadingSts = 900 AND rh.trailingSts = 900 AND (rh.code = :code OR rh.code IS NULL) AND (rd.itemCode = :itemCode OR rd.itemCode IS NULL) AND (rh.shipFromName = :shipFromName OR rh.shipFromName IS NULL) AND (rh.closedAt >= :beg OR rh.closedAt IS NULL) AND (rh.closedAt <= :end OR rh.closedAt IS NULL) ORDER BY rh.closedAt DESC

每个条件都写成字段 = :参数 OR 字段 IS NULL的形式，含义是“参数没传时这一条恒真，不参与过滤”。少了这个兜底，只要用户漏填一个条件，整个 WHERE 链就断了。

6.3 上线前的三步验证

模板上传完成后，在开发菜单里找到报表对应的界面类型和界面名称，在 View JSON 里打开加载项，在打印区域添加对应作业报表，文档名称对应模板名称、id 对应打印配置里的代码名，点更新。这一步只适用于一般作业报表；管理报表直接在报表查询里双击预览，选好自定义期间和其他字段，点 PDF 下载验证。

我自己的验证习惯固定为三步：先在设计器里导出一次 PDF，确认中文不掉字；再在系统里跑一次不带任何条件的查询，确认基础数据能出来；最后带上起止日期和编码跑一次，确认参数绑定生效。从那以后我每次改完模板，都强制走一遍「源码加全局 style → 重新编译 → 导出 PDF 看中文 → 系统里带条件查一次」这四步，再没在交付现场翻过车。希望帮到你。

本文还有配套的精品资源，点击获取