Jasper Report v1.0用户手册中文版

Jasper Report用户手册

version1.0

作者：薛笛

EMail：[e-mail]

严正声明:本来我在以前把JasperReport1.0的用户文档由中文译成了英文，花了两周多时间写了几万字，并把它贴到了CSDN的Blog上，并凡是要翻译完的PDF文档的朋友我都尽量给邮过去。但是最近我发现问我要文档的人总管我叫“良子大哥”，我开始还不明所以，后来一查才知道CSDN上有个叫良子的人把我翻译的东西整理了一下，调整了一下格式变成了他的作品，上面压根就没提我，但是里面的注明的索要文档PDF版的E-Mail（[e-mail]）却是还是我的—所以别人还是问我要PDF文档！！这令我十分不爽。本来嘛，我想公开大家看是件好事，但你不能连个转载标志也不写啊！？？这行为不是明抢吗，做人不能这样啊？但是今天我终于想通了，我好歹也念过这么多年书，不能和他一般见识，最终又重新把它贴出来，不过还是希望不要有人再这么做。

Jasper Report用户手册... i

version1.0. i

1 简介... 1

2 API概览... 2

Class net.sf.jasper.engine.design.JasperDesign. 2

Class net.sf.jasper.engine.JasperReport4

Class net.sf.jasper.engine.JasperCompileManager4

Class net.sf.jasper.engine.JasperPrint4

Interface net.sf.jasper.engine.JRDataSource. 4

Class net.sf.jasper.engine.JRResultSetDataSource. 5

Class net.sf.jasper.engine.data.JRTableModelDataSource. 5

Class net.sf.jasper.engine.JREmptyDataSource. 5

Class net.sf.jasper.engine.JasperFillManager5

Class net.sf.jasper.engine.JRAbstractScriptlet6

Class net.sf.jasper.engine.JRDefaultScriptlet6

Class net.sf.jasper.engine.JasperPrintManager6

Class net.sf.jasper.engine.JasperExportManager7

Class net.sf.jasper.engine.JasperRunManager7

Class net.sf.jasper.view.JRViewer7

Class net.sf.jasper.view.JasperViewer7

Class net.sf.jasper.view.JasperDesignViewer7

Class net.sf.jasper.engine.util.JRLoader7

3 主要的任务和过程... 8

3.1 XML解析... 8

3.2 编译报表设计(Report Designs)9

3.3 Report Design 预览... 12

3.4报表装填（Filling Report）... 13

3.5 查看报表（Viewing Reports）... 15

3.6 打印报表... 15

3.7 导出报表... 16

3.8 对象的载入和保存... 16

4 报表设计（Report Designs）... 17

4.1 DTD Reference. 17

4.2 XML 编码... 18

4.3 报表属性... 19

Report Name. 19

Column Count（列数）... 20

Print Order（打印顺序）... 20

Page Size（页面大小）... 21

Page Orientation（默认设置为Portrait）... 21

Page Margins（页边距）... 21

Empty Data Source Behavior22

Scriptlet Class22

5 报表数据（Report Date）... 23

5.1 表达式（expressions）... 23

5.2 参数（Parameters）... 24

参数名... 25

参数类型... 25

Prompting for Parameter values26

参数的默认值（parameter default value）... 26

5.2.1 内置的报表参数... 27

5.3 Data Source（数据源）... 28

5.4 报表查询（Report Query）... 30

5.5 字段（Field）... 32

字段名（Field Name）... 33

字段类型（Field Class）... 34

字段描述（Field Description）... 34

5.6 变量（Variables）... 35

变量名（Variable Name）... 35

变量类型（Variable Class）... 35

重置类型（Reset Type）... 36

Reset Group. 36

5.6.1 运算（Calculations）... 36

5.6.2 内置的报表变量（Build-in Report Variables）... 39

6 Report Sections41

6.1 Main Report Sections42

6.2 Data Grouping. 43

Group Name. 44

Group Header44

Group Footer44

7 Scriptlets45

8 Report Elements46

Absolute Position. 46

Relative Position. 47

Element Size. 47

Element Color47

8.1 Text Elements51

8.1.1 Fonts and Unicode Support51

8.1.2 Static Texts55

8.1.3 Text Fields56

8.2 Graphic Elements58

8.2.1 Lines59

8.2.2 Rectangles60

8.2.3 Images60

8.2.4 Charts and Graphics62

8.3 Hyperlinks63

8.4 Element Groups64

9 Subreports65

9.1 Subreport Parameters67

9.2 Subreport Data Source. 68

10 Advanced JasperReports68

10.1 XML Report Designs Loading and Writing. 68

10.2 Implementing Data Sources69

10.3 Customizing Viewers69

10.4 Exporting to New Output Formats70

1 简介

