开始使用

本章节包含使用向导创建并运行报表的说明。为了方便使用，报表扩展组件自带报表向导，这是一个用于快速创建报表的可视化工具，支持报表数据结构和模板设计。

项目配置

安装扩展组件

首先，新建一个 Jmix 应用程序，并按照说明安装报表和图表扩展组件。

创建实体和界面

作为示例，我们创建一个图书馆（Library）应用程序，包含几个实体。

创建 Author 实体，具有下列属性：
- firstName，为 String 类型。
- lastName，为 String 类型。
创建 LiteratureType、Publisher、LibraryDepartment 和 Town 实体，每个实体都仅包含一个 name 属性：
- name，为 String 类型。
创建 Book 实体，具有下列属性：
- name，为 String 类型。
- summary 为 String 类型，长度无限制。
- literatureType 关联至 LiteratureType 实体，多对一关系。
- authors 关联至 Author 实体，多对多关系。
创建 BookPublication 实体，具有下列属性：
- year，为 Integer 类型。
- book 关联至 Book 实体，多对一关系。
- publisher 关联至 Publisher 实体，多对一关系。
- town 关联至 Town 实体，多对一关系。
创建 BookInstance 实体，具有下列属性：
- isReference，为 Boolean 类型。
- inventoryNumber，为 Long 类型。
- bookCount，为 Integer 类型。
- bookPublication 关联至 BookPublication 实体，多对一关系。
- libraryDepartment 关联至 LibraryDepartment 实体，多对一关系。
对于上面创建的所有实体，都分别为其创建浏览和编辑界面。

启动应用程序并为每个实体添加一些数据。在后续步骤中我们将使用这些数据。

通过点击 Reports（报表） 界面中 Create（新建） → Using wizard（向导） 打开向导界面。

Figure 1. 调用向导界面

使用向导可以创建三种类型的报表：

单个实体的报表。
实体列表的报表。
通过查询过滤的实体列表的报表。

报表设计分为三个步骤：

创建报表的数据结构。
编辑报表区域。
保存报表。

可以使用报表编辑器以常规方式修改向导创建的报表，并通过通用报表浏览界面运行，或使用特定的操作（ListPrintFormAction、EditorPrintFormAction 等）运行。

单一实体报表

假设我们想获取有关图书的详细出版信息，即 BookPublication 实体的实例。

首先，运行报表向导并指定报表详细信息：

Entity（实体） - 报表中展示的实体 - BookPublication.
Template type（模板类型） - 报表的模板格式，也是报表的输出格式 - DOCX。这里也可以使用 XSLX、HTML、CSV 和 Chart 格式。
Report name（报表名称） - Publication details。

接下来，指定报表类型：Report for single entity（单一实体报表）。

Figure 2. 单一实体报表：第一步

然后单击 Next（下一步） 按钮，出现 Select attributes for the simple report region（为简单报表展示区选择属性） 窗口。指定 BookPublication 实体和应该在体现在报表中的相关实体的属性（Publication.Book.Name、Publication.Publisher.Name、Publication.Year 和 Publication.Town.Name）。请在左列中选择属性并通过单击 attributes selection arrow 按钮或双击属性将它们移动到右侧。

报表中属性的顺序将对应于右侧列表中指定的顺序。要更改显示顺序，请单击 attributes selection up / attributes selection down 上下移动属性。

Figure 3. 单一实体报表：选择实体属性

单击 OK 进入第二步 - 报表区域编辑。

出现的界面包含一个命名区域列表，这些区域是用来显示相关数据。向导支持向模板中添加多个纯文本区域，以显示不同的数据集。

加载到特定区域的实体属性列表可以通过单击属性列表链接来修改。还可以通过单击 Add simple region（添加简易展示区） 来添加新区域。

如果实体包含集合属性，则会出现 Add tabulated region（添加表格展示区） 按钮。可以添加显示表格数据的区域。

在这两种情况下，选择对话框将显示 BookPublication 实体的属性列表，允许添加或删除集合中的属性。

Figure 4. 单一实体报表：第二步

到这一步，我们已经可以运行并查看报表。单击 Run（运行） 按钮，选择 BookPublication 实例并查看结果。

Figure 5. 测试运行

配置完所有报表区域后，可以进入第三步：保存报表。此时，可以查看完整的报表模板，或将输出文件的名称和格式更改为其他任意支持的类型。

Figure 6. 报表输出类型

单击 Save（保存） 按钮后，将出现标准报表编辑界面。现在，可以按常规方式微调报表。编辑完成后，在报表编辑界面单击 Save and close（保存并关闭）。

该报表现已添加到报表浏览界面中的 General 分组，可以通过单击 Run（运行） 按钮来运行该报表。

Figure 7. 报表浏览

此外，我们可以在 publications 浏览界面上调用报表运行功能。为此，我们将在 book-publication-browse.xml 界面描述中声明一个标准的 ListPrintFormAction：

<actions>
    <action id="list" type="listPrintForm" caption="msg://printDetails"/> (1)
</actions>
<buttonsPanel id="buttonsPanel" alwaysVisible="true">
    <button id="list" action="bookPublicationsTable.list"/> (2)
</buttonsPanel>

1	`type` 属性定义特定的 `listPrintForm` 操作类型。
2	添加运行报表操作的按钮。

然后我们应该将报表与 BookPublication 浏览界面关联起来。打开报表编辑界面，切换到 Roles and Screens（角色和界面） 标签页，并从下拉列表中将 BookPublication.browse 界面添加到表格：

Figure 8. 添加界面

现在，可以通过在表格选中 publication 并单击 Print details 按钮来运行对应的报表。

Figure 9. 打印详情

