【译】JasperReports Library使用指南

简介（Introduction）

        Jasperreports是一个强大的开源报表工具，它能够传送丰富的内容到屏幕上、打印机或者转换为PDF、HTML、XLS、RTF、ODT、CSV、TXT和XML文件等多种格式的文件。Jasperreports完全由Java编写，它可以被用于各种各样的Java程序来动态的生成内容。它主要的目的就是帮助以一种简单且灵活的方式生成基于页面的、可打印的文档。

API 概览（API Overview）

Jasperreports会整理从JRXML文件（报表设计文件,又称为报表模版文件，后缀为*.jrxml）中定义的数据源中取出的数据。为了给一个报表填充数据，报表设计文件必须首先经过编译。

通过JasperCompileManager类暴露的compileReport()方法来编译报表设计文件。通过编译，报表设计文件（*.jrxml）将被加载到一个报表设计（jasper-design）对象中，然后这个对象将被序列化到磁盘上（由JasperReport类完成，生成的文件为*.jasper）。这个序列化的对象将在程序需要向其填充数据的时候被使用到。事实上，编译一个*.jrxml文件意味着将要编译定义在*.jrxml文件中定义的所有Java表达式，在编译时将执行一系列的验证过程，用于检查*.jrxml文件的一致性。编译的结果是生成一个将会根据一系列数据来生成文档的“待填充（ready-to-fill）”文件（*.jasper）。

我们可以使用JasperFillManager类暴露的fillReportXXX()方法来填充一份“待填充”文件。这些方法接收一个jasper-design对象或者一个代表该对象的文件作为参数，同时接收一个连接数据库的用于获取填充数据的JDBC连接。方法的执行结果是生成一个可打印（ready-to-print，打印工作由JasperPrint类完成）文档（*.jrprint），它将被序列化到磁盘上待以后使用。这份文档将被传送到屏幕或者打印机，或者可以被导出为PDF、HTML、XLS、RTF、ODT、CSV、TXT或者XML文档。

如上所述，使用JasperReports时用到的主要的类有：

net.sf.jasperreports.engine.JasperCompileManager

net.sf.jasperreports.engine.JasperFillManager

net.sf.jasperreports.engine.JasperPrintManager

net.sf.jasperreports.engine.JasperExportManager

这些类代表了JasperReports引擎的门面类，它们包含了一系列简化了访问API的静态方法，它们可用于编译一份报表设计文件、为报表填充数据、打印报表或者将结果导出到其他文档格式。

除了这些门面类以外，你还可以直接使用具体的导出类来工作。比如你需要导出你的报表为XLS、RTF、ODT、TXT或者其他文档格式，对于这些格式，在JasperExportManager类中没有相应的辅助方法，又比如在当你需要配置导出过程以使满足你特殊的需求时，也可以使用这些导出类。这些导出实现类可以在JasperReports库的net.sf.jasperreports.engine.export包中找到。

如果你想在Swing应用中显示报表，你可以使用和JasperReports库一起推出的JRViewer组件。它由一个可嵌入的而且可配置的java.swing.JPanel组件组成。JasperViewer是一个独立的Swing应用，它使用JRViewer组件以特有的格式（序列化的JasperPrint对象）或者XML格式展示报表。为了辅助报表设计工作，JasperReports还在JasperDesignerViewer类中提供了一个报表设计的预览器。

报表设计（Report Design）

正如上面提到的，报表设计代表了一个将会被JasperReports引擎使用来生成动态内容到打印机、屏幕或者Web的模版文件。存储在数据库中的数据会被整理起来用于获得可打印的、基于页面的文档。报表设计以一种特殊的结构定义在JRXML文件中，这个结构已在JasperReports引擎提供的DTD文件中声明。然后JRXML文件被编译，因为接下来将在报表填充操作中使用到它们。

为了创建一个简单的报表设计，我们需要以以下结构来编辑一份XML文件：

?

为了更好的理解JRXML文件的结构，或者一份报表设计的流程，我们推荐你看看快速引用（原链接已失效）。