JasperReport是一个强大、灵活的报表生成工具，能够展示丰富的页面内容，并将之转换成PDF，HTML，或者XML格式。最重要的是它是开源的，这给我们带来很大方便，但是文档却要钱，让人不爽。不过人总要生存，再说，做这么一个好东西，用户总不能一点代价也不付（虽然对于中国普通程序原来说太贵了点）。它还有一个相关的开源工程—IReport，这是一个图形化的辅助工具，因为JasperReport仅提供了可使用的类库而未提供更好的开发工具，IReport的出现解决了这一难题。它们配合使用将会更大程度的提高效率。

该库完全由Java写成，可以用于在各种Java应用程序，包括J2EE，Web应用程序中生成动态内容。它的主要目的是辅助生成面向页面的（page oriented），准备付诸打印的文档。

JasperReport借由定义于XML文档中的report design进行数据组织。这些数据可能来自不同的数据源，包括关系型数据库，collections，java对象数组。通过实现简单的接口，用户可以将report library插入到订制好的数据源中，在以后我们将提到有关内容。

其实这是一份JasperReport Ultimate Guide的简单翻译以及我的理解和例子。在最后，我将描述一个我正在做的工程，将其中用到的相关信息贡献出来。我这么做是因为当我在学这个类库的时候苦于很少有相关的中文文档，诱惑语焉不详，希望其他人不再受苦。这个文档将分几次贴出来，与原文档的章节相对应。这份文档的Word形式将在全部完成之后放在我的公开邮箱中与各位共享。我的EMail是[e-mail]有什么意见或想法请与我联系。

闲言少叙，进入正题。

2 API概览

上图为一个生成报表并打印（导出）的全过程。我将会把涉及到的重要的类进行一一说明。

Class net.sf.jasper.engine.design.JasperDesign

这是一个未经加工的报表实例，供JasperReport Library使用。这个类可以在JasperReport类库内置的XML解析器对XML report design进行解析处理之后得到。如果你的程序不想对直接XML文件进行操作，在例子noxmldesign中有不使用XML设计文件而动态生成这个类的方法。我们稍稍看看这个例子：

import 略

public class NoXmlDesignApp

