极速报表：模板及插件

栏目：云星瀚知识作者：金蝶来源：金蝶云社区发布：2024-09-22浏览：1

极速报表：模板及插件

变更记录

产品版本	更新内容	更新日期
V4.0.020	初始版本	2022年05月12日

1 简介

1.1 功能介绍

使用极速报表开发业务报表时，必须继承元数据模板才能实现相关的功能，同时框架对相关的功能进行了封装，开发了一些供业务使用的插件。在实现相关功能时，需要实现相应的方法。下面分元数据模板和插件接口两部分来介绍。

1.2 元数据模板

报表元数据模板：scmc_report_tpl，元数据模板对过滤区域进行了划分，通用过滤、显示设置、合计列有木人的设置，同时配置了模板插件。如下图：

在目标页面添加的任何字段标识，需要注意不能与报表列表控件中动态生成的字段同名，报表列表中字段是动态生成，可能导致冲突。比如：通用过滤加了字段叫org，报表列表显示一列也叫org，可能出现数据显示异常，也可能报错。

关键区域和字段

区域和字段	描述和用法
常用过滤	建议业务报表添加自的定义的过滤字段的区域。可自定义修改。
通用过滤	以字段库字段作为字段数据构建的过滤面板，框架默认会解析传递条件。可自定义修改。
汇总依据	设置汇总的维度字段，及GROUP BY 字段。可自定义修改。
汇总值	设置要参与汇总的数值字段。集SUM字段。可自定义修改。
合计项	合计项可选范围，必须是汇总依据勾选项的子集，根据会合计项，添加合计行。可自定义修改。
显示总计行	开启时，框架会自动根据汇总值字段，增加一行总计行。可自定义修改。
分析模式	默认不可见，已废弃，已调整到报表参数控制。
合计列	固定字段，标识是固定的，用于辅助计算汇总统计。如合计的逻辑。可配合RowSumPlan使用。

1.2 插件及接口

即时报表插件有3类：

1）报表页面控制插件（与平台原生报表一致），用于控制页面交互逻辑，可以有多个，需继承kd.bos.report.plugin.AbstractReportFormPlugin（领域模型插件）；

2）列表查询插件，用于实现数据查询的逻辑，只能配置一个，需继承kd.bplat.scmc.report.core.tpl.AbstractReportQuery （极速报表插件），该插件对查询逻辑进行业务了封装，用于接通配置。子类几乎不用实现任何逻辑。

3）报表计算插件，用于业务控制具体的计算逻辑，实现一定的扩展，可以有多个，需实现kd.bplat.scmc.report.core.tpl.IReportDataHandle（极速报表插件），在对应的报表数据源插件列表中配置，业务大部分逻辑，都在这个插件里实现；

报表的总体思路，可以这样理解：计算报表分为输入层、计算层、输出层，输入层需要的是一些报表的参数，及过滤条件，也可以分为框架的参数，和业务的参数，框架的参数就是通用过滤设置的条件，显示设置的参数等，业务的参数就是自定义的一些常用过滤和自定义的一些特殊参数，都是在输入层完成，即在AbstractReportFormPlugin 实现类控制。输出层则是定义的一些流式计算框架，开放了很多的切口，运行业务将自定义的一些参数在计算前设置好，如自定义的过滤条件。以及业务可以在相应的方式中设置算子达到计算的要求。输出层则无需关注，都是输出到报表页面。

因此在实现相关功能前，应该先思考清楚，自己要加的逻辑是在哪一层控制。而不是以达功能为目的。不合理的设计可能导致业务报表的无法再扩展。

2 开发技巧

2.1 新增报表

报表也是一个元数据，新增方式和其他元数据创建方式一样，选择报表即可。但因跨云无法继承模板，可参考下面方式创建。

1）在开发平台【供应链和制造服务云】—【公共服务模型】—【报表配置】路径下，先创建一个报表数据源，注意需要继承scmc_report_tpl模板。

2）元数据新增完后，将报表元数据导出，在导入到目标应用下即可。后续的修改、发布都在目标应用下完成。

2.2 新增插件

下面是不同插件的配置方式。

1）报表页面控制插件。

2）列表查询插件。

3）报表计算插件。

2.3 接口方法

页面控制插件是领域模型（即平台）的插件，开发人员需先对平台Form插件有所了解。列表查询插件只需要继承出一个子类，几乎不需要修改任何逻辑，因此，这两种插件这里不做介绍。下面重点介绍报表计算插件。

2.3.1 接口：kd.bplat.scmc.report.core.tpl.IReportDataHandle。

setupCtx

设置上下文，通过ctx.get方法获取信息，然后ctx.set相关信息，比如：将Form界面传过来的自定义条件，设置到报表过滤条件中。

handleBlockDataSelectCols

这里只对某个数据块来定义，中间表需要哪些字段，默认逻辑字段是不会自动加载的，根据不同的逻辑需要，添加不同的字段需求。尽量避免全部字段加载。一般是数据源到数据库中间MR算子有需求是才会添加。计算完后，不会影响中间表字段。

handleBigtableCols

这里收集的是中间表需要哪些字段，默认逻辑字段是不会自动加载的，根据不同的逻辑需要，添加不同的字段需求。尽量避免全部字段加载。这里添加后，所有映射的数据库都会识别需要字段，自动加载数据。

注意：这里方法加的字段，默认会传递到handleBlockDataSelectCols中。反之，则没有传递关系。

modifyBlocks

