外部系统集成前端SDK工具包

前端SDK工具包

前端SDK工具包

数据服务/cboard-common

cboard-common 依赖包含:

  • 所有restful请求服务接口
  • 数据转换服务
  • 工具包
  • 部分业务对象BO定义

包含下列模块:

名称说明
_axiosHTTP 请求单例
commonService基础服务
loginService登录认证服务
adminService用户角色管理服务
datasourceService数据源管理服务
datasetService数据集管理服务
widgetService组件管理服务
boardService仪表板管理服务
dashboardService仪表盘服务
dataService数据处理服务
jobService任务管理服务
metaService元数据管理服务
folderService文件夹管理服务
chartConf图表配置
DateUtil日期工具

Business Object

名称说明
Widget图表BO

CommonService

CommonService 包含一些基础服务方法, 对外主要包含以下两个方法

方法名说明参数返回值
getBaseServerUrl()获取基础服务器 URL无String
setBaseServerUrl(url)设置基础服务器 URLBI服务器地址, 确保Restful服务请求之前设置一次无
export declare class CommonService {
    getBaseServerUrl()
    setBaseServerUrl(url)
}
import {commonService} from 'cboard-common';

commonService.setBaseServerUrl('http://localhost:8026/cboard');

LoginService

登陆认证服务

export declare class loginService {
    isSDK: Boolean
    getTokenInfo(key)
    getToken()
    getUserName()
    getUserId()
    auth(username, password)
    authDigest(username, password)
    authByJwtToken(token)
    authByShareId(shareId)
}
方法名/属性说明参数返回值
isSDK属性: 是否为 SDK 模式默认: false, 设置为 true 防止登录失败跳转 BI 登录页面boolean
getTokenInfo(key)获取指定 Token 信息key - Token 键名Token 信息对象
getToken()获取当前 Token无string(Token 字符串)
getUserName()获取当前用户名无string(用户名)
getUserId()获取当前用户 ID无string(用户ID)
auth(username, password)后端服务请求,进行用户名密码认证username - 用户名,password - 密码Promise(AuthResult)
authDigest(username, password)进行 MD5 加密密码认证username - 用户名,password - 密码Promise(AuthResult)
authByJwtToken(token)使用 JWT Token 认证token - JWT 令牌Promise(AuthResult)
authByShareId(shareId)使用看板分享 ID 认证shareId - 分享 IDPromise(AuthResult)
import { loginService } from 'cboard-common';

loginService.isSDK = true;
loginService.auth('admin', 'root123').then(res => {
    console.log(res)
    const {valid, token} = res.data;
    if (valid) {
       console.log(res)
       this.token = token;
    }
});

AuthResult

public class AuthResult {
  boolean valid;
  String token;
  User user;
  String msg;
}

WidgetBO

export class Widget {
  constructor(args) {
    let {name} = args || {};
    Object.assign(this, {
      name,
      data: {
        datasetId: null,
        datasource: null,
        query: {
          _sid: randomId(),
        },
        config: {
          chart_type: 'table',
          selects: [],
          keys: [],
          groups: [],
          values: [
            {series_type: null, name: '', cols: []}
          ],
          filters: [],
          option: {},
          calColumns: [],// 图表级计算字段
        },
        expressions: [], // 图表级表达式
        filterGroups: [], // 图表级过滤组合
        variables: [], // 图表级变量
      }
    });
  }
}
属性说明后续简称
datawidget的配置数据WidgetConfig
data.config多维查询配置/图表配置ChartConfig
import { Widget } from 'cboard-common';
new Widget();

WidgetConfig

class WidgetConfig {
  // 数据源查询配置
  datasetId: null;
  datasource: null;
  query: { _sid: randomId, };
  // 多维查询配置/图表配置
  config: ChartConfig
  // 图表级表达式
  expressions: [];
  // 图表级过滤组合
  filterGroups: [];
  // 图表级变量
  variables: []; 
}

ChartConfig

多维查询配置/图表配置

