开始使用
本章节介绍如何使用报表向导和报表编辑器创建并执行报表。
我们将使用图书馆（Library）应用程序作为本章节的示例程序，源码位于 GitHub。
项目配置
-
下载并解压 Jmix Samples 项目，或者直接用 Git 克隆：
git clone https://github.com/jmix-framework/jmix-samples
-
按照 打开已有项目 部分的说明，在 Studio 中打开
jmix-samples项目。 -
选择 Reports-sample Jmix Application 配置，按照 启动应用程序 部分的说明启动应用程序。
-
使用
admin/admin凭证登录 Library 应用。
打开 报表浏览界面 然后点击 Create（新建） → Using wizard（向导）。
使用向导可以创建下列类型的报表：
-
单个实体的报表。
-
实体列表的报表。
-
通过查询过滤的实体列表的报表。
使用向导创建报表的过程包含三个步骤：
-
创建报表的数据结构。
-
编辑报表区域。
-
保存报表。
使用报表向导
本节中，我们将创建的报表包含书籍的主要数据以及书籍作者的信息。报表模板将使用 DOCX 格式，保存后的报表使用 PDF 格式。
从应用程序主菜单打开 Reports → Reports 界面，然后点击 Create（新建） → Using wizard（向导）。在向导的第一步输入下列内容：
-
报表实体：
Book（jmxrpr_Book）。 -
模板类型：DOCX。
-
报表名称：
Book Record。 -
报表类型：
Report for single entity。
定义属性
向导的下一步中，指定 Book 实体和关联的 LiteratureType 实体的属性，这些属性将在报表中展示：Book.Name, Book.Summary, Book.Literature type.Name。这些属性形成了所谓的 “简单展示区”（simple region）。
点击 OK 移至下一步 - 报表展示区编辑。
出现的界面包含一个命名区域列表，这些区域是用来显示相关数据。向导支持向模板中添加多个纯文本区域，以显示不同的数据集。
加载到特定区域的实体属性列表可以通过单击属性列表链接来修改。还可以通过单击 Add simple region（添加简易展示区） 来添加新区域。
如果实体包含集合属性，则会出现 Add tabulated region（添加表格展示区） 按钮。可以添加显示表格数据的区域。
因此，为了展示该 Book 实体相关的作者列表，我们将创建另一个数据展示区。点击 Add tabulated region（添加表格展示区） 按钮。
选择 Book.Authors.First name 和 Book.Authors.Last name 属性。
所有的展示区都配置完成后，可以进行最后一步了：保存报表。此时，可以查看完整的报表模板，或将输出文件的名称和格式更改为其他任意支持的类型。我们选择 PDF 作为报表输出类型。
点击 Save 按钮后，会显示标准的报表编辑器。可以对报表继续做微调。
配置输出文档
报表的输出文档包含一个最初通过向导定义的模板。输出类型设置为 PDF，模板文件是 DOCX。
点击模板文件名并打开它，例如，通过 LibreOffice 打开。按照下图修改 模板内容：
|
报表的模板可以在 Demo 项目中下载： reports/templates。 |
此外，还可以定义输出文档的文件名。可以使用静态名称，也可以编程式配置。
这里，对于 “The 20th Century Art Book” 这本书，文件名是：Book Record - The 20th Century Art Book.pdf。
因此，我们需要配置一个引用特定报表区域的文件名：${Root.title}.pdf。
Root.title 是 Root 数据区域的标题值。标题属性通过一个基于 Groovy 的数据集定义：
def bookName = params["entity"]["name"] (1)
return [
["title" : "Book Record - $bookName"] (2)
]| 1 | 用 params 变量访问不同的外部参数。params["entity"] 表示选择的 book 实例。 |
| 2 | Groovy 脚本需要返回一个 Map 的列表。title 键值对应的就是目标文件名。 |
使用 Groovy 的数据集如下：
从 Books 界面运行报表
另外，我们可以在 book 的浏览界面启用报表运行。首先，我们需要在 book-browse.xml 界面描述中声明一个标准的 ListPrintFormAction：
<actions>
...
<action id="listPrintForm"
type="listPrintForm"
caption="Print details"/> (1)
...
</actions>
...
<buttonsPanel id="buttonsPanel" alwaysVisible="true">
...
<button id="printBtn" action="booksTable.listPrintForm"/> (2)
...
</buttonsPanel>| 1 | type 属性定义特定的 listPrintForm 操作类型。 |
| 2 | 添加一个用来运行报表的按钮。 |
然后，我们需要将报表与 Book 浏览界面关联起来。打开报表编辑界面，切换到 Roles and Screens（角色和界面） 标签页，并从下拉列表中将 Book.browse 界面添加到表格：
现在，可以通过在表格选中任何书籍并单击 Print details 按钮来运行对应的报表。
输出如下：
手动创建报表
本节中，我们将不使用向导创建一个稍微复杂一些的报表。
报表将包含出版物（publications）列表，列表通过文献类型（literature types）和书籍分组。
报表的上半部分包含关于报表创建人的信息以及报表的生成日期。下半部分是展示分组的出版物列表。
报表的配置如下：
-
模板类型：XLSX。
-
报表名称：
Publications grouped by types and books。
创建模板
使用 Microsoft Office 或 LibreOffice 创建一个 Template for publications by type.xlsx 模板。
报表模板需要包含命名区域：主区域的三组数据集（type、book、publisher），表头（tableheader），以及报表的附加信息（header）。
|
报表的模板可以在 Demo 项目中下载： reports/templates。 |
定义报表结构
从应用程序主菜单打开 Reports → Reports 界面，然后点击 Create → New。
会显示报表编辑界面的 报表结构（Report structure） 标签页。
定义报表名称 - Publications grouped by types and books。
点击 Create template（创建模板） 按钮。
在 Template editor（模板编辑） 弹窗中，上传前一步定义的报表模板，并定义输出名称格式（output name pattern）。
下面我们创建报表区域。
-
header 区域包含使用 Groovy 脚本定义的数据集，脚本会输出当前用户的名称和当前日期。
import io.jmix.core.security.CurrentAuthentication; import io.jmix.core.TimeSource; def user = currentAuthentication.getUser().getUsername(); def currentDate = timeSource.currentTimestamp(); return [["generated_by":user, "generated_when":currentDate]] -
tableheader 区域是空的，用来展示表头。
-
type 区域通过运行下列 JPQL 语句输出文献类型：
select b.literatureType.id as typeId, b.literatureType.name as type from jmxrpr_Book b
-
book 区域，是 type 的子区域，运行下列 JPQL 语句输出书籍：
select b.id as bookId, b.name as bookName from jmxrpr_Book b where b.literatureType.id = ${type.typeId}这个查询语句使用了父区域的字段
typeId作为查询参数。框架提供了父子区域之间的依赖。 -
publisher 区域，是 book 的子区域，运行下列 JPQL 语句输出出版物信息：
select bp.publisher.name as publisher, bp.year as year, bp.town as town from jmxrpr_BookPublication bp where bp.book.id = ${book.bookId}这个查询语句使用了父区域的字段
bookId作为查询参数。
最终完成的报表结构如下：