编译报表设计文件（Compiling Report Designs）

一份报表设计文件是以一个具有jasperreport.dtd文件定义的结构的JRXML文件或者是一个存在于内存中的JasperDesign对象的方式呈现。为了根据这样的报表设计文件生成报表，这个对象或文件需要被编译。这个编译过程可以通过使用JasperCompileManager类的compileReportXXX()方法完成，其结果是生成一个*.jasper文件或者一个JasperReport对象。

编译一个报表设计文件时，引擎首先会执行一步验证来确保设计文件的一致性，然后

转换所有报表中的表达式为一个待赋值的形式，并且将它们存储在编译后的JasperReport文件或者*.jasper文件中。

这个转换要么是跟报表模版相关的Java类的快速编译过程，要么是生成将要在报表填充阶段计算表达式值时使用的Groovy或者BeanShell脚本，这取决于报表中指定的表达式的语言（详见报表模版文件的language属性）。

在更深入了解报表编译之前，你应该通过阅读以下常见问题来了解什么时候你需要编译模版文件，以及怎样才能以最好的方式编译它们：

什么情况下我应该编译我的模版文件？怎样编译？（原链接已失效）

为了让模版文件编译过程尽可能的灵活，我们将用到一个特殊的叫做JRCompiler的接口。正如上面看到的，在这个库中有多个不同类型的类实现了这个接口：

        1. Java报表编译器。这个编译器生成并编译一个包含计算表达式值的方法的Java类。

        2. Groovy报表编译器。它生成一个脚本用于在运行时计算表达式的值。

        3. BeanShell报表编译器。它也生成一个脚本用于运行时计算表达式的值。

        关于更多报表编译的信息，请查看The Definitive Guide to JasperReports。

用Ant任务来编译报表模版文件

既然模版文件的编译过程更像是一个设计时的工作而不是运行时的工作，库中提供一个Ant任务来简化开发。这个Ant任务由JRAntCompileTask类实现，它和Ant内置任务<javac>非常相似，只是符号和行为需要我们关心。

模版文件的编译任务可以通过在工程的build.xml文件中像下面这样声明：

?

在上面的例子中，lib文件夹应包含jasperreports-<version>.jar文件和它所依赖的库文件（包含jdt-compiler-<version>.jar，万一你使用Java作为报表表达式的语言，这是推荐的报表编译器）。

接下来这个用户自定义的Ant任务可以用于在一个单个操作中编译多个JRXML报表模版文件。可以通过指定包含这些JRXML文件的根目录或者通过使用文件的模式匹配选择JRXML文件来指定它们。下面是模版文件编译任务的一些属性：

像Ant内置任务<javac>一样，报表模版文件编译任务支持内嵌的<src>和<classpath>元素。为了看到这一点起作用，可以查看JasperReports项目源码中提供的demo/samples/antcompile例子

 查看一个报表设计文件

报表设计文件可以通过使用JasperDesignViewer程序来查看。在它的main()方法中，它接收一个用于查看的包含报表设计的文件名，它可能是JRXML文件自身，也可以是编译后的设计文件（.jasper文件）

填充报表（Filling Reports）

我们可以通过调用JasperFillManager类的fillReportXXX()方法让一个编译好的报表文件生成报表。在这个门面接口类中有两种类型的填充方法。一类接收一个java.sql.Connection对象作为第三个参数，另一类接收一个JRDataSource对象。

这是因为大多数时候，我们使用一个JDBC连接获取关系型数据库中的数据来填充报表，我们可以很方便的在报表模版文件中使用SQL查询。JasperReports引擎可以使用传递给它的Connection执行SQL查询，由此生成一个报表数据源用于填充报表。

如果数据以其他的形式提供，此时将用到接收一个数据源作为参数的方法。

查看、打印和导出报表（View, Print and Export Reports）

生成的报表可以通过使用JasperViewer程序来查看。它的main()方法接收一个用于查看的报表文件的文件名。生成的报表也可以通过调用JasperPrintManager类的printReport()、printPage()或者printPages()等静态方法来打印。

