【譯】JasperReports Library使用指南

簡介（introduction）

jasperreports是一個強大的開源報表工具，它能夠傳送豐富的内容到螢幕上、列印機或者轉換為pdf、html、xls、rtf、odt、csv、txt和xml檔案等多種格式的檔案。jasperreports完全由java編寫，它可以被用于各種各樣的java程式來動态的生成内容。它主要的目的就是幫助以一種簡單且靈活的方式生成基于頁面的、可列印的文檔。

jasperreports會整理從jrxml檔案（報表設計檔案,又稱為報表模版檔案，字尾為*.jrxml）中定義的資料源中取出的資料。為了給一個報表填充資料，報表設計檔案必須首先經過編譯。

如上所述，使用jasperreports時用到的主要的類有：

<a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/jaspercompilemanager.html">net.sf.jasperreports.engine.jaspercompilemanager</a>

<a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/jasperfillmanager.html">net.sf.jasperreports.engine.jasperfillmanager</a>

<a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/jasperprintmanager.html">net.sf.jasperreports.engine.jasperprintmanager</a>

<a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/jasperexportmanager.html">net.sf.jasperreports.engine.jasperexportmanager</a>

這些類代表了jasperreports引擎的門面類，它們包含了一系列簡化了通路api的靜态方法，它們可用于編譯一份報表設計檔案、為報表填充資料、列印報表或者将結果導出到其他文檔格式。

為了建立一個簡單的報表設計，我們需要以以下結構來編輯一份xml檔案：

<code><</code><code>jasperreport</code> <code>...</code><code>=</code><code>""</code> <code>name</code><code>=</code><code>"name_of_the_report"</code>

<code> </code><code>xmlns</code><code>=</code><code>"http://jasperreports.sourceforge.net/jasperreports"</code>

<code> </code><code>xmlns:xsi</code><code>=</code><code>"http://www.w3.org/2001/xmlschema-instance"</code>

<code> </code><code>xsi:schemalocation</code><code>=</code><code>"http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd"</code><code>></code>

<code></</code><code>jasperreport</code><code>></code>

為了更好的了解jrxml檔案的結構，或者一份報表設計的流程，我們推薦你看看快速引用（原連結已失效）。

編譯一個報表設計檔案時，引擎首先會執行一步驗證來確定設計檔案的一緻性，然後

轉換所有報表中的表達式為一個待指派的形式，并且将它們存儲在編譯後的jasperreport檔案或者*.jasper檔案中。

這個轉換要麼是跟報表模版相關的java類的快速編譯過程，要麼是生成将要在報表填充階段計算表達式值時使用的groovy或者beanshell腳本，這取決于報表中指定的表達式的語言（詳見報表模版檔案的language屬性）。

在更深入了解報表編譯之前，你應該通過閱讀以下常見問題來了解什麼時候你需要編譯模版檔案，以及怎樣才能以最好的方式編譯它們：

什麼情況下我應該編譯我的模版檔案？怎樣編譯？（原連結已失效）

1. java報表編譯器。這個編譯器生成并編譯一個包含計算表達式值的方法的java類。

用ant任務來編譯報表模版檔案

模版檔案的編譯任務可以通過在工程的build.xml檔案中像下面這樣聲明：

<code><</code><code>taskdef</code> <code>classname</code><code>=</code><code>"net.sf.jasperreports.ant.jrantcompiletask"</code> <code>name</code><code>=</code><code>"jrc"</code><code>></code>

<code> </code><code><</code><code>classpath</code><code>></code>

<code> </code><code><</code><code>fileset</code> <code>dir</code><code>=</code><code>"./lib"</code><code>></code>

<code> </code><code><</code><code>include</code> <code>name</code><code>=</code><code>"**/*.jar"</code> <code>/></code>

<code> </code><code></</code><code>fileset</code><code>></code>

<code> </code><code></</code><code>classpath</code><code>></code>

<code></</code><code>taskdef</code><code>></code>

在上面的例子中，lib檔案夾應包含jasperreports-<version>.jar檔案和它所依賴的庫檔案（包含jdt-compiler-<version>.jar，萬一你使用java作為報表表達式的語言，這是推薦的報表編譯器）。

接下來這個使用者自定義的ant任務可以用于在一個單個操作中編譯多個jrxml報表模版檔案。可以通過指定包含這些jrxml檔案的根目錄或者通過使用檔案的模式比對選擇jrxml檔案來指定它們。下面是模版檔案編譯任務的一些屬性：

屬性

描述

srcdir

