JasperReports最終用戶手冊(cè)中文版第四章報(bào)表設(shè)計(jì)

1、第四章報(bào)表設(shè)計(jì)注：CJSDN.COM haibo 譯轉(zhuǎn)載請(qǐng)注明譯者和出處ethonsmith"報(bào)表設(shè)計(jì)(report design)”是一個(gè)模板，JasperReports引擎會(huì)用它來(lái)傳遞動(dòng)態(tài)內(nèi)容到 打印機(jī)，屏幕或者是Web頁(yè)面。存儲(chǔ)于數(shù)據(jù)庫(kù)中的數(shù)據(jù)會(huì)根據(jù)報(bào)表的實(shí)際設(shè)計(jì)來(lái)填充整個(gè)報(bào)表，打印到頁(yè)面導(dǎo)向的文檔。The report desig n represe nts a template that will be used by the JasperReports engine to deliver dynamic content to the printer, to the scr

2、een or to the Web. Data stored in the database is orga ni zed duri ng the report filli ng process accordi ng to this report desig n to obta in ready to print, page orie nted docume nts.通常，一個(gè)"報(bào)表設(shè)計(jì)"包含了關(guān)于數(shù)據(jù)填充后所形成的報(bào)表(docume nts)的結(jié)構(gòu)和所有的其他方面的信息。這些信息包括將要輸岀到報(bào)表上的各種文本，圖像元素的位置，內(nèi)容， 以及要進(jìn)行的數(shù)據(jù)計(jì)算，自定義計(jì)算，分組

3、，操作等信息。Gen erally speak ing, a report desig n contains all the in formatio n concerning the structure and the aspect of the docume nts that will be gen erated whe n the data will be provided. This in formati on concerns the positi on and the content of various text or graphic eleme nts that will app

4、ear on the docume nt, their appeara nee, the custom calculati ons, data group ing and data man ipulati on that should be performed whe n gen erati ng the docume nts, etc.一般，"報(bào)表設(shè)計(jì)(report design )"用一種特殊的結(jié)構(gòu)定義在Xml文檔中(我們會(huì)在稍后詳細(xì)分析)，在被填充數(shù)據(jù)前，這一過(guò)程屬于JasperReports報(bào)表的編輯階段。但是"報(bào)表設(shè)計(jì)(report design)&qu

5、ot;也可以用JasperReports API以編程的方式在內(nèi)存中構(gòu)造.隨JasperReports項(xiàng)目源文件一起提供了一個(gè) noxmldesign ( No Xml Design )例子介紹了如何直接在內(nèi)存中創(chuàng)建"報(bào)表設(shè)計(jì) (report design) ”，而不用編輯 Xml文檔。Normally, the report desig ns are defi ned in XML files with a special structure that we shall see in detail later and are subject to the JasperReports

6、 compilation process before being filled with data. But they also can be con structed in-memory, programmatically, using the JasperReports API.There is a sample called no xmldesig n shipped with the JasperReports project source files that shows how to directly create in-memory report desig ns, witho

7、ut edit ing any XML files at all.4.1 DTD文件引用用Xml文檔來(lái)編輯"報(bào)表設(shè)計(jì)(report design )"時(shí)，JasperReports用它自己內(nèi)部專用的 DTD文件來(lái)校驗(yàn)這個(gè)文檔內(nèi)容。如果 XML校驗(yàn)通過(guò)，那表示這個(gè) XML “報(bào)表設(shè)計(jì)(report design) ”符合 JasperReports所需要的XML 文檔結(jié)構(gòu)和語(yǔ)法， JapserReports引擎也可以編譯 這個(gè)文檔來(lái)輸岀"已編譯"的"報(bào)表設(shè)計(jì)( report design ) ”.When work ing with XML re

8、port desig ns, JasperReports uses its own internal DTD files to validate the XML content it receives for process in g. If the XML validati on is passed, it means that the supplied report desig n corresp onds to the JasperReports required XML structure and syn tax and the engine is able to gen erate