在填充了一个report后，我们可以通过调用JasperExportManager的exportReportXXX()方法将其导出为PDF，HTML或者XML格式。

参数（Parameters）

参数是在报表填充操作中传入的对象的引用。它在传递不能从数据源中找到的数据给报表引擎时非常有用。例如：如果我们需要在报表中显示启动报表填充操作的用户的名字，我们可以传递一个用户名给引擎；或者我们可以通过参数来动态的改变报表的标题。

还有一个很重要的方面是：为了能在更进一步的自定义从数据库中取到的数据，可以在报表的查询字符串中使用参数，这些参数可以像为报表提供数据的查询中的动态过滤器一样工作。

在报表模版中声明一个参数很简单，我们只需要指定其类型和参数名，例如：

?

在查询中有两种可能使用这些参数的方式：

1. 参数用于普通的java.sql.PreparedStatement的参数，使用以下格式：

?

2. 有时，使用参数来动态修改SQL查询的一部分或者传递整个SQL查询作为参数来填充报表是很有用的，在这些情况下，格式有些不同，例如下面的例子：

?

下面还有些系统中内置的参数，在表达式中可以直接使用：

数据源（Data Source）

JasperReports使用一个叫做JRDataSource的接口来支持多种类型的数据源，这个接口有这个接口有一个默认的叫做JRResultSetDataSource的实现类，它封装了一个java.sql.ResultSet对象，它允许通过JDBC使用任何类型的关系型数据库。

使用一个JDBC数据源时，你需要传递一个java.sql.Connection对象给报表填充操作，并指定报表定义中的query（可以查看XML文件中的元素）；或者通过直接提供一个java.sql.ResultSet对象来创建一个新的JRResultSetDataSource实例。

对于其他类型的数据源而言，也没有多大区别。你需要做的就是实现JRDataSource接口，或者使用JasperReports库中的某一个实现类来封装一个内存中的集合、JavaBeans数组、CSV或XML文件等。

字段（Fields）

报表的字段是唯一映射数据源中的数据到报表生成子程序的方式。当报表的数据源是一个java.sql.ResultSet时，java.sql.ResultSet对象中的所有的字段必须映射给相应的列，这些列必须拥有和ResultSet字段同样的名字和相兼容的数据类型。

比如：如果我们想用Employees表中取出的数据生成一个报表，该表为以下结构：

我们可以在报表模版文件中定义以下字段：

?

如果我们声明一个字段，该字段在java.sql.ResultSet中没有相应的列对应，那么将会在运行时抛出一个异常。一个在java.sql.ResultSet中的列的对象如果在报表中没有对应的字段，那么在报表填充操作时将不受影响，但是它同样不可访问。

表达式（Expressions）

表达式是JasperReports的一个强大的功能。它们可用于声明报表中对数据分组时将会执行一系列计算的变量，来指定报表文本域内容甚至自定义报表中对象的样式。

基本上所有的报表表达式是Java表达式，它们可以引用报表中的字段（Fields）和变量（Variables）。

在一个XML报表模版文件中，定义的表达式有以下几种：

• <variableexpression>
• <initialvalueexpression>
• <groupexpression>
• <printwhenexpression>
• <imageexpression>
• <textfieldexpression>

在一个表达式中使用一个报表字段（Field），字段名必须放在”$F{“和”}”之间，比如：如果我们想在报表中的一个textfield中显示两个字段连接后的值，我们可以像下面这样定义一个表达式：

?

表达式甚至可以更复杂一些：

?

在表达式中引用一个变量（Variable），变量名必须放在”$V{”和”}”之间，像下面的例子一样：

?

在表达式中，可以对参数（Parameter）使用相同的符号。参数名应该放在”${”和”}”之间，像下面的例子一样：

?

变量（Variable）

报表的变量是一个在表达式基础上特殊的对象。变量可以通过仅仅被声明一次并在报表中用于多次，或者在相应的表达式中进行一系列的计算来简化报表设计。在它的表达式中，一个变量可以引用其他变量，但前提是这些被引用的变量之前报表中已经有声明。因此，报表中变量声明的顺序很重要。