class ChartConfig {
  String chart_type;
  List<Dim> keys;
  List<Dim> groups;
  List<Dim> filters;
  List<Value> values;
  Object option = new Object();
  calColumns: [];// 图表级计算字段
}
// 维度
class Dim {
  //String sid; // 在DSL中唯一id
  //如果需要使用层级下钻功能,id必须与维度层级下面的维度相对应
  String id; // 数据集节点id
  String rawDataType; // 原始数据类型
  String alias; // 字段别名
  @required
  String column; // 字段
  String dateFormat; // 日期字段格式化, 与Java中日期格式化对应
  FilterType type; // 过滤类型  3.1中 <filterType> 类型
  List<Object> values; // 比较值 参照3.1 过滤之数组 <filterValues>
  String sort = "asc"; // 维度值排序 ['asc', 'desc']
}

// 指标栏
class Value {
  String sort = "asc"; // 维度值排序 ['asc', 'desc']
  // 双轴图: 'line', 'arealine', 'stackline', 'percentline', 'bar', 'stackbar', 'percentbar'; 
  // 饼图: 'pie', 'coxcomb', 'doughnut'
  String series_type; 
  List<Metric> cols; // 指标列
}

// 与SQL中的聚合函数类似 `aggregate_type(col)`
class Metric  {
  String sid; // 在DSL中唯一id
  String id; // 数据集节点id
  String alias; // 数据集节点.a 可以修改为新的名称
  AggType aggregate_type; // 汇总类型, 聚合函数
  @required
  String col; // 数据集节点.column
  String f_type; // 过滤类型 枚举 只能选择3.1中 <filterType> 类型
  ValueType valueType; // 值显示方式
  List<Object> f_values;
  @required
  String type; // 数据集节点.t
  String exp; // 非必须, String, 汇总表达式, measure 的 exp 属性
}

/**
- <filterValues>: 过滤值数组,与<filterType>组合形成过滤条件,数组中多余的值会被忽略,如
- <dateFormat>: String, 日期格式化, 当 字段 为 'date' 类型时,可以对字段进行格式化 Pattern列表:
  - yyyy,年,2025
  - Q,季度, 1-4
  - MM,月,01-12
  - dd,日,01-31
**/
enum FilterType {
  // 等值与不等值 相当于sql中的`in`与`not in`
  '=', '≠'
  // 开区间
  '≥', '≤',
  // 闭区间
  '[a,b]', // 相当于sql中的between
  'like', 'not like'
}

enum AggType {
  sum, min, max, avg, distinct
}

enum ValueType {
  value, //原始值
  percentByColumn, // 列占比, 行维度方向上计算占比
  percentByRow, // 行占比, 列维度方向上计算占比
  percentByTotal, // 总占比
  row_number, // 序号
  cum_cum, // 累加
  cum_sum_% // 累加占比
}

DataService

方法名/属性说明返回值
newChartConfig()新建组件配置图表组件配置对象
linkDataset(args)关联数据集更新图表配置Promise()
replaceWgtCfgVariable(widgetConfig)替换组件配置变量Promise(replacedWgtCfg)
setEnvVariables(variables, clean)设置环境变量无
deleteEnvVariables(envArr)删除环境变量无
getVariables(args)获取变量列表变量列表
getDimMembers(args)获取维度成员Promise(维度成员数据)
getColumnStat(args)获取列统计信息Promise(统计数据)
directQuery(datasourceId, query, opt)直接查询数据Promise(查询结果)
getDetailData(args)获取明细数据Promise(明细数据)
downloadDetailData(args)导出明细数据到ExcelPromise()
queryDefer(chartConfig)查询检查配置是否符合图表配置要求Boolean
queryBasicAggData(args)查询基本二维聚合数据表格Promise(二维聚合数据)
getDataSeries(args)获取多维数据序列Promise(数据序列)
viewQuery(args)预览生成的查询脚本Promise(String[])
getColumns(args)获取查询字段Promise(字段列表)
export declare class DataService {
    newWidgetConfig()
    // @ts-ignore
    linkDataset(args)
    replaceWgtCfgVariable(widgetConfig)
    // 环境变量设置
    setEnvVariables(variables: Object, clean: boolean)
    getVariables(chartConfig)
    // 获取维度成员信息
    getDimMembers(args)
    getColumnStat(args)
    // @ts-ignore
    directQuery(datasourceId, query, opt)
    queryForList(args)
    getDetailData(args)
    downloadDetailData(args)

