com.finebi.provider.api.component.CustomComponentProvider

一、特殊名词介绍

无

二、背景、场景介绍

CustomComponentProvider支持插件自定义组件（图表）。

三、接口介绍

后端接口

CustomComponentProvider.java

package com.finebi.provider.api.component;

import com.finebi.common.context.OperationContext;
import com.finebi.provider.api.component.data.DataModel;
import com.fr.common.annotations.Open;
import com.fr.stable.fun.mark.Mutable;
import com.fr.web.struct.AssembleComponent;

import java.util.List;

/**
 * <p>插件自定义组件（图表）的注册点</p>
 *
 * @author Jimmy.Zheng
 * @since 6.0
 * Created on 2023/5/22
 **/
@Open
public interface CustomComponentProvider extends Mutable {
    String XML_TAG = "CustomComponentProvider";

    int CURRENT_LEVEL = 1;

    /**
     * 获取组件的名称
     *
     * @return 组件名称
     */
    String getName();

    /**
     * 获取组件的类型，建议英文
     *
     * @return 组件类型
     */
    String getType();

    /**
     * 获取组件的图标
     *
     * @return 图标路径
     */
    String getIcon();

    /**
     * 获取组件的预览大图标
     *
     * @return 图标路径
     */
    String getPreviewIcon();

    /**
     * 获取组件编辑界面的html
     *
     * @param context 上下文
     * @return html
     */
    String getEditPageHTML(OperationContext context);

    /**
     * 获取组件编辑界面的css和 js
     *
     * @param context 上下文
     * @return css和 js的路径包装
     */
    AssembleComponent editClient(OperationContext context);

    /**
     * 获取组件预览界面的html
     *
     * @param context 上下文
     * @return html
     */
    String getPreviewPageHTML(OperationContext context);

    /**
     * 获取组件预览界面的css和 js
     *
     * @param context 上下文
     * @return css和 js的路径包装
     */
    AssembleComponent previewClient(OperationContext context);


    String config();

    /**
     * 返回是否需要进行自定义数据处理
     *
     * @param customComponentContext 自定义图表相关的上下文信息，目前包含前端传的查询配置
     * @return 是否需要进行自定义数据处理
     */
    boolean needDataProcess(CustomComponentContext customComponentContext);

    /**
     * 对BI计算后即将返回前端的数据进行自定义处理
     *
     * @param dataModels             数据模型
     * @param customComponentContext 自定义图表相关的上下文信息，目前包含前端传的查询配置
     * @return 处理过的数据模型
     */
    List<DataModel> process(List<DataModel> dataModels, CustomComponentContext customComponentContext);
}

前端接口

bi.plugin.client.ts

import { BIPluginAction, BIPluginMessage } from '@webui/bi/plugin/bi.plugin.constant';

export class BIPluginClient {
    private connID: string | null = null;

    /**
     * data：如果是保存过的，这里直接填入开发者保存的信息，新建的话这里为null
     * config：配置信息，比如提供所在模板等环境类信息，未来属性拓展也主要会放在这里
     * saveSessionCallback(data: Object): Promise保存回调函数，入参为保存的json对象，返回值为Promise对象，返回保存成功或失败状态
     * closeSessionCallback：调用该接口会结束当前页面会话，把主动权交给BI
     * @param render
     */
    public init(
        render: (
            data: any,
            config: any,
            saveSessionCallback: (data: any) => Promise<any>,
            closeSessionCallBack: () => void,
            extensionCallback?: (action: string, value: any) => void
        ) => void
    ): void {
        addEventListener('message', (event: MessageEvent) => {
            if (event.source === window.parent && event.data) {
                const eventData = JSON.parse(event.data);
                if (!this.connID && eventData.action === BIPluginAction.INIT) {
                    this.connID = eventData.connID;
                } else {
                    if (this.connID === eventData.connID && eventData.action === BIPluginAction.RENDER) {
                        const { data, config } = eventData;
                        render(
                            data,
                            config,
                            this.saveSessionCallback.bind(this),
                            this.closeSessionCallback.bind(this),
                            this.extensionCallback.bind(this)
                        );
                    }
                }
            }
        });
    }

    private sendMessage(action: BIPluginAction, data: any, config?: any) {
        if (this.connID) {
            const message: BIPluginMessage = { connID: this.connID, action, data, config };
            parent.postMessage(JSON.stringify(message), '*');
        }
    }

    private saveSessionCallback(data: any): Promise<any> {
        return new Promise(resolve => {
            const saveListener = (event: MessageEvent) => {
                if (event.source === window.parent && event.data) {
                    const eventData = JSON.parse(event.data);
                    if (this.connID === eventData.connID && eventData.action === BIPluginAction.SAVE_COMPLETE) {
                        removeEventListener('message', saveListener);
                        resolve(eventData.data);
                    }
                }
            };
            this.sendMessage(BIPluginAction.SAVE, data);
            addEventListener('message', saveListener);
        });
    }

    private closeSessionCallback(): void {
        this.sendMessage(BIPluginAction.CLOSE, null);
    }

    private extensionCallback(action: string, value: any) {
        this.sendMessage(action, value);
    }
}

// @ts-ignore
window.BIPlugin = BIPluginClient;

图表配置

图表配置分为两部分，默认配置和自定义配置。

自定义配置分为组件样式和图表属性区域的自定义配置（config.json中配置，支持固定的几种类型）和图表编辑区域的自定义配置（可以理解成自定义的json配置，配置界面可以自定义）。

图表数据

图表数据主要存在dataModel中，主要的内容有字段数据（fileds）和按列存储的二维表数据（colData）。

数据格式转化：日期字段格式转换后的数据，数值字段格式配置，均存放在dataModel的fields配置里。

四、支持版本

产品线	版本	支持情况	备注
BI	6.0.13-	支持

五、插件注册

plugin.xml

<extra-core>
    <CustomComponentProvider class="your class name"/>
</extra-core>

六、原理说明

注册逻辑的实现主要在FinePluginService的实现类中，相关方法：

com.finebi.common.api.service.plugin.FinePluginService#getCustomComponentPage获取自定义图表预览界面html；

com.finebi.common.api.service.plugin.FinePluginService#getAllCustomComponentInfo获取自定义图表图标，name等信息。

七、特殊限制说明

目前尚未支持移动端、后台导出、数据脱敏等场景。

八、常用链接

demo地址：plugin-bi-custom-chart-demo

九、开源案例

免责声明：所有文档中的开源示例，均为开发者自行开发并提供。仅用于参考和学习使用，开发者和官方均无义务对开源案例所涉及的所有成果进行教学和指导。若作为商用一切后果责任由使用者自行承担。

Page tree