用于編譯的jrxml檔案的位置。除非相關的元素會呈現，否則是不可省（required）的。

destdir

用于存放編譯後檔案的位置（預設與srcdir相同）

compiler

（可選）實作了jrcompiler接口的類的名字

xmlvalidation

用于标記報表模版的源檔案的xml驗證是否将被執行的标記（預設值為true）

tempdir

用于存儲臨時生成檔案的位置（預設值為目前工作目錄）

keepjava

用于表明臨時生成的java檔案是否需要保留的标記（預設值為false）

像ant内置任務<javac>一樣，報表模版檔案編譯任務支援内嵌的<src>和<classpath>元素。為了看到這一點起作用，可以檢視jasperreports項目源碼中提供的demo/samples/antcompile例子

檢視一個報表設計檔案

這是因為大多數時候，我們使用一個jdbc連接配接擷取關系型資料庫中的資料來填充報表，我們可以很友善的在報表模版檔案中使用sql查詢。jasperreports引擎可以使用傳遞給它的connection執行sql查詢，由此生成一個報表資料源用于填充報表。

如果資料以其他的形式提供，此時将用到接收一個資料源作為參數的方法。

參數是在報表填充操作中傳入的對象的引用。它在傳遞不能從資料源中找到的資料給報表引擎時非常有用。例如：如果我們需要在報表中顯示啟動報表填充操作的使用者的名字，我們可以傳遞一個使用者名給引擎；或者我們可以通過參數來動态的改變報表的标題。

還有一個很重要的方面是：為了能在更進一步的自定義從資料庫中取到的資料，可以在報表的查詢字元串中使用參數，這些參數可以像為報表提供資料的查詢中的動态過濾器一樣工作。

在報表模版中聲明一個參數很簡單，我們隻需要指定其類型和參數名，例如：

<code><</code><code>parameter</code> <code>class</code><code>=</code><code>"java.lang.string"</code> <code>name</code><code>=</code><code>"reporttitle"</code> <code>/></code>

<code><</code><code>parameter</code> <code>class</code><code>=</code><code>"java.lang.integer"</code> <code>name</code><code>=</code><code>"maxorderid"</code> <code>/></code>

<code><</code><code>parameter</code> <code>class</code><code>=</code><code>"java.awt.image"</code> <code>name</code><code>=</code><code>"summaryimage"</code> <code>/></code>

在查詢中有兩種可能使用這些參數的方式：

1. 參數用于普通的java.sql.preparedstatement的參數，使用以下格式：

<code>select</code> <code>* </code><code>from</code> <code>orders </code><code>where</code> <code>customerid = $p{ordercustomer}</code>

2. 有時，使用參數來動态修改sql查詢的一部分或者傳遞整個sql查詢作為參數來填充報表是很有用的，在這些情況下，格式有些不同，例如下面的例子：

<code>select</code> <code>* </code><code>from</code> <code>orders </code><code>order</code> <code>by</code> <code>$p!{orderbyclause}</code>

下面還有些系統中内置的參數，在表達式中可以直接使用：

參數名

report_parameters_map

這個參數包含了所有使用者定義和内置的參數的map

report_connection

一個使用者提供的，用于jdbc連接配接資料源的java.sql.connection

report_data_source

一個代表系統内置的資料源類型或者使用者提供的資料源的jrdatasource

report_max_count

一個用于允許使用者限制資料源大小的整數

report_scriptlet

report_locale

一個包含資源組期望的locale執行個體的java.util.locale對象

report_resource_bundle

包含了本地化消息的java.util.resourcebundle對象

report_time_zone

一個用于為使用者格式化日期的java.util.timezone執行個體

report_virtualizer

report_class_loader

一個在報表填充階段用到的用于加載像images、fonts、或者subreport模版的java.lang.classloader 執行個體

is_ignore_pagination

如果被設定成java.lang.boolean.true，報表将會生成一個很長的頁面，不會插入分頁符

使用一個jdbc資料源時，你需要傳遞一個java.sql.connection對象給報表填充操作，并指定報表定義中的query（可以檢視xml檔案中的元素）；或者通過直接提供一個java.sql.resultset對象來建立一個新的jrresultsetdatasource執行個體。

報表的字段是唯一映射資料源中的資料到報表生成子程式的方式。當報表的資料源是一個java.sql.resultset時，java.sql.resultset對象中的所有的字段必須映射給相應的列，這些列必須擁有和resultset字段同樣的名字和相相容的資料類型。

比如：如果我們想用employees表中取出的資料生成一個報表，該表為以下結構：