    queryDefer(chartConfig)
    queryAggData(args)
    queryBasicAggData(args)
  
    getDataSeries(widgetConfig)
    viewQuery(args)
  
    getColumns(args)
    getColumnsByWidgetId(widgetId)
  
    castRawData2Series(aggData, chartConfig, sortCfg)
  
    getAllDimensions(datasetId, datasourceId, query)
}

replaceWgtCfgVariable

替换widgetConfig中的keys、groups、values中的环境变量模板

dataService.replaceWgtCfgVariable({
  // 省略其他属性
  keys: [{
    column: 'month',
    type: '=',
    values: ['${cdt.now(), "yyyy-MM-dd"}']
  }]
}).then(res => {
  
});
res = { column: 'month', type: '=', values: ['2025-04-02'] }

setEnvVariables

// 设置环境变量
dataService.setEnvVariables({foo: 'bar', key: 1, dateRange: ['2025-01-01', '2025-04-05']});

getVariables

/** 获取环境变量
 * @param vars 赋值优先级最高变量
 * @param objectResult 是否以对象形式返回,默认返回字符串
 * @returns {{}|string}
 */
function getVariables(vars, objectResult = false) {  }
// 设置环境变量
dataService.setEnvVariables({foo: 'bar', key: 1, dateRange: ['2025-01-01', '2025-04-05']});
// 返回对象 {foo: 'bar', key: 3, dateRange: ['2025-01-01', '2025-04-05']}
dataService.getVariables({key: 3}, true);
// 返回对象字符串 "{foo: 'bar', key: 2, dateRange: ['2025-01-01', '2025-04-05']}"
dataService.getVariables({key: 2});

getDataSeries

dataService.getDataSeries({
  widgetConfig: {
    datasetId: 1,
    // chartConfig
    config: {
      chart_type: 'table',
      keys: [{
        column: 'the_year',
      }],
      groups: [{
        column: 'sales_country'
      }],
      filters: [],
      values: [{
        cols: [{
          aggregate_type: 'sum',
          col: 'store_sales',
        }]
      }],
      option: {},
    }
  }
}).then(seriresData => {
  this.jsonData = seriresData;
}).catch(e => {
  this.jsonData = e;
})

Series 返回数据结构描述

{
  "keys": [...],
  "groups": [...],
  "metrics": [...],
  "series": [...],
  "data": [...],
  "seriesConfig": {...},
  "chartConfig": {...},
  "pivotModel": {...},
  "keyInfos": [...],
  "groupInfos": [...],
  "aggData": {...},
  "drill": {...}
}
字段名类型描述示例值/结构
keys二维数组年份维度数据,每个子数组为行维对应的一行数据[[2021],[2022],[2024],[2023],[2020],[2025]]
groups二维数组国家/地区分组,每个子数组列维对应的一列数据[["USA"],["Mexico"],["Canada"]...]
metricsstring[]指标名称["store_sales","store_sales",...]
series二维数组系列名称 groups + series[["USA","store_sales"], ["Mexico","store_sales"], ...]
data二维数组列结构的数据, 每个子数组为一列数据可与series对应[[123,132,...], [771,827,...], ...]
keyInfos二维数组keys的对象数组[[{"col":"the_year","value":2021}], ...]
groupInfos二维数组groups的对象数组[[{"col":"sales_country","value":"USA"}], ...]
aggDataobject聚合后的原始数据见下方详细结构
seriesConfigobject系列配置对象,key为系列名见下方详细结构
chartConfigobject返回最终图表基础配置, 必要时SDK会对用户传入ChartConfig调整与加工
pivotModelobject数据透视表模型(包含与根对象重复的 keys/data/seriesConfig 等字段)结构同根对象对应字段