正如提到的，变量可以在他们相应的表达式中执行内置类型的计算，例如count，sum，average，lowest，highest等。

一个用于计算数量总和的变量应该像以下这样声明：

?

对于执行计算的变量，我们可以指定它们重新初始化的级别。默认级别是Report，那意味着这个变量在整个报表开始时只初始化一次，然后它将执行指定的计算直到报表结束。但是我们可以指定一个重置变量的较低级别，例如页面级别（page），列级别（column）或者组级别（group）。

比如：如果我们想计算每一页的总量，我们应该这样声明一个变量：

?

这个变量将在每一页开始时初始化为0值。

这里还有以下可以在表达式中直接使用的内置变量：

• PAGE_NUMBER
• COLUMN_NUMBER
• REPORT_COUNT
• PAGE_COUNT
• COLUMN_COUNT
• GroupName_COUNT

报表区域（Report Sections）

当构建一个报表时，我们需要定义区域的布局和内容。整个报表文件结构是基于以下区域的：

• <pageheader>
• <groupheadr>
• <groupfooter>
• <pagefooter>
• <summary>
• <columnheader>
• <detail>
• <columnfooter>
• <lastpagefooter>
• <nodata>

Sections是报表中的一部分，它有一个指定的高度和宽度，并且可以包含例如线条（lines）、矩形（rectangles）、图像（images）或者文本域（textfields）等报表元素。当在XML报表模版文件中声明报表区域的布局和内容时，我们使用一般的元素。

下面这个页眉中，只包含了一个线条对象和一个静态文本：

?

框（Frames）

有时候一组元素需要共享一个公共的背景色或者一个公共的边框。这是通过在它们后面放一个矩形来实现的，但是这样做对网格导出器（grid exporters）是不起作用的，因为它不支持重叠的元素。

新的Frame元素将被网格导出器识别，可以被用于将元素嵌入Frame中来对元素进行分组。Frames可以被嵌入无限层。

分组（Groups）

分组代表了一种在报表中组织数据的灵活的方式。当填充一个报表的时候，JasperReports引擎将检测所有定义的分组表达式来判断是否发生了分组结束，如果是，引擎将在报表中使用相应的<groupfooter>（这个分组的groupfooter）和<groupheader>（下个分组的groupheader，如果有的话。译者注。）区域。

只要我们需要，在报表中我们可以有很多个group。报表中声明的分组顺序很重要，因为分组互相包含，一个组包含接下来的一个组，等等。当一个大的分组结束时，所有子分组会被重新初始化。

声明一个报表分组时，会同时给出相应的数据分组表达式，我们会声明两种区域：就是分组的header和分组的footer。

请查阅Jasper样例报表来查看如何定义分组。

字体和Unicode支持（Fonts and Unicode Support）

现在你可以以任何语言创建报表了！

介绍的元素中的新属性允许在Java字体和PDF字体间建立映射关系。PDF使用特殊的字体设置，在JasperReports以前的版本中没有一种方式可以使用它们。通过介绍这些新的属性，用户可以指定PDF将使用哪种字体来显示不同的字符集（pdfFontName属性），将使用何种编码方式（pdfEncoding属性）以及是否该字体会被嵌入到PDF文档中（isPdfEmbedded属性）。

为了简化字体设置，一个新的元素出现了：

报表字体是报表级别的字体定义，它可以在整个报表的其他字体定义中被用于默认或者基准字体设置。因为对国际化字符的支持在某种程度上跟iText库相关联。你可以查看iText文档以获得关于怎样以不同语言不同字符集来创建一个PDF文档的更多信息。

样式（Styles）

为了将一组被用于报表元素的视觉特性进行分组，引入了报表样式。这个新概念是一个以前的报表字体（现在已过时）的扩展。引用了报表样式的报表元素能够覆盖任何在样式中定义的视觉特性。