字段名

資料類型

長度

employeeid

int

lastname

varchar

firstname

hiredate

datetime

我們可以在報表模版檔案中定義以下字段：

<code><</code><code>field</code> <code>class</code><code>=</code><code>"java.lang.integer"</code> <code>name</code><code>=</code><code>"employeeid"</code> <code>/></code>

<code><</code><code>field</code> <code>class</code><code>=</code><code>"java.lang.string"</code> <code>name</code><code>=</code><code>"lastname"</code> <code>/></code>

<code><</code><code>field</code> <code>class</code><code>=</code><code>"java.lang.string"</code> <code>name</code><code>=</code><code>"firstname"</code> <code>/></code>

<code><</code><code>field</code> <code>class</code><code>=</code><code>"java.util.date"</code> <code>name</code><code>=</code><code>"hiredate"</code> <code>/></code>

如果我們聲明一個字段，該字段在java.sql.resultset中沒有相應的列對應，那麼将會在運作時抛出一個異常。一個在java.sql.resultset中的列的對象如果在報表中沒有對應的字段，那麼在報表填充操作時将不受影響，但是它同樣不可通路。

表達式是jasperreports的一個強大的功能。它們可用于聲明報表中對資料分組時将會執行一系列計算的變量，來指定報表文本域内容甚至自定義報表中對象的樣式。

基本上所有的報表表達式是java表達式，它們可以引用報表中的字段（fields）和變量（variables）。

在一個xml報表模版檔案中，定義的表達式有以下幾種：

在一個表達式中使用一個報表字段（field），字段名必須放在”$f{“和”}”之間，比如：如果我們想在報表中的一個textfield中顯示兩個字段連接配接後的值，我們可以像下面這樣定義一個表達式：

<code><</code><code>textfieldexpression</code><code>></code>

<code> </code><code>$f{firstname} + " " + $f{lastname}</code>

<code></</code><code>textfieldexpression</code><code>></code>

表達式甚至可以更複雜一些：

<code> </code><code>$f{firstname} + " " + $f{lastname} + " was hired on "</code>

<code> </code><code>+ (new simpledateformat("mm/dd/yyyy")).format($f{hiredate}) + "."</code>

在表達式中引用一個變量（variable），變量名必須放在”$v{”和”}”之間，像下面的例子一樣：

<code> </code><code>"total quantity : " + $v{quantitysum} + " kg." </code>

在表達式中，可以對參數（parameter）使用相同的符号。參數名應該放在”${”和”}”之間，像下面的例子一樣：

<code> </code><code>"max order id is : " + $p{maxorderid} </code>

報表的變量是一個在表達式基礎上特殊的對象。變量可以通過僅僅被聲明一次并在報表中用于多次，或者在相應的表達式中進行一系列的計算來簡化報表設計。在它的表達式中，一個變量可以引用其他變量，但前提是這些被引用的變量之前報表中已經有聲明。是以，報表中變量聲明的順序很重要。

正如提到的，變量可以在他們相應的表達式中執行内置類型的計算，例如count，sum，average，lowest，highest等。

一個用于計算數量總和的變量應該像以下這樣聲明：

<code><</code><code>variable</code> <code>calculation</code><code>=</code><code>"sum"</code> <code>class</code><code>=</code><code>"java.lang.double"</code> <code>name</code><code>=</code><code>"quantitysum"</code><code>></code>

<code> </code><code><</code><code>variableexpression</code><code>></code>

<code> </code><code>$f{quantity}</code>

<code> </code><code></</code><code>variableexpression</code><code>> </code>

<code></</code><code>variable</code><code>></code>

對于執行計算的變量，我們可以指定它們重新初始化的級别。預設級别是report，那意味着這個變量在整個報表開始時隻初始化一次，然後它将執行指定的計算直到報表結束。但是我們可以指定一個重置變量的較低級别，例如頁面級别（page），列級别（column）或者組級别（group）。

比如：如果我們想計算每一頁的總量，我們應該這樣聲明一個變量：

<code> </code><code></</code><code>variableexpression</code><code>></code>

<code> </code><code><</code><code>initialvalueexpression</code><code>></code>

<code> </code><code>new double(0)</code>

<code> </code><code></</code><code>initialvalueexpression</code><code>></code>

這個變量将在每一頁開始時初始化為0值。

這裡還有以下可以在表達式中直接使用的内置變量：

page_number

column_number

report_count

page_count

column_count

groupname_count

當建構一個報表時，我們需要定義區域的布局和内容。整個報表檔案結構是基于以下區域的：

