JasperReports怎么用？

wen python案例 2026-07-22 1

本文目录导读：

JasperReports怎么用？

核心工作流程（三步走）
第一步：环境搭建
第二步：设计报表模板（.jrxml）
第三步：Java 代码填充与导出（核心）
常见概念补充
常见问题与技巧

JasperReports 是一个非常流行的开源 Java 报表引擎，它可以生成 PDF、HTML、Excel、CSV 等多种格式的报表，它的使用流程通常分为：设计模板 -> 填充数据 -> 导出/预览。

下面是一个从零开始的完整使用指南,包含核心步骤和代码示例。

核心工作流程（三步走）

设计（Design）：使用可视化工具或 XML 手动编辑，创建 .jrxml 报表模板文件。
编译（Compile）：将 .jrxml 文件编译成 .jasper 二进制文件（这也是运行时要用到的文件）。
填充（Fill）：将数据（通常是 JRDataSource 或 Connection）填充到 .jasper 文件中，生成 JasperPrint 对象。
导出（Export）：将 JasperPrint 对象导出为 PDF、HTML、Excel 等格式。

第一步：环境搭建

如果你使用 Maven，在 pom.xml 中添加核心依赖（以 JasperReports 6.20.x 为例，版本号可根据需要调整）：

<dependency>
    <groupId>net.sf.jasperreports</groupId>
    <artifactId>jasperreports</artifactId>
    <version>6.20.6</version>
</dependency>
<!-- 如果导出 Excel 需要 Apache POI -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.5</version>
</dependency>
<!-- 如果编译或运行需要 Groovy 表达式支持（默认） -->
<dependency>
    <groupId>org.codehaus.groovy</groupId>
    <artifactId>groovy-all</artifactId>
    <version>3.0.19</version>
</dependency>

第二步：设计报表模板（.jrxml）

使用可视化工具 Jaspersoft Studio（推荐）

这是最直观的方式，相当于报表版的 Dreamweaver。

下载并安装 Jaspersoft Studio。
新建一个 Jasper Report 工程。
通过拖拽方式设计报表：
- Title。
- Page Header：页眉（每页顶部）。
- Column Header：表格列头。
- Detail：数据行（核心区域，循环显示）。
- Page Footer：页码。
- Summary：汇总信息。
定义 Parameter（输入参数）、Field（数据字段，对应 JavaBean 属性或 SQL 列名）。
保存文件，生成 .jrxml 文件。

手写 .jrxml（简单示例）

创建一个 my_report.jrxml 文件：

<?xml version="1.0" encoding="UTF-8"?>
<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              name="SimpleReport"
              pageWidth="595"
              pageHeight="842"
              columnCount="1"
              language="java"
              xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports
              http://jasperreports.sourceforge.net/xsd/jasperreport.xsd">
    <!-- 定义参数：外部传入 -->
    <parameter name="TITLE" class="java.lang.String"/>
    <!-- 定义字段：对应数据源中的属性 -->
    <field name="ID" class="java.lang.Integer"/>
    <field name="NAME" class="java.lang.String"/>
    <!-- 定义列标题区域 -->
    <columnHeader>
        <band height="30">
            <staticText>
                <reportElement x="0" y="0" width="150" height="30"/>
                <text>用户ID</text>
            </staticText>
            <staticText>
                <reportElement x="150" y="0" width="200" height="30"/>
                <text>用户名</text>
            </staticText>
        </band>
    </columnHeader>
    <!-- 定义明细行区域（循环显示） -->
    <detail>
        <band height="25">
            <textField>
                <reportElement x="0" y="0" width="150" height="25"/>
                <textFieldExpression><![CDATA[$F{ID}]]></textFieldExpression>
            </textField>
            <textField>
                <reportElement x="150" y="0" width="200" height="25"/>
                <textFieldExpression><![CDATA[$F{NAME}]]></textFieldExpression>
            </textField>
        </band>
    </detail>
</jasperReport>

第三步：Java 代码填充与导出（核心）

使用 JavaBean 集合作为数据源

假设你有一个实体类 User：

public class User {
    private Integer id;
    private String name;
    // getters and setters 省略
}

Java 代码：

import net.sf.jasperreports.engine.*;
import net.sf.jasperreports.engine.data.JRBeanCollectionDataSource;
import java.util.*;
public class JasperReportGenerator {
    public static void main(String[] args) throws JRException {
        // 1. 准备数据
        List<User> userList = new ArrayList<>();
        userList.add(new User(1, "张三"));
        userList.add(new User(2, "李四"));
        // 将 List 转换为 JasperReports 能识别的数据源
        JRBeanCollectionDataSource dataSource = new JRBeanCollectionDataSource(userList);
        // 2. 准备参数（对应 .jrxml 中的 $P{TITLE}）
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("TITLE", "用户报表");
        // 3. 编译 .jrxml 为 .jasper（通常只在第一次做，或者用预编译的）
        // 如果已经有 .jasper 文件，可以直接加载
        JasperReport jasperReport = JasperCompileManager.compileReport("path/to/my_report.jrxml");
        // 4. 填充数据，生成 JasperPrint 对象
        JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, parameters, dataSource);
        // 5. 导出为 PDF
        JasperExportManager.exportReportToPdfFile(jasperPrint, "C:/output/user_report.pdf");
        // 导出为 HTML（用字符串形式或文件）
        JasperExportManager.exportReportToHtmlFile(jasperPrint, "C:/output/user_report.html");
        // 导出为 Excel (需要 poi 依赖)
        // net.sf.jasperreports.engine.JRXlsExporter 等
        System.out.println("报表生成成功！");
    }
}

直接连接数据库

如果你的报表模板是基于 SQL 查询设计的（在 .jrxml 中定义了 <queryString>），可以直接传一个 JDBC Connection 对象：

// 假设你已经有一个 JDBC Connection
Connection connection = DriverManager.getConnection("jdbc:mysql://localhost:3306/test", "root", "password");
// 直接传入 connection，数据源将自动执行 SQL
JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, parameters, connection);

常见概念补充

层级	写法	说明
参数	`$P{参数名}`	外部传入，用于条件或标题
字段	`$F{字段名}`	数据源中的列或属性值
变量	`$V{变量名}`	内置变量，如 `PAGE_NUMBER`

常见问题与技巧

中文显示为方框：需要设置字体的 PDF 嵌入字体，或者在代码中指定字体，或者用 iText 字体扩展。
图片显示：使用 Image 元素，表达式可以直接传 InputStream、URL 或 byte[]。
子报表：大的报表可以拆分成多个 .jrxml，通过 Subreport 元素插入。
性能：对于大量数据（>10万行），尽量使用虚拟化数据源（JRCachedDataSet）或数据库直接连接,避免将所有数据加载到内存。

简单的思维导图：

┌─────────────────────────────────────────────────────┐
│            JasperReports 使用流程                    │
├─────────────────────────────────────────────────────┤
│ 1. 设计模板 (Jaspersoft Studio) → .jrxml           │
│ 2. 编译模板 (JasperCompileManager) → .jasper       │
│ 3. 准备数据 (JRDataSource / Connection / Map)      │
│ 4. 填充数据 (JasperFillManager) → JasperPrint      │
│ 5. 导出报表 (JasperExportManager) → PDF/HTML/Excel │
└─────────────────────────────────────────────────────┘

如果只是第一次接触，建议安装 Jaspersoft Studio 拖一个最简单的列表报表出来，再运行上面的 Java 代码，上手后，再学习分组、饼图、子报表等高级功能会容易很多。