9、the compiled version of the report desig n.正確的Xml “報(bào)表設(shè)計(jì)"通常標(biāo)明用于校驗(yàn)它本身的 JasperReports內(nèi)部專用的DTD文件。 如果不標(biāo)明引用這個(gè)文件，報(bào)表編譯便會(huì)失敗。這個(gè)應(yīng)該不復(fù)雜，因?yàn)檫@個(gè)引用在每個(gè)“報(bào)表設(shè)計(jì)(report design )"里通常都是一樣，你只要簡(jiǎn)單的復(fù)制他就行了。初始設(shè)計(jì)報(bào)表，你可以從 本書的例子 里復(fù)制。Valid XML report desig ns always point to the JasperReports internal DTD files for validati o

10、n. Without the DTD reference specified, the report compilati on process fails abruptly. This should not be con sidered a too much burde n for an ybody since the DTD reference is always the same and can simply be copied from previous report desig ns. At the begi nning you will copy it from the suppli

11、ed samples.前面已經(jīng)說(shuō)過(guò)，Jasper reports引擎只認(rèn)識(shí)指向它內(nèi)部DTD文件的引用，所以大蝦你不要從library源文件里另外拷貝一個(gè)DTD文件放到別的所在，然后在你的“報(bào)表設(shè)計(jì)“里指向它-做外部引用。如果你預(yù)謀這樣做，你還得修改一些library Classes，包括dori.jasper.e ngin e.xml.JRXmlDigester類。As already mentioned, the engine recognizes only the DTD references that point to its internal DTD files. You cannot

12、 make a copy of the DTD files found among the library source files and point to that copy in your XML report desig ns. If you want to do that, you will also have to alter the code of some of the library classes including the dori.jasper.engine.xml.JRXmlDigester class.如果“小強(qiáng)”你有福遇到了說(shuō)JasperReport引擎由于資源載

13、入問(wèn)題找不到它自己內(nèi)部 DTD專用文件，確認(rèn)排除一切可能的錯(cuò)誤后再做外部DTD文件引用做“強(qiáng)人”。不過(guò)遇到這樣錯(cuò)誤的機(jī)率很小，因?yàn)閘ibrary資源載入機(jī)制已經(jīng)作了優(yōu)化。If you ever encounter problems such as the engine not finding its own internal DTD files due to some resource loadi ng problems, make sure you have elim in ated every possible cause before deciding to useexternal DT

14、D files. Encountering such a problem is very unlikely since theresource loadi ng mecha nism of the library was improved with time.在XML ”報(bào)表設(shè)計(jì)”里，有兩種方式的 DTD文件引用，它們是：<!DOCTYPE jasperReport PUBLIC "-/JasperReports/DTD Report Design/EN""或者是<!DOCTYPE jasperReport PUBLIC "-/JasperR

15、eports/DTD Report Design/EN""XML “報(bào)表設(shè)計(jì)”的根元素是<jasperReport>,下面是一個(gè)普通的XML文件形式的“報(bào)表設(shè)計(jì)”：<?xml version="1.0"?><!DOCTYPE jasperReport PUBLIC "-/JasperReports/DTD Report Design/EN""vjasperReport name="name_of_the_report"。>o oo</jasperReports&g

16、t;第一個(gè)連續(xù)的3個(gè)點(diǎn)號(hào)是放報(bào)表的屬性和設(shè)置的，另外3個(gè)點(diǎn)號(hào)是放各種“報(bào)表設(shè)計(jì)”元素的如：parameters,fields,variables,groups,sections,等。我們會(huì)在接下來(lái)的幾章里詳細(xì)分析它 們。The first 3 points make it for the report desig n properties and sett in gs a nd the other 3 for the suppressed various report desig n eleme nts such as report parameters, fields, variables,