针对实体数据源进行一些设置。ctx是上下文信息，blockCollector是数据源信息集合。比如：代码自定义一个数据块，添加到blockCollector，或通过遍历数据块，在特点的数据块信息中添加过滤条件、添加数据转换器，修改字段映射等。

modifyJoinBlocks

针对关联实体数据源进行一些设置。和modifyBlocks 用法相同。在V5.0.024版本添加的。

transFormAfterUnion

定义在数据块Union完之后，需要执行哪些数据转换器，transCollector.add即可，比如：需要对数量进行拆分为收入、发出等列，在改方法比较合适，因为下一节点就是分组汇总。

beforeGroupData

在分组汇总添加自定义算子前，可以再次对ctx进行信息修改，比如：不想使用标准的分组合计逻辑，可以修改后删除GroupPlan，也可以在setUpdate位置除了。

transFormAfterGroup

定义在数据块分组汇总完之后，需要执行哪些数据转换器，transCollector.add即可。

beforeAddSumRow

在添加汇总行算子前，可以再次对ctx进行信息修改，比如：不想使用标准的分组合计逻辑，可以修改后删除RowSumPlan。

transFormAfterAddSumRow

定义在数据块添加汇总行之后，需要执行哪些数据转换器，transCollector.add即可。

transformResult

定义在AlgoX计算完结果，输出DataSet数据包后，需要执行哪些数据转换器，transCollector.add即可。注意这里要添加的是IDataTransform实现类了。

buildShowColumn

定义报表字段如何显示，比如：增加字段、调整字段的一些定义。Cols是经过框架自动处理完的字段集合。插件修改后再返回。

2.3.2 数据转换接口：kd.bplat.scmc.report.core.tpl.IDataXTransform

doTransform

定义数据是如何转换的，输入DataSetX，返回也是DataSetX，中间可以通果AlgoX标准的流操作方法，或者自定义流操作接口实现类（算子），来完成相关的计算。在编写算子前，请务必先熟悉AlgoX相关的API文档。这里无法挨个介绍。流式计算原理，可以进行百度了解，是非常成熟的技术。下面给一个操作例子。

AlgoX开发文档地址：https://dev.kingdee.com/sub/index/open/detail/sdk/1565335160516249600

2.3.3 数据转换接口：kd.bplat.scmc.report.core.tpl.IDataTransform

该接口和IDataXTransform用法几乎一样，一个用的AlgoX还在AlgoX任务中，后者则是用的Algo，数据已经在服务节点了。

2.3.4 合计方案：kd.bplat.scmc.report.core.transform.plan.RowSumPlan

改方法需搭配kd.bplat.scmc.report.core.transform.func.AddSumRowFunc算子使用。比如：二级的小计行。

sumKeyCols : GroupBy的字段。
sumQtyCols：Sum的字段。
countName：对应模板中合计列字段类型，用于标识哪些行是参与Sum的。
注意Sum字段不能为空，且必现是可计算的字段。

2.3.5 聚合方案：kd.bplat.scmc.report.core.transform.plan.GroupPlan

keyCols : GroupBy的字段。
qtyCols：Sum的字段。
注意Sum字段不能为空，且必现是可计算的字段。

2.3.6 数据转换接口：kd.bplat.scmc.report.core.ReportDataCtx

业务常用方法介绍

方法	描述和用法
setUseDefGroup	设置是否使用默认的聚合方案，等价于setGroupPlans(null)。默认：true。
setUseDefSum	设置是否使用默认的合计行方案，等价于setSumPlans(null)。默认：true。
setShowTotalQty	设置是否计算总计行。自动取报表页面设置。
setShowKeyCols	设置汇总依据字段集，自动取报表页面设置，一般不修改。
setShowQtyCols	设置汇总值字段集，自动取报表页面设置，一般不修改。
setSumKeyCols	设置合计项字段集，自动取报表页面设置，一般不修改。
setSumQtyCols	设置合计数量字段段集，自动取报表页面设置，默认同汇总值，一般不修改。
setSumKeyCols4Count	设置实际参与合计的字段集，自动取报表页面设置，一般不修改。
setSumQtyCols4Count	设置实际参与合计的数量字段集，自动取报表页面设置，默认同汇总值，一般不修改。
setFixedFs	设置固定的过滤条件，过滤字段必须使用字段库字段标识。
setGroupPlans	设置聚合方案，默认使用汇总依据字段聚合。
setSumPlans	设置合计方案，默认使用合计项字段合计一行。
getShowKeyCols	读取设置好的汇总依据字段，一般不修改。
getShowQtyCols	读取设置好的汇总值字段，一般不修改。
getSumKeyCols	读取设置好的合计项字段，一般不修改。
getSumQtyCols	读取设置好的参与合计的汇总值字段，一般不修改。
getSumKeyCols4Count	读取实际参与计算的合计项字段，一般不修改。
getSumQtyCols4Count	读取实际参与计算的参与合计的汇总值字段，一般不修改。
getGroupPlans	读取聚合方案。
getSumPlans	读取合计方案。
getFixedFs	读取固定过滤条件设置，一般通过get后，使用add添加过滤条件。
getCurrentJob	获取单前的AlgoX任务，一般用于额外添加input数据流。
getParam	获取Form界面通过ReportQueryParam.getCustomParam().put()进来的自定义参数。
getCommonFs	获取通用过滤面板设置的过滤条件。
getReportConf	获取单前查询的配置，在setup方法中允许修改。