sections是報表中的一部分，它有一個指定的高度和寬度，并且可以包含例如線條（lines）、矩形（rectangles）、圖像（images）或者文本域（textfields）等報表元素。當在xml報表模版檔案中聲明報表區域的布局和内容時，我們使用一般的元素。

下面這個頁眉中，隻包含了一個線條對象和一個靜态文本：

<code><</code><code>pageheader</code><code>></code>

<code> </code><code><</code><code>band</code> <code>height</code><code>=</code><code>"30"</code><code>></code>

<code> </code><code><</code><code>rectangle</code><code>></code>

<code> </code><code><</code><code>reportelement</code> <code>height</code><code>=</code><code>"25"</code> <code>width</code><code>=</code><code>"555"</code> <code>x</code><code>=</code><code>"0"</code> <code>y</code><code>=</code><code>"0"</code><code>></</code><code>reportelement</code><code>></code>

<code> </code><code><</code><code>graphicelement</code><code>></</code><code>graphicelement</code><code>></code>

<code> </code><code></</code><code>rectangle</code><code>></code>

<code> </code><code><</code><code>statictext</code><code>></code>

<code> </code><code><</code><code>textelement</code> <code>textalignment</code><code>=</code><code>"center"</code><code>></</code><code>textelement</code><code>></code>

<code> </code><code><</code><code>text</code><code>>northwind order list</</code><code>text</code><code>></code>

<code> </code><code></</code><code>statictext</code><code>></code>

<code></</code><code>pageheader</code><code>></code>

有時候一組元素需要共享一個公共的背景色或者一個公共的邊框。這是通過在它們後面放一個矩形來實作的，但是這樣做對網格導出器（grid exporters）是不起作用的，因為它不支援重疊的元素。

新的frame元素将被網格導出器識别，可以被用于将元素嵌入frame中來對元素進行分組。frames可以被嵌入無限層。

分組代表了一種在報表中組織資料的靈活的方式。當填充一個報表的時候，jasperreports引擎将檢測所有定義的分組表達式來判斷是否發生了分組結束，如果是，引擎将在報表中使用相應的<groupfooter>（這個分組的groupfooter）和<groupheader>（下個分組的groupheader，如果有的話。譯者注。）區域。

隻要我們需要，在報表中我們可以有很多個group。報表中聲明的分組順序很重要，因為分組互相包含，一個組包含接下來的一個組，等等。當一個大的分組結束時，所有子分組會被重新初始化。

聲明一個報表分組時，會同時給出相應的資料分組表達式，我們會聲明兩種區域：就是分組的header和分組的footer。

現在你可以以任何語言建立報表了！

介紹的元素中的新屬性允許在java字型和pdf字型間建立映射關系。pdf使用特殊的字型設定，在jasperreports以前的版本中沒有一種方式可以使用它們。通過介紹這些新的屬性，使用者可以指定pdf将使用哪種字型來顯示不同的字元集（pdffontname屬性），将使用何種編碼方式（pdfencoding屬性）以及是否該字型會被嵌入到pdf文檔中（ispdfembedded屬性）。

為了台灣字型設定，一個新的元素出現了：

為了将一組被用于報表元素的視覺特性進行分組，引入了報表樣式。這個新概念是一個以前的報表字型（現在已過時）的擴充。引用了報表樣式的報表元素能夠覆寫任何在樣式中定義的視覺特性。

報表樣式同樣可以引用其他的報表樣式，并且擁有同樣的用于樣式的繼承和覆寫機制。樣式在整個組的元素需要共享同樣的視覺特性的時候非常有用，因為對樣式的任何改變都會被用于該組中所有的元素。這可以通過改變它們共同引用的報表樣式來實作。

在報表樣式中顯示的所有資料均來自報表參數（parameters）和報表的字段（fields）。這些資料可以使用報表變量（variable）和它們組成的表達式來處理。

處理變量有特定的時刻。一些變量在報表開始時根據它們的resettype來初始化，一些在遇上分頁（page break）或者分列（column break）時，亦或者在分組改變（group change）時。另外，變量在每次從資料源中取出新資料時被指派（每行都會指派一次）。

但是隻有簡單的變量表達式有時不能實作複雜的功能，這時就要用到小腳本了。

小腳本是java代碼片段，它們可以在每次報表事件發生時被執行。通過使用小腳本，使用者可以修改報表變量中存放的值。