17、 groups, report sect ions, etc. We shall see all of them in detail in the follow ing chapters of this book.4. 2 XML編碼使用不同種類的語(yǔ)言設(shè)計(jì)報(bào)表時(shí)，大哥你一定要注意你報(bào)表里的語(yǔ)言編碼要符合XML文件頭部的encoding屬性所指定的編碼。如果不指定的話，默認(rèn)的就是“ UTF 8”編碼。When creati ng XML report desig ns in differe nt Ian guages, a special atte nti on should be accord

18、ed to the encoding attribute that can be used in the header of the XML file. By default, if no value is specified for this attribute, the XML parser uses "UTF-8" as the encoding for the content of the XML file.羅嗦這一點(diǎn)很重要，因?yàn)槟闳绻斯ぶ圃靀ML報(bào)表設(shè)計(jì)“文件的話，你經(jīng)常會(huì)引入本土語(yǔ)言文本。This important because the report de

19、sign often contains localized static texts, which are introduced whe n man ually edit ing the XML file.對(duì)于大多數(shù)西歐語(yǔ)言，“ISO 8859 1 “編碼，也稱作”LATIN1 （拉丁語(yǔ)）”，應(yīng)該足夠滿足處理包括法語(yǔ)在內(nèi)特殊字符。For most of the West European Ianguages, the "ISO-8859-1" encoding, also known as LATIN1, should be sufficient to deal with

20、special characters like , a, ,e?, that we have in French for example.<?xml version="1.0" encoding="ISO-8859-1"?><!DOCTYPE jasperReport PUBLIC "-/JasperReports/DTD Report Design/EN""vjasperReport name="name_of_the_report" . ></jasperReports&

21、gt;具體到每種語(yǔ)言設(shè)計(jì)的報(bào)表，所最合適的編碼類型，請(qǐng)您查詢相關(guān)的XML文檔。（修理它）To find out what is the exact encoding type to specify when editing XML files in a particularIan guage, you have to check the XML docume ntatio n. FIXME4. 3報(bào)表屬性我們已經(jīng)知道，vjasperReport >XML文件形式的“報(bào)表設(shè)計(jì)”的根元素。這一節(jié)我們將會(huì)詳 細(xì)的看一下這個(gè)整張報(bào)表的各種屬性以及在XML文件里分別由誰(shuí)對(duì)應(yīng)它們。We have a

22、lready seen that vjasperReportis the root element of an XML report design. In this sect ion will get to know in detail what are the properties of a report desig n objects and what is are the XML attributes that corresp ond to them.Report Name每個(gè)“報(bào)表設(shè)計(jì)"都必須有一個(gè)名字（Name）。這很重要，因?yàn)?JasperReport要用它生成各種文件，

23、特別是在報(bào)表編譯，填充，導(dǎo)岀時(shí)默認(rèn)參數(shù)要使用時(shí)。Every report desig n has to have a n ame. Its n ame is importa nt because the library uses it whe ngenerating files, especially when the default behavior is preferred for compiling, filling or export ing the report.報(bào)表的名稱 用vjasperReport >的name屬性指定，這個(gè)屬性時(shí)必填的。而且不允許有空格， 必須是單個(gè)詞。

24、The name of the report is specified using the name attribute of the <jasperReport> element and is man datory. Spaces are not allowed in the report n ame, which has to be one word.Colum CountJasperReports允許在每頁(yè)創(chuàng)建多個(gè)列，就像下面這副圖一樣，它由兩列：VERTICAL I ILLINGHORIZONTAL FILLINGCOLUMN HEADERcolumn spacing QC

25、OLUMN HEADER+ column vwdth口 ET機(jī)DETAILIDETAL DETAILDETAILDETAILDETAIL、A*FGOLUMB FOOTERCOLUMN FOOTERPAGE HEADERtop margin QPAGE HEADERbottomPAGE HEADERCOLUMN HEADIERCOLUMN HEADERRDETAILDETALDETAILDETAI.DETAILDETAILDETAtDETAILCOLUMN FOOTERCOLUMN FOOTER.PAGE HEADER默認(rèn)的，JasperReport引擎每頁(yè)創(chuàng)建一個(gè)列Print Order對(duì)于有