aggData 原始聚合数据

字段名类型描述示例值/结构
columnListObject[]字段描述数组对象
data二维数组行结构二维数组[[ "Canada", "F", 2021, 60237.11 ],...]
subData子集行列汇总、小计下推数据源时产生

seriesConfig 系列对象

{
   [系列名]: {
      seriesName: '',
      seriesIdx: 0,
      data: [], // 系列数据
      valueConfig: {}, // 指标配置
      groupInfos: [], // 列维信息数组
   },
   ...
}

viewQuery

dataService.viewQuery({
  widgetConfig
}).then(res => {
  // res为查询脚本数组
  // ['sql1', 'sql2']
})

getDetailData

dataService.getDetailData({
    widgetConfig,
    resultLimit, // 查询结果集大小限制,默认: 2000
}).then(res => {
    
}).catch(e => {
  // 异常处理
})

res 返回数据结构

{
  data: {
    columnList: [{}, ...], // 字段对象
    data: [["United States of America", "F", 2021, "#NULL"], ...], // 二维数据
    count: 55264, // 总记录数
    detail: true,
  },
  chartConfig: {...},
}

getDimMembers

维度成员查询

dataService.getDimMembers({
  datasetId: 1,
  dimCfg: { column: 'sales_country' }, // dimCfg可以是对象或者字段字符串
  // dimCfg:'sales_country', 
  keywords: 'a' // 关键词限定,模糊查询值中包含字母a的成员
}).then(res => {
  // 返回 [{value: 'Canada'}, {value: 'Mexico'}]
})

其他字段限定/级联限定

查询 'sales_country' 下面 'sales_region' 成员

dataService.getDimMembers({
  datasetId: 1,
  dimCfg: { column: 'sales_region' }, // dimCfg可以是对象或者字段字符串
  chartConfig: {
    keys: [{
      id: '8clz4jnwc',
      column: 'sales_country',
      type: '=',
      values: ['Canada']
    }],
  }
}).then(res => {
  // 当前返回值为Ajax原始的Response对象,后续版本迭代可能会做解构操作
});

getColumnStat

获取指标字段的最小值、最大值、平均值、记录数信息

dataService.getColumnStat({
  datasetId: 1,
  dimCfg: { column: 'store_sales' }, // dimCfg可以是对象或者字段字符串
}).then(res => {
  this.jsonData = res.data;
})

返回

{
  "min": 0.5,
  "max": 49.99,
  "avg": 8.31538858,
  "count": 55265
}

directQuery

位置参数参数类型说明样例
datasourceIdLong数据源ID1
queryString查询脚本查询对象需要与数据源匹配
optObject其他参数{ resultLimit = 2000, variables }
dataService.directQuery(1,
  'select * from department',
  {
    resultLimit: 5, 
    variables: {foo: 'bar'}, // 环境变量
  }
).then(res => {
  res.data;
});
{
  "data": [
    [ 1, "HQ General Management" ],
    [ 2, "HQ Information Systems" ],
    ...
  ],
  "columns": [
    {
      "columnName": "DEPARTMENT_ID",
      "remarks": null,
      "dataType": null,
      "typeCategory": null,
      "innerTypeName": null,
      "type": "INT",
      "ordinalPosition": null
    },
    {
      "columnName": "DEPARTMENT_DESCRIPTION",
      "remarks": null,
      "dataType": null,
      "typeCategory": null,
      "innerTypeName": null,
      "type": "STRING",
      "ordinalPosition": null
    }
  ],
}

AdminService