{

private static JasperDesign getJasperDesign() throws JRException

{

//JasperDesign定义JasperDesign的头信息

JasperDesign jasperDesign = new JasperDesign();

jasperDesign.setName("NoXmlDesignReport");

.剩余略

//Fonts定义使用到的字体

JRDesignStyle normalStyle = new JRDesignStyle();

normalStyle.setName("Arial_Normal");

//Parameters 定义Parameters的内容—这个内容以后会提到

JRDesignParameter parameter = new JRDesignParameter();

parameter.setName("ReportTitle");

parameter.setValueClass(java.lang.String.class);

jasperDesign.addParameter(parameter);

parameter = new JRDesignParameter();

parameter.setName("OrderByClause");

parameter.setValueClass(java.lang.String.class);

jasperDesign.addParameter(parameter);

//Query 定义查询

JRDesignQuery query = new JRDesignQuery();

query.setText("SELECT * FROM Address $P!{OrderByClause}");

jasperDesign.setQuery(query);

//Fields

JRDesignField field = new JRDesignField();

field.setName("Id");

field.setValueClass(java.lang.Integer.class);

jasperDesign.addField(field);

//Variables 定义变量

JRDesignVariable variable = new JRDesignVariable();

variable.setName("CityNumber");

variable.setValueClass(java.lang.Integer.class);

variable.setResetType(JRVariable.RESET_TYPE_GROUP);

//Groups 定义组

group.setMinHeightToStartNewPage(60);

expression = new JRDesignExpression();

//余下定义一个文档的其他内容，这里省略

return jasperDesign;

}

从getJasperDesign()方法我们可以看出，这个应用程序并没有从XML文件里面将report design提取出来在生成JasperDesign类，而是直接利用JasperDesign提供的函数生成了一个报表设计。这样做的原因是基于灵活性的考虑，你可以在程序中随时动态生成报表，而不需要去从硬盘或网络中读取XML设计文件。但通常我不这么做，因为比较麻烦，而且要对JasperReport的每个元素都非常熟悉才行。

Class net.sf.jasper.engine.JasperReport

这个类的实例包含了一个经过编译的report design对象。生成它的时机是对报表编译之后，但尚未对其填入数据的时候。编译过程中，JasperReport需要生成一个临时的类文件，用以保存report expression，如变量表达式，文本，图像表达式，组表达式等等。这个临时的Java Source File是被动态编译的，编译器使用的是JDK中用来执行应用程序的编译器类（compiler class）。如果 tools.jar不在classpath中，编译过程将采用javac.exe来进行后台编译。编译后所得的字节码保存在JasperReport类中，用来在执行期装填数据（filling the report with data）和给表达式赋值（evaluate various report expression）。

Class net.sf.jasper.engine.JasperCompileManager

这是一个上面提到的与编译有关的类。利用它提供的一些方法，你将有能力编译从本地硬盘或一个Input Stream获得的XML report；还可以通过传给JasperCompileManager一个JasperDesign类，来对内存中的report design进行编译—功能很强大。

Class net.sf.jasper.engine.JasperPrint

当一个报表已经装填好数据之后，这个文档就以JasperPrint类的实例出现。这个类可以直接用JasperReport内置的viewer进行查看，也可以序列化到硬盘以备后用，或者发送到网上去。这个类的实例是报表装填过程后的产物，它可以被JasperReport类库中的导出方法导出成各种流行的格式—PDF，HTML，XML等等。

Interface net.sf.jasper.engine.JRDataSource

这个类与报表的数据源有关。只要能够恰当的实现他的一些接口，用户就可以在报表中使用各种数据源，在报表装填的时候由报表引擎负责对数据进行解释和获取。当报表装填的时候，报表引擎都会在后台生成或提供一个该接口的实例。

Class net.sf.jasper.engine.JRResultSetDataSource

这是一个JRDataSource的缺省实现，因为很多报表数据都来源于关系数据库，所以JasperReport缺省包含了这个外覆（wrap）了java.sql.ResultSet对象的实现。

这个类可以用来包裹（wrap）用以对报表进行装填的、已经载入的结果集，也可以被报表引擎用来包裹通过JDBC执行完查询后所得的数据----非常有用。

Class net.sf.jasper.engine.data.JRTableModelDataSource

顾名思义，这个类用于包裹java.swing.table.TableModel类中的数据，它也是实现了JRDataSource接口，用于在Java Swing程序中使用已经被载入到table中的数据来生成报表。

Class net.sf.jasper.engine.JREmptyDataSource

这是JRDataSouce接口的最简单实现，这个类用在不需要显示数据源数据而从参数中获取数据的报表和仅需要知道数据源中的实际行数（number of virtual rows）的报表中。

JasperReport自带的例子：fonts，images，shapes和unicode中使用这个类对报表进行装填，来模拟没有任何record的数据源，这时所有的field都为null。例如：

JasperRunManager.runReportToPdfFile(fileName, null, new JREmptyDataSource());

Class net.sf.jasper.engine.JasperFillManager

这个类用来实现报表的数据装填。这个类提供了很多方法来接受各种类型的report design--可以是一个对象，一个文件，或一个输入流。它的输出结果也是多样的：file，Object，output Stream。

report的装填引擎需要接收一个可以从中获取数据和value的数据源作为报表参数。参数值（Parameters value）通常使用Java.util.Map来提供，里面包含的KEY是报表的参数名。

数据源可以通过两种方式提供，这取决于你的解决方案：

通常情况下，用户应该提供一个JRDataSource对象，例如我前面提到的那些。

但是大多数的报表都是采用关系数据库中的值来装填数据，所以JasperReport拥有一个内置的缺省行为—让用户在报表设计的时候提供一个SQL查询。在运行期，这个查询将被执行以用来从数据库中获取要装填的数据。在这种情况下，JasperReport仅需要一个java.sql.Connection对象来取代通常的数据对象。JasperReport需要这个连接对象来连接数据库管理系统并执行查询操作。

在查询结束之后，JasperReport将自动生成一个JRResultSetDataSource，并将它返回给报表装填过程。

Class net.sf.jasper.engine.JRAbstractScriptlet

这个类同样用于报表装填期间，用户可以自己定义一些代码，并由报表引擎在装填过程中执行。这些用户代码可以处理报表数据操作，或在一些定义好的时刻执行，例如page，列，或组的分割处。

Class net.sf.jasper.engine.JRDefaultScriptlet

这是一个非常方便的JRAbstractScriptlet的子类。通常情况下你应该选择继承这个类。

Class net.sf.jasper.engine.JasperPrintManager

这个类用户提供打印方法，用户可以将整个文档或部分文档传递给它，也可以选择是否显示打印Dialog，这在他的API文档中可以找到，这里不再赘述。

Class net.sf.jasper.engine.JasperExportManager

顾名思义，这个类负责文档的导出。这个类的具体信息详见API文档。非常明显和清除，没什么好解释的，Just use it即可。

Class net.sf.jasper.engine.JasperRunManager

有时，我们仅仅需要构造一个流行的文档格式，例如PDF，或HTML，而不需要将装填过程后生成的JasperPrint对象保存到硬盘或其他中间媒体上。这时，可以使用这个类来直接将装填过程生成的文档导出到所需的格式。

Class net.sf.jasper.view.JRViewer

这是一个基于Swing的应用程序，你可以将它视为一个独立组件，用来进行打印预览。用户可以继承这个类，来构造满足自身要求的预览程序。

Class net.sf.jasper.view.JasperViewer

这个类更像是使用JRViewer的教学组件，它演示了一个Swing应用程序如何装在并显示报表。

Class net.sf.jasper.view.JasperDesignViewer

这个类用于报表的设计期间，用来预览报表模版。它仅作为一个开发工具存在于类库中。

text-indent:

分享到：

开始看c语言的缺陷和陷阱，写下笔记 | 利用JasperReport+iReport进行Web报表开发

• 2007-05-08 09:31
• 浏览 695
• 评论(0)
• 查看更多