因為小腳本主要和報表變量一起工作，在準确的時刻完全控制腳本的執行是極為重要的。jasperreports允許使用者自定義的java代碼在根據變量的重置類型（report、page、column和group）初始化報表變量的“之前”或者“之後”被執行。

當建立一個jasperreports腳本類時，開發者需要實作或者覆寫幾個方法，比如：beforereportinit， afterreportinit(), beforepageinit(), afterpageinit(), beforegroupinit()， aftergroupinit()等，這些方法将會在填充報表的合适時候被報表引擎調用。

有一個預設的報表參數叫report_scriptlet，它代表了一個對報表引擎在填充報表時初始化的腳本對象的引用，它可以被用于整個報表的表達式中來調用腳本對象中的自定義方法，這使得整個機制更加靈活。

子報表是一個報表生成工具重要的功能。子報表允許建立更加複雜的報表來簡化設計工作。

子報表在建立概覽--明細類型的報表或者單個報表不足以描述複雜的輸出文檔時非常有用。

子報表其實就是一個包含在另一個報表中的普通報表。一個報表可以和子報表重疊，還可以建立包含自己的一個子報表，這種嵌套可以深至無限的深度。任何的報表模版在被嵌入到其他報表時不需要修改裡面的任何地方就可以被作為一個子報表。

一共有兩種方式可以為子報表提供參數值。一種是，你可以使用用于生成指定參數映射map的元素，或者你可以使用<subreportparameter>元素為每一個相關的參數指派。如果同時使用兩種方式為子報表參數指派，那麼使用<subreportparameter>指定的參數值将覆寫使用<parametersmapexpression>元素指定的值。

就像普通報表一樣，子報表也以同樣的方式，需要一個資料源來生成相應的内容，并且子報表在填充時希望接收到相同的輸入類型。

從子報表中計算出的值可以被傳回到父報表，在一個子報表填充值之後，子報表的變量值可以被指派或者累計（使用一個增長器）到父報表的變量中。

jasperreports允許通過使用新的resourcebundle屬性在運作時或者在運作時為内置參數report_resource_bundle賦一個值來關聯一個java.util.resourcebundle對象。

如果需要以不同于目前本地環境（locale）的環境生成，那麼在填充報表時這個内置參數report_locale應該被用于指定運作時的本地環境。

為了更容易的國際化報表，在報表表達式中有一個特殊符号允許引用放在報表關聯的java.util.resourcebundle對象中的字元串資源。$r{...}表達式用于封裝資源束（resource bundle）的key來擷取對應的值。

在生成的輸出中，jasperreports庫會儲存文本運作方向，以便以不同語言生成的擁有從右到左的書寫（比如阿拉伯語和希伯來語）的文檔能夠被正确的渲染。

圖表和交叉表有時候需要使用在報表填充時沒有被疊代的資料。這就是資料源的某些字段自身作為子報表的資料源這種情況。

為了避免使用子報表來渲染圖表或者交叉表，我們引入了一個叫做資料集（dataset）的新概念。一個資料集是一個資料源和子報表之間的概念，因為它包含了參數（parameters）、字段（fields）、變量（variables）和分組（groups），但是沒有布局（layout）資訊。

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折線圖、散點圖、時序圖

隐藏/顯示線條

隐藏/顯示圖形氣泡圖

氣泡圖

縮放類型

高低開合圖

隐藏/顯示關閉提示

隐藏/顯示打開提示

交叉表是一個特殊類型的表元件，它的行和列都是動态的。它們用于顯示在列（columns）群組（groups）上使用多級分組的聚合資料。

【譯】JasperReports Library使用指南

繼續閱讀

關于Gradle配置的小結

Java小案例——随機數猜測随機數猜測

nginx location中斜線的位置的重要性

27 Best Free Eclipse Plug-ins for Java Developer to be ProductiveCode Quality PluginsText Editor PluginsDependency ManagementVersion Control Integration PluginsFramework Development Continuous Integration Related PluginsOther Utility Plugins

Java String.format方法的簡單使用

neo4j之cypher使用文檔

GitHub連夜封殺！這份阿裡 10W 字内部 Java 字面試手冊到底有多強？

spark/scala關于【資源檔案】加載方法概述外部檔案加載方案測試資源檔案打包入jar包中小結

mybatis_入門程式Mybatis入門

AOP程式設計_Android優雅權限架構(1)概念基礎，2021金三銀四前言正文大綱正文

Effective Java 8:通用程式設計

OOM三種類型

工廠模式-三種類型

【遞歸】高效率求2的n次幂

win10本地scala和spark安裝安裝scala安裝spark

scala (3) Function 和 Method