方法名/属性说明参数返回值
changePwd(user)修改用户密码user: objectPromise(ServiceStatus)
getUserDetails()获取用户详情无Promise(用户详情对象)
getUserList()获取用户列表无Promise(用户列表)
getUserRoleList()获取用户角色列表无Promise(角色列表)
getRoleList()获取角色列表无Promise(角色列表)
getRoleResList()获取角色资源列表无Promise(资源列表)
grantUserRoles(userIds, roleIds)授予用户角色userIds: string[], roleIds: string[]Promise(ServiceStatus)
revokeRoleOfUser(userIds, roleIds)撤销用户角色userIds: string[], roleIds: string[]Promise(ServiceStatus)
shareResources(roleIds, resIds)共享资源roleIds: string[], resIds: string[]Promise(ServiceStatus)
updateRoleRes(roleIds, resIds)更新角色资源roleIds: string[], resIds: string[]Promise(ServiceStatus)
isAdmin()当前用户是否为Admin无Promise(boolean)
newUser(user)新建用户userPromise(ServiceStatus)
updateUser(user)更新用户userPromise(ServiceStatus)
deleteUser(userId)删除用户userIdPromise(ServiceStatus)
handoverAcl(srcUserId, toUserId)权限交接srcUserId, toUserIdPromise(JSONObject)

export declare class AdminService {
    changePwd(user)
    getUserDetails()
    getUserList()
    getUserRoleList()
    getRoleList()
    getRoleResList()
    grantUserRoles(userIds, roleIds)
    revokeRoleOfUser(userIds, roleIds)
    shareResources(roleIds, resIds)
    updateRoleRes(roleIds, resIds)
    grantRoleRes(roleIds, resources)
    revokeRoleRes(roleIds, resources)
    updateUserRes(userIds, resIds)
    grantUserRes(userIds, resIds)
    revokeUserRes(userIds, resIds)
    getAllUserResList()
    newUser(user)
    updateUser(user)
    deleteUser(userId)
    newRole(role)
    updateRole(role)
    deleteRole(roleId)
    isAdmin()
    getJobList()
    handoverAcl(srcUserId, toUserId)
    getResUserList(resType, resId)
}

DatasourceService

数据源相关API

specFolderId 选填参数,获取指定目录下面的资源

方法名/属性说明返回值
getById(id)获取数据源Promise(数据源对象)
getDatasourceList(lite, specFolderId?)获取数据源列表Promise(数据源列表)
getDatasourceTreeData(specFolderId?)获取数据源树形数据Promise(树形数据)
new(datasource)新建数据源Promise(ServiceStatus)
update(datasource)更新数据源Promise(ServiceStatus)
delete(id)删除数据源Promise(ServiceStatus)
getDatasourceParams(dpType)获取数据源连接参数Promise(Object)
getQueryParams(sourceType, pageType)获取数据源查询参数Promise(Object)
listDatabases(datasourceId)获取数据库列表Promise(数据库列表)
listSchemas(datasourceId, databaseName)获取数据库模式列表Promise(模式列表)
listTables(datasourceId, databaseName,
schemaName)
获取数据表列表Promise(数据表列表)
listColumns(datasourceId, databaseName,
schemaName,
tableName)
获取数据表字段列表Promise(字段列表)

export declare class DatasourceService {
    getById(id)
    getDatasourceList(lite = true, specFolderId?)
    getDatasourceTreeData(specFolderId?)
    new(datasource)
    update(datasource)
    delete(id)
    getDatasourceParams(dpType)
    getQueryParams(sourceType, pageType)
    testQuery(datasource, queryObj)
    listDatabases(datasourceId)
    listSchemas(datasourceId, databaseName)
    listTables(datasourceId, databaseName, schemaName)
    listColumns(datasourceId, databaseName, schemaName, tableName)
}

DatasetService

数据集相关API

specFolderId 选填参数,获取指定目录下面的资源