运行结果如下：

Figure 10. 运行结果

实体列表报表

报表向导支持为实体实例列表创建两种类型的报表：

手动选择一组特定实体实例的报表
由某个请求筛选的实体实例报表。

来看看第一种报表类型。假设想要获取图书馆中所有书籍实例（BookInstance 实体）的列表，列表项中包含书籍的名称和所属类目。

在 Reports（报表） 界面点击 Create（新建） → Using wizard（向导），设定下列信息：

Entity（实体） - 报表实体 - BookInstance。
Template type（模板类型） - 输出格式 - XSLX。
Report name（报表名称） - 报表名称 - Book items location。

然后，选择报表的类型（Report for list of entities（实体列表报表）），然后单击 Next（下一步）。

Figure 11. 实体列表报表：第一步

按照我们定的任务要求，在属性选择窗口中选择 BookItem.Publication.Book.Name 和 BookItem.LibraryDepartment.Name。

Figure 12. 实体列表报表：选择实体属性

单击 OK 并进入第二步，进行报表带区编辑。

用于实体列表的报表模板限制只能有一个以表格形式显示数据的区域。虽然不允许添加新区域，但可以通过单击包含属性列表的链接来编辑现有数据集，或者删除现有区域并重新创建。

目前，不需要进行任何更改。单击 Next → Save（保存） 保存报表。该报表在报表编辑界面中显示如下：

Figure 13. 报表数据结构

一旦报表保存成功，就可以从通用报表浏览界面运行报表。

此外，可以添加一个按钮来从书籍条目浏览界面运行报表，通过单击出版物浏览界面中的 Show items 按钮打开该界面。为此，将书籍实例表格的 multiselect 属性设置为 true，以便能够为报表指定一组记录，然后声明一个标准的 ListPrintFormAction：

<table id="bookInstancesTable"
       width="100%"
       dataContainer="bookInstancesDc"
       multiselect="true"> (1)
    <actions>
        <action id="list" type="listPrintForm" caption="msg://printList"/> (2)
    </actions>
    <buttonsPanel id="buttonsPanel"
                  alwaysVisible="true">
        <button id="listBtn" action="bookInstancesTable.list"/> (3)
    </buttonsPanel>

1	使用 `multiselect` 模式。
2	`type` 属性定义特定的 `listPrintForm` 操作类型。
3	添加运行报表操作的按钮。

然后我们需要将 Book items location 报表和书籍浏览界面相关联。打开报表编辑器，切换到 Roles and Screens（角色和界面） 标签页从界面下拉列表选择 BookInstance.browse 并添加至表格中：

Figure 14. 添加界面

现在，可以从书籍条目浏览界面运行。在 BookInstances 界面选择表格中需要生成报表的条目然后点击 Print list（打印列表） 按钮。Print selected（打印已选） 选项会导出选中的条目，Print all（打印全部） 会导出当前过滤器选中的所有实例。

Figure 15. 打印选中记录

输出如下：

Figure 16. 报表结果

过滤实体列表报表

现在看一下向导提供的最后一种报表类型：通过查询语句过滤出的实体列表的报表。要演示这种报表类型，可以在前一个示例的基础上进行修改。和前一个示例一样，报表包含一个书籍列表（包括其标题和归属类目），但仅输出特定日期之后添加的书籍。

点击 Reports（报表） 界面中 Create（新建） → Using wizard（向导），并配置：

Entity（实体） - 报表实体 - BookInstance。
Template type（模板类型） - 输出文件格式 - XSLX。
Report name（报表名称） - Recently added book items。

然后选择 Report for list of entities, selected by query（实体列表报表，由查询语句选择） 报表类型。

Figure 17. 查询语句过滤的实体列表报表：第一步

单击 Next 移至 BookInstance 属性选择界面。我们将 BookItem.Publication.Book.Name 和 BookItem.LibraryDepartment.Name 属性移到右边。单击 OK 完成第一步。

Figure 18. 选择实体属性

目前，不需要进行任何更改。点击 Next。

Figure 19. 报表区域

出现 JPQL Query（JPQL 语句） 窗口。在 Query（查询语句） 字段展示根据在第一步选择的实体和属性自动生成的 JPQL。

要添加新查询条件，可以直接在 Query（查询语句） 字段添加，或者点击 Create（新建） 按钮。例如，我们在 Query（查询语句） 添加一个 where e.createdDate >= :createDt 条件，然后点击 Generate（自动生成） 按钮生成查询参数。

Figure 20. 报表查询语句设置

或者，点击 Create（新建） 按钮添加参数，然后修改 JPQL 语句使用参数：

Figure 21. 创建查询参数

设置好 JPQL 和参数后，点击 Next。然后在下一个弹窗点击 Save（保存）。

Figure 22. 保存报表

在报表编辑器中，可以通过添加新的带区和数据集，以及配置报表模板、本地化和访问权限来创建更复杂的报表。

例如，可以切换到 Parameters and formats（参数和格式） 标签页并修改 Parameters（参数） 列表中的查询参数：使用 Create After 替换标准的 CreateDt。保存更改并关闭报表编辑界面。

Figure 23. 参数和格式标签页

执行完上述操作后，直接在 departments 浏览界面添加运行报表的 Run report 按钮。

为此，需要在 library-department-browse.xml 界面描述中定义一个新的 RunReportAction 标准操作以及一个按钮：

<actions>
    <action id="run" type="runReport"/> (1)
</actions>
<buttonsPanel id="buttonsPanel"
              alwaysVisible="true">
    <button id="runReportBtn"
            action="libraryDepartmentsTable.run"
            caption="Run Report"/> (2)
</buttonsPanel>