报表样式同样可以引用其他的报表样式，并且拥有同样的用于样式的继承和覆盖机制。样式在整个组的元素需要共享同样的视觉特性的时候非常有用，因为对样式的任何改变都会被用于该组中所有的元素。这可以通过改变它们共同引用的报表样式来实现。

小脚本（Scriptlets）

在报表样式中显示的所有数据均来自报表参数（Parameters）和报表的字段（Fields）。这些数据可以使用报表变量（Variable）和它们组成的表达式来处理。

处理变量有特定的时刻。一些变量在报表开始时根据它们的resettype来初始化，一些在遇上分页（page break）或者分列（column break）时，亦或者在分组改变（group change）时。另外，变量在每次从数据源中取出新数据时被赋值（每行都会赋值一次）。

但是只有简单的变量表达式有时不能实现复杂的功能，这时就要用到小脚本了。

小脚本是Java代码片段，它们可以在每次报表事件发生时被执行。通过使用小脚本，用户可以修改报表变量中存放的值。

因为小脚本主要和报表变量一起工作，在准确的时刻完全控制脚本的执行是极为重要的。JasperReports允许用户自定义的Java代码在根据变量的重置类型（Report、Page、Column和Group）初始化报表变量的“之前”或者“之后”被执行。

为了利用好这个功能，用户只需要通过继承JRAbstractScriptlet类或者JRDefaultScriptlet类来创建一个脚本类即可。这个自定义脚本类的名字必须在<jsaperreport>元素中的scriptletClass属性中指定。

当创建一个JasperReports脚本类时，开发者需要实现或者覆盖几个方法，比如：beforeReportInit， afterReportInit(),  beforePageInit(), afterPageInit(), beforeGroupInit()， afterGroupInit()等，这些方法将会在填充报表的合适时候被报表引擎调用。

有一个默认的报表参数叫REPORT_SCRIPTLET，它代表了一个对报表引擎在填充报表时初始化的脚本对象的引用，它可以被用于整个报表的表达式中来调用脚本对象中的自定义方法，这使得整个机制更加灵活。

以上就是小脚本的所有了！详见ScriptletReport例子。

子报表（Subreports）

子报表是一个报表生成工具重要的功能。子报表允许创建更加复杂的报表来简化设计工作。

子报表在创建概览--明细类型的报表或者单个报表不足以描述复杂的输出文档时非常有用。

子报表其实就是一个包含在另一个报表中的普通报表。一个报表可以和子报表重叠，还可以创建包含自己的一个子报表，这种嵌套可以深至无限的深度。任何的报表模版在被嵌入到其他报表时不需要修改里面的任何地方就可以被作为一个子报表。

像其他报表元素一样，子报表元素有一个将在运行时为了获得JasperReports对象的资源而被计算的表达式。

一共有两种方式可以为子报表提供参数值。一种是，你可以使用用于生成指定参数映射Map的元素，或者你可以使用<subreportparameter>元素为每一个相关的参数赋值。如果同时使用两种方式为子报表参数赋值，那么使用<subreportparameter>指定的参数值将覆盖使用<parametersmapexpression>元素指定的值。

就像普通报表一样，子报表也以同样的方式，需要一个数据源来生成相应的内容，并且子报表在填充时希望接收到相同的输入类型。

从子报表中计算出的值可以被返回到父报表，在一个子报表填充值之后，子报表的变量值可以被赋值或者累计（使用一个增长器）到父报表的变量中。

详情请查阅Subreport样例。

国际化（Internationalization）

JasperReports允许通过使用新的resourceBundle属性在运行时或者在运行时为内置参数REPORT_RESOURCE_BUNDLE赋一个值来关联一个java.util.ResourceBundle对象。

如果需要以不同于当前本地环境（Locale）的环境生成，那么在填充报表时这个内置参数REPORT_LOCALE应该被用于指定运行时的本地环境。

为了更容易的国际化报表，在报表表达式中有一个特殊符号允许引用放在报表关联的java.util.ResourceBundle对象中的字符串资源。$R{...}表达式用于封装资源束（Resource Bundle）的key来获取对应的值。