26、多個(gè)列的報(bào)表，指定列的填充順序很重要?？梢杂胮rin tOrder屬性指定。屬性值有兩種：printOrder= "Vertical ”prin tOrder= "Horiz on tai ”1.豎向填充：列的填充順序?yàn)閺纳系较拢瑥淖蟮接?。?2.橫向填充：列的填充順序?yàn)閺淖蟮接?，從上到下。（圖6即說(shuō)明了這兩種填充方式。默認(rèn)的：prin tOrder= "Vertical"For the reports having more that one column, is important to specify the order in which the

27、columns will be filled and this can be done using the printOrder attribute of the <jasperReport> eleme nt. There are two possible situati ons:Vertical filling : Selecting this option will ensure the columns are filled from top to bottom and left to right (printOrder="Vertical").Horiz

28、ontal filling : Columns are filled from left to right and top to bottom(pri ntOrder="Horizo ntal"). The default print order is: prin tOrder="Vertical"Page Size有兩個(gè)屬性可以指定要打印出的報(bào)表文檔的大?。簆ageWidth和pageHeight.像所有其它的JasperReports元素指定大小和位置的屬性一樣，它們都以像素為單位。JasperReports使用Java默認(rèn)的映射72點(diǎn)每英寸。這意味

29、著，如果設(shè)置 pageWidth=595，那么映 射的實(shí)際紙張大小為8.26英寸，恰好時(shí)A4織的寬度。這兩個(gè)屬性默認(rèn)都設(shè)置為A4紙的大小：pageWidth="595" pageHeight="842"There are two attributes at this level to specify the page size of the document that is going to be gen erated: pageWidth and pageHeight. Like all the other JasperReports attribut

30、es that represe nf| eleme nt dime nsions and positi on, those should be specified in pixels. JasperReports uses the | default Java resoluti on of 72 dots per in ch. This means that a pageWidth="595" will make about 8.26 in ches, which is roughly the width of an A4 paper. The default page s

31、ize corresp onds to an A4 paper: pageWith="595" pageHeight="842"Page OrientationOrientation屬性確定將要打印的報(bào)表紙張的鋪放方向，可以是豎鋪（A4紙正常放）或橫鋪（A4紙橫者放）。The orientation attribute is used to specify whether we are creating documents using the "Portrait" or the "La ndscape" forma

32、ts.如果你從豎鋪 Portrait轉(zhuǎn)為橫鋪Landscape，你還得必須修改 pagewidth 和pageheight屬性。 JasperReports requires you to adapt the page width and the page height whe n switch ing from "Portrait" docume nts to "La ndscape" or vice-versa.例如：若你要豎鋪A4紙，那么報(bào)表的屬性大約應(yīng)設(shè)計(jì)為 ：pageWidth="595" pageHeight="

33、842" orientation="Portrait"若你要橫鋪A4紙，那么報(bào)表的屬性必須改為：pageWidth="842" pageHeight="595" orien tatio n="La ndscape"Let's see an example: We assume that we want to create an A4 report using the "Portrait" layout. An A4 has approximately this size: pa

34、geWidth="595" pageHeight="842" orientation="Portrait" If we decide to use the "La ndscape" layout for our A4 docume nt, we have to make sure we modify the page with and page height accord in gly, like in the follow ing:pageWidth="842" pageHeight=&quo

35、t;595" orien tatio n="La ndscape"這是因?yàn)?jasperreports必須知道將要打印紙張的絕對(duì)寬度和高度，而且至少在填充報(bào)表時(shí)，它不會(huì)考慮我們對(duì) orie ntation屬性所設(shè)的值。This is because JasperReports has to know exactly the absolute width and height of the pages it will draw on, and does not necessarily consider the value that we supply in the

36、orientation attribute, at least not at report filling time.Orientation屬性只有在實(shí)際打印時(shí)才有用，它來(lái)通知打印機(jī)或其他輸出設(shè)備頁(yè)面的的鋪放方向。默認(rèn)設(shè)置為豎向，orie ntatio n= Portrait;This orientation attribute is only useful at report printing time, to inform the printer about the page orientation or in some special exporters. The default pag