方法名/属性说明参数返回值
getById(datasetId)获取数据集datasetId: stringPromise(数据集对象)
getByIds(ids)批量获取数据集ids: string[]Promise(数据集列表)
getDatasetList(specFolderId?)获取数据集列表specFolderId?: stringPromise(数据集列表)
new(dataset)新建数据集dataset: objectPromise(ServiceStatus)
update(dataset)更新数据集dataset: objectPromise(ServiceStatus)
delete(datasetId)删除数据集datasetId: stringPromise(ServiceStatus)

export declare class DatasetService {
    getById(datasetId)
    getByIds(ids)
    getDatasetList(specFolderId?)
    getDatasetTreeData(specFolderId?)
    getDatasetListByDsr(datasourceId)
    new(dataset)
    update(dataset)
    delete(datasetId)
    getDimByIdFromDataset(nodeId, dataset)
    testTemplateRuleMatch(input, regex)
}

WidgetService

图表资源相关API

specFolderId 选填参数,获取指定目录下面的资源

方法名/属性说明参数返回值
getById(widgetId)获取组件widgetId: stringPromise(组件对象)
getWidgetList(specFolderId?)获取组件列表specFolderId?: stringPromise(组件列表)
getWidgetListByDsr(datasourceId)按数据源ID获取图表组件datasourceId: stringPromise(组件列表)
new(widget)新建组件widget: objectPromise(ServiceStatus)
update(widget)更新组件widget: objectPromise(ServiceStatus)
delete(widgetId)删除组件widgetId: stringPromise(ServiceStatus)

export declare class WidgetService {
    getById(widgetId)
    getWidgetList(specFolderId?)
    getWidgetListByDsr(datasourceId)
    getWidgetListByDst(datasetId)
    getWidgetTreeData(datasetList, datasourceList, specFolderId?)
    new(widget)
    update(widget)
    delete(widgetId)
    checkWidget(widgetId)
    compileChartConfig(chartConfig)
}

BoardService

方法名/属性说明参数返回值
getBoardData(boardId)获取看板数据boardId: stringPromise(看板数据对象)
getBoardList(specFolderId)获取看板列表specFolderId: stringPromise(看板列表)
getBoardTreeData(layoutType, specFolderId)获取看板树形结构数据layoutType: string, specFolderId: stringPromise(树形结构数据)
new(board)新建看板board: objectPromise(ServiceStatus)
update(board)更新看板board: objectPromise(ServiceStatus)
delete(boardId)删除看板boardId: stringPromise(ServiceStatus)
cacheParams(boardId, filters)缓存看板参数boardId: string, filters: object
getCachedParams(key)获取缓存参数key: string参数对象

export declare class BoardService {
    getBoardData(boardId)
    getBoardList(specFolderId)
    getBoardTreeData(layoutType, specFolderId)
    getBoardNestLoopTreeData2(layoutType, specFolderId)
    new(board)
    update(board)
    delete(boardId)
    cacheParams(boardId, filters)
    getCachedParams(key)
}

图表服务/chart-services

图表服务库,渲染dom为图表

drawChart

import { chartService } from 'chart-services'

this.drawChart(containerDom, widgetConfig, options = {}) { ... }
this.chartDom = this.$el.querySelector('.view-div');
try {
  chartService.drawChart($(this.chartDom), {
    widgetName: '去年的总销售额',
    datasetId: 240820113813950,
    config: {
      chart_type: 'line',
      keys: [
        {
          column: '订单日期',
          dateFormat: 'yyyy',
        }
      ],
      groups: [],
      filters: [],
      values: [{
        cols: [
          {
            sid: 'v1',
            // id: 'qjjm6fjtuq',
            col: '销售额',
            aggregate_type: 'sum'
          }
        ]
      }],
      option: {
        title: {
          show: true,
        },
        drillConfig: {
          allow: true,
          freeMode: true,
        },
        devTool: {
          beforeRender(option) {
            console.log(JSON.stringify(option));
            _.merge(option, {
              title: {
                text: '名称改变',
              },
            })
          },
        }
      }
    }
  }).then(response => {
    let {
      //updater,
      render
    } = response;
    this.render = render;
  })
} catch (e) {
  console.log(e)
}