为了格式化基于报表本地环境的不同语言中的消息，在报表关联的JRCalculator中有一个内置方法提供和java.text.MessageFormat类相似的功能。这个方法就是msg()，它允许在消息中最多使用3个参数。同样的，还提供了内置的str()方法，它的作用和表达式中$R{...}符号相同，都是基于报表的本地环境访问资源束。

在生成的输出中，JasperReports库会保存文本运行方向，以便以不同语言生成的拥有从右到左的书写（比如阿拉伯语和希伯来语）的文档能够被正确的渲染。

详情请查阅I18nReport和UnicodeReport样例。

数据集（Datasets）

图表和交叉表有时候需要使用在报表填充时没有被迭代的数据。这就是数据源的某些字段自身作为子报表的数据源这种情况。

为了避免使用子报表来渲染图表或者交叉表，我们引入了一个叫做数据集（Dataset）的新概念。一个数据集是一个数据源和子报表之间的概念，因为它包含了参数（Parameters）、字段（Fields）、变量（Variables）和分组（Groups），但是没有布局（Layout）信息。

详情请查阅/demos/samples/charts和Crosstabs样例。

图表（Charts）

JasperReports现在内置支持使用图表。尽管我们已经有图像、文本域子报表和其他元素可用，还有一种新的、立即可用的图表组件。这极大的简化了把图表嵌入到报表中的方式，因为这之前，用户必须完全依赖于小脚本（scriptlets）来收集图表数据并在报表模版中使用一个image元素来渲染图表。

现在通过使用新的chart组件，用户只需要设置期望的样式并且在迭代报表数据源时以一种增长的方式定义能够帮助引擎构建图表数据集的表达式即可。

在嵌入和配置图表组件时，有三个相关的实体：

• 全局的chart组件
• chart数据集（将chart数据分组的相关设置）
• chart样式（chart条目在渲染时相关的样式设置）

JasperReports目前支持以下几种图表：

饼图、3D饼图、条形图、3D条形图、堆积图、3D堆积图、折线图、区域图、散点图、气泡图、时序图和高低开合图。

这些图表使用几种数据集（每一种图表和几种指定的数据集工作）：饼图数据集、种类数据集、XY数据集、时序数据集、时间段值、XYZ数据集和高低数据集。

对于所有的图表，我们可以配置以下属性：

• 四周的边框
• 背景色
• 标题
• 标题位置（顶部、左边、底部、右边）
• 标题字体
• 标题颜色
• 子标题
• 子标题字体
• 子标题颜色
• 显示/隐藏图例
• 绘图区域背景色
• 绘图区域背景色透明度（alpha值）
• 绘图区域前景色透明度（alpha值）
• 绘图区域方向（垂直、水平）
• 坐标文本

  对于所有的数据集，我们可以配置以下属性：

• 增长类型（详细、列、页、分组、报表）
• 增长分组
• 重置类型（无、按列、按页、按组、按报表）
• 重置分组

  图表类型的详细设置：

• 3D饼图
  • 深度因子
• 条形图、XY条形图、堆积条形图
  • 隐藏/显示文本
  • 隐藏/显示提示标记
  • 隐藏/显示提示文本
• 3D条形图，3D堆积条形
  • 图隐藏/显示文本
  • x偏移量（3D效果）
  • y偏移量（3D效果）
• 折线图、XY折线图、散点图、时序图
  • 隐藏/显示线条
  • 隐藏/显示图形气泡图
• 气泡图
  • 缩放类型
• 高低开合图
  • 隐藏/显示关闭提示
  • 隐藏/显示打开提示

JasperReports使用JFreeChart库来渲染图表。关于怎么使用这个功能，可以在提供的JFreeChart样例中找到。

交叉表（Crosstabs）

交叉表是一个特殊类型的表组件，它的行和列都是动态的。它们用于显示在列（columns）和组（groups）上使用多级分组的聚合数据。

详情请查阅提供的Crosstabs样例。

原文地址：http://community.jaspersoft.com/wiki/jasperreports-library-tutorial