37、e orientation is "Portrait".page Margins文檔大小確定以后，你就可以指定 jasperreports引擎在產(chǎn)生報(bào)表時(shí)應(yīng)該預(yù)留多大的頁(yè)邊 距。頁(yè)邊距有四個(gè)屬性指定：topMargin ,leftMargin, bottomMargin 和 rightMargin .（圖 6已有說(shuō)明）。默認(rèn)設(shè)置上，下頁(yè)邊距為20像素，左右為30像素。Once the page size decided, you can specify what margins should the report ing engine preserve whe n gen

38、erati ng the reports. And there are 4 attributes for the job: topMargi n, leftMargi n, bottomMarg in and rightMarg in （figure 6）. There is a 20 pixels default margin for the top and bottom of the page and a 30 pixels default marg in for the right and left marg ins.Column Size and Spacing在前面說(shuō)明ColumnC

39、ount屬性時(shí)，我們已經(jīng)說(shuō)明報(bào)表可以有多個(gè)列。報(bào)表引擎必須知道每個(gè)列有多寬，每列之間的間隔有多大，這由ColumnWidth和ColumnSpacing 屬性指定。Reports may have more that one colu mn, as we have already see n whe n we have talked about the colu mnCount attribute above. But the report ing engine has to know how large a colu mn can be and what space should it le

40、t between columns. There are two attributes for this job: columnWidth and colu mn Spac ing.在編譯"報(bào)表設(shè)計(jì)”時(shí)，JasperReports會(huì)同樣校驗(yàn)一下所有列的寬度和所有的列間隔是否與指定的頁(yè)面寬度和頁(yè)邊距相符合。There is also a validati on check performed whe n we compile the report desig ns, that do not let us create reports in which the width of the

41、overall columns and the space between does not fit on the specified page width and page margins.因?yàn)閖asperreports默認(rèn)只有一列，所以列間隔默認(rèn)為0像素，列寬是頁(yè)面默認(rèn)寬度減去默認(rèn)左右頁(yè)邊距為555像素。Since there is only one colu mn by default, the default colu mn spaci ng is 0 pixels and the default colu mn width is equal to the default page w

42、idth, minus the default left and right margins, which make 555 pixels.Empty Data Source Behavior有時(shí)，我們?yōu)閳?bào)表指定的數(shù)據(jù)集可能為空集，具體輸出什么我們不能確定。Sometimes the data source that we supply to our reports has no records in it. In this case, it is not clear what the output should be.可能希望輸出一張空文檔，有時(shí)希望輸出報(bào)表的某些部分。Some may ex

43、pect to see a blank document in these situations and others might w ant to have some of the report secti ons displayed any way.我們可以指定一個(gè) whenNoDataType屬性來(lái)指定發(fā)生這種情況時(shí)文檔的輸出結(jié)果。There is an attribute called whe nN oDataType that lets you decide how the gen erated docume nt should look whe n there is no data

44、 in the data source supplied to it.有三個(gè)屬性值可選：Empty document:產(chǎn)生的報(bào)表文檔為空，沒(méi)有一頁(yè)。Viewers在裝入這種文當(dāng)時(shí)會(huì)拋出異常。(whe nN oDataType =" NoPages").Bla nk page:產(chǎn)生一頁(yè)空的文檔。(whe nN oDataType = "Bla nkPage").All sections displayed :報(bào)表文檔會(huì)產(chǎn)生除了 detail部分以外所有的其他部分。(whenNoDataType="AIISectionsNoDetail").默認(rèn)值：whe nN oDataType ="NoPages".There are 3 possibilities you can choose from:Empty docume nt: The gen erated docume nt will have no pages in it. Viewers might throw anerror whe n trying to load such docume nts (whe nN oDataType="NoPages").Blank page : The gen erated docume nt