# dataTransform - 数据加工组件扩展

SuccBI数据加工内置了大量常用的加工组件，如汇总、行转列、列加工等，能满足大部分的数据加工需求，一些个性化加工需求也可以通过SQL组件、脚本组件实现，但是SQL组件、脚本组件不方便复用，每个用到的地方都需要再次编写SQL或者脚本。

数据加工组件扩展组件可以做到和产品内置的加工组件一样的复用，由扩展开发者开发好数据加工组件扩展后，使用者可以像使用内置加工组件一样使用扩展组件。

本文讲述如何开发一个SuccBI数据加工组件扩展。

# 扩展文件结构

package.json 定义扩展的配置信息。
main.action 定义扩展的执行逻辑。

# package.json

每一个扩展都需要在根目录中有一个描述文件package.json。

示例如下：

{
    "name": "template-dataTransform-blank",
	"displayName": "空白模板",
	"icon": "icon-extension",
    "categories": ["data"],
    "version": "1.0.0",
    "thumbnail": "default.png",
    "author": {
        "name": "YourName"
    },
    "contributes": {
        "dataTransform": {
            "inputDataStreamTypes": ["DbTable", "ModelTable", "Stream"],
            "inputDataStreamCount" : "None",
            "outputDataStreamType": "DbTable",
            "properties": {
                "propertyItems":[
                    {
                        "name":"param1",
                        "type":"number",
                        "caption":"参数1",
                        "desc":"说明如何使用参数1"
                    }
                ]
            }
        }
    }
}

详细说明：

在dataTransform属性中描述扩展组件的配置信息，包括下列属性：

inputDataStreamTypes 描述扩展组件可以接受哪些输入节点，是一个json字符串数组，可以设置这些类型：
1. DbTable 数据库表或视图
2. ModelTable 模型表
3. Stream 数据流、
4. Sql SQL查询
inputDataStreamCount 描述此组件可以接受几个输入节点，可以设置如下值：
1. Any 随便是否有输入节点，可以没有也可以有，输入节点只是控制执行顺序，输入节点不能是不落地数据的节点
2. MustOne 必须且只需要一个数据输入节点
3. MustTwo 必须要两个输入节点
4. MustMore 必须需要多个数据输入节点
outputDataStreamType 描述此组件的输出数据类型，可以设置如下值：
1. DbTable 输出数据在一个数据库表或视图中
2. Stream 输出数据是一个数据流
scriptAction 加工逻辑所在的后端脚本，默认是main.action，脚本中有一个onProcessExtensionNode函数。
properties 描述使用这个加工组件时可以设置测选项
1. propertyItems 选项列表，是一个json数组，每个元素说明一个选项的定义，可以包含如下属性：
  1. name 属性名，应该是一个字母组成的标识符，用于在扩展组件运行的时候传递给扩展组件的加工逻辑
  2. type 属性类型，描述用户输入此属性时的输入方式，具体见下文
  3. caption 属性标题，应该是一个简短的描述，如：每月发放月限量
  4. desc 属性描述，可选，一段文字描述如何使用此属性
  5. items 可选值列表，可选，当属性类型是combobox时有效

属性类型可以有如下选项：

filter 过滤条件
number 数字输入
combobox 下拉选项输入
checkbox 勾选框输入
text 文本输入
date 日期输入，支持输入相对日期
field 字段选择下拉框
fields 字段选择下拉框，可以多选字段

# main.action

main.action文件是一个后端脚本文件，定义了数据加工扩展的执行逻辑。

入口函数是onProcessExtensionNode，会在如下2个时机被调用：

用户在数据加工界面中选择使用此扩展组件，并进行数据预览时。
定时调度包含了此扩展组件的加工流程时。

可以直接编辑main.action文件，也可以在SuccIDE或元数据项目设置中通过脚本编辑器直接编辑 ts语法的脚本文件main.action.ts，编辑器会自动编译并生成main.action。

脚本模版：

/**
 * 生成组件的字段结构。
 * 
 * 返回的结果将作为组件的数据面板列头显示，只在加工设计器阶段有效，加工保存后会把这个信息物化下来，
 * 在提取时执行这个方法，结果将只用于和节点字段映射，确定每行数据对应的字段顺序。
 * 
 * 有些场景字段结构是和数据一起产生的，比如解析JSON，出于性能考虑开发者可以只实现 {@link #onProcessData()} 方法
 * 使用 {@link IDataFlowScriptNodeContext.getOutput()} 获取组件输出对象，同时设置字段信息和数据信息。 
 * @see FlowScriptNodeOutputData.setFields
 * 
 */
export function onProcessFields(): DwTableFieldInfo[] {
	return null;
}

/**
 * 生成组件数据。
 * 
 * 数据加工设计器预览数据时会显示这个结果，加工启用提取后也会将产生的数据写入到目标表中。
 * 
 * 支持流式输出和输出表两种模式：
 * 
 * 1. 需要逐行处理数据并写入时可以选择流式写入，支持超大数据量的迁移。
 * 2. 也可以在方法内部将数据处理好并产生数据库表，输出一个表或一段sql。
 * 
 * 两种模式都不影响组件后继续添加列加工、关联等常规组件，数据加工会根据输出结果自动转换并处理。
 * 
 * @see IDataFlowScriptNodeContext.getOutput
 * @see FlowScriptNodeOutputData.setDbTableInfo
 * @see FlowScriptNodeOutputData.writeRow
 * 
 * 需要注意的是，设计器界面数据预览时会等待这个方法执行结束，处理时间过长会阻塞设计器界面的数据预览，
 * 开发者通过 {@link IDataFlowScriptNodeContext.isPreview} 判断是否是预览状态，处理少量数据，提高数据预览效率。
 * 
 * @param context 
 */
export function onProcessData(context: IDataFlowScriptNodeContext): void {

}

# 示例

aninationEffect

fappComponent

0条评论