DMP图表组件开发指南

一、组件开发工具

安装

npm install dmp-cli -g

windows下若出现fsevents安装失败，尝试在命令后面添加--no-optional参数

运行dmp，输出以下画面，说明安装成功。

初始化组件

dmp init

windows下需使用管理员权限执行

1、输入组件基本信息

组件英文名称为组件code，保证唯一。

组件中文名称，为平台显示的组件名称。

2、选择图表组件类型

chart(有数据集的普通图表)： 数据源通过配置数据集的图表，如表格、饼图等大部分图表。

filter(有数据集的筛选器图表)：数据源通过配置数据集的筛选器，如下拉筛选等。

auxiliary(无数据集、可配置数据的辅助图形)：数据源通过手动输入配置的简单图表，如文本、图片等。

auxiliary-none(无数据集、不可配置数据的辅助图形)：无数据源的简单图表，如时间器，简单Tab选项卡组件。

3、选择组件开发使用的前端框架

4、组件初始化完成后会生成一个组件包，开发者在此基础上进行开发。

生成的组件包

运行组件

cd 你组件的文件夹名
dmp run

windows下需使用管理员权限执行

执行运行命令后，会打开报告设计器本地开发调试界面，同DMP平台报告设计器功能一致。

1、首先注册开发者账号

2、进入本地报告设计器界面，进行组件开发调试

组件导航栏包含了开发者的组件、平台内置的图表组件

3、创建组件单图后，可以进行样式及数据配置

样式选项卡：渲染组件的自定义配置项。

数据选项卡：拖拽数据维度和数值字段等，组件获取到对应的数据进行显示。

打包组件

dmp package --env test|beta|prod

windows下需使用管理员权限执行

根据组件包运行的环境（test或beta或prod）执行打包命令，生成一个zip包，然后再上传到组件中心。

二、组件包规范

1、目录结构

component                           //组件包
   |
   |-- .dist/                       //包含组件打包文件
   |-- .pack/                       //包含组件打包文件的zip压缩包
   |
   |-- designer/                    //包含组件的设计时代码
   |   |--components/               //包含开发者自行开发的样式属性组件
   |      |--myComponent.js
   |   |--index.js                  //组件的功能配置
   |
   |-- platform/
   |   |--icon/
   |      |--component.png          //组件icon图标(32*32)
   |      |--component_disable.png  //组件禁用状态的icon图标
   |   |--preview/
   |      |--sample.png             //组件显示的示例图片(335*238)
   |
   |-- src/
   |   |--index.jsx                 //包含组件的运行时源码
   |
   |-- index.js                     //组件包主入口文件
   |-- package.json                 //组件包配置

2、package.json

• 组件初始化默认生成的部分，开发者不需要修改

(1) name

(2) version

(3) description

(4) platform/name

(5) platform/chartType

(6) platform/dataLogicType

(7) config/dataSourceOrigin

chartType、dataLogicType和dataSourceOrigin的对应关系：

• 开发者需要手动配置的部分：

(1) 修改platform配置项icon、icon_disable和previewImg的图片引用路径，指向组件自身的图片

(2) 修改组件功能配置项config

3、入口文件index.js

初始化组件选择vue框架时，该文件有特殊处理。通过dmp-chart-sdk的getVueComponent方法接入Vue组件，然后再Connect到平台。

而React组件包则在源码src/index.jsx里通过Connect方法连接到平台。

4、运行时源码src/index.jsx

组件开发需要引入DMP平台提供的组件开发SDK: dmp-chart-sdk, 组件通过Connect方法连接平台，接收config(样式配置)、data(通过数据集获取的数据)和events(平台功能API)等Props属性。

组件内部接收到的props属性列表：

React组件示例：

5、设计时代码designer/index.js

通过该文件对组件进行配置，包括功能配置(package.json/config)、样式配置(chartConfig)、previewData(没有配置数据集时的默认数据)、defaultDataSize(报告设计时获取数据的最大条目数)等

• 样式配置格式详情见《四、样式配置chartConfig》。

• 每个样式配置项对应一个样式配置组件PropComponent

• 开发者可以从dmp-chart-sdk的PropComponents获取，详情见《五、内置样式配置组件PropComponents》

• 开发者也可以扩展开发样式配置组件，详情见《六、样式配置组件扩展开发》

• 开发者引入使用Vue框架开发的样式配置组件时，需要调用dmp-chart-sdk的getVueComponent方法，如下图

三、组件开发SDK

平台提供了图表组件开发SDK: dmp-chart-sdk

import {
  Connect,
  PropComponents,
  Utils,

  getVueComponent,
  convertToVueComponent
} from 'dmp-chart-sdk'

Connect

连接器，为图表组件与DMP大数据可视化平台提供了连接，通过此连接可为组件提供开发相关的props属性。

React和Vue组件使用略有差别。

• React: src/index.jsx

class MyChart extends React.Component {
 ...
}

export default Connect()(MyChart)

• Vue: index.js

import component from './src/index'
import designer from './designer'

export default {
  ...,
  component: Connect()(getVueComponent(component))
}

PropComponents

平台内置样式属性基础组件，详情见《五、内置样式配置组件PropComponents》

Utils

实用方法

getVueComponent

getVueComponent('path/to.vue')

引入vue文件，使vue组件能够在dmp平台运行

convertToVueComponent

使dmp组件sdk提供的基础属性组件PropComponents，能够在vue文件内使用

vue文件示例：

<template>
  <color-picker :data="color" :onChange="onChangeColor"/>
</template>

<script>
import { PropComponents, convertToVueComponent } from "dmp-chart-sdk"

export default {
  components: {
    ColorPicker: convertToVueComponent(PropComponents.ColorPicker)
  }
};
</script>

四、样式配置chartConfig

chartConfig配置用以说明组件有哪些配置,既用于传给组件,也用于说明编辑器的选项.

四种概念：

• 配置模块
• 配置组
• 配置项
• 配置组件

示例：

//使用组件SDK的基础配置组件PropComponents
import { PropComponents } from 'dmp-chart-sdk'

export default {

  chartConfig:[
    //这是一个配置模块
    {
      field: 'module1',        // 模块字段，必填
      title: '模块1',           // 模块名称
      show: true,              // 设置模块开关按钮的状态(开启或关闭)，不设置该属性则不显示开关按钮
      spread: true,            // 设置模块的展开状态(下拉展开或收缩隐藏)
      items: [                 // 配置模块包含配置组或配置项

        //这是一个配置组
        {
          field: 'group1',     // 配置组字段，必填
          label: '配置组1',     // 配置组名称
          show: {              // 配置组开关按钮，不设置则不显示
            field: 'checked',  // 开关字段名，必填
            data: true         // 开关按钮状态(开启或关闭)
          },
          items:[              // 配置组包含配置项，不支持嵌套配置组

            //这是一个配置项
            {
              field: 'item1',      // 配置项字段，必填
              label: '配置项1',     // 配置项名称，不设置该属性则不显示label

              //这是一个内置配置组件
              component: PropComponents.ColorPicker,
              data: ''             // 配置项默认值，传入配置组件
            }
          ]
        },

        //这是一个配置项
        {
          field: 'item2',      // 配置项字段，必填
          label: '配置项2',     // 配置项名称，不设置该属性则不显示label

          //这是一个内置配置组件，可传递prop属性
          component: {
           component: PropComponents.Spinner,
           props: {
             min: 12
           }
          },
          data: 14          // 配置项默认值，传入配置组件
        }
      ]
    }
  ]
}

传递给组件的配置数据

//react
const { config } = this.props

//vue
const config = this.config

//配置JSON数据如下
config={
  module1:{
    show: true,
    spread: true
    group1:{
      checked: true,
      item1: ''
    }
    item2: 14
  }
}

效果

平台内置通用配置(标题、背景、边框)，可选择禁用(不建议)。

chartConfig=[

  //禁用标题模块
  {
    field: 'containerTitle',
    disabled: true
  },

  //禁用背景模块
  {
    field: 'containerBackground',
    disabled: true
  },

  //禁用边框模块
  {
    field: 'containerBorder',
    disabled: true
  }
]

五、内置样式配置组件PropComponents

PropComponents.Border

示例

{
  component: {
    component:PropComponents.Border,
    props:{
      hideColor: false,   //是否隐藏颜色配置项
      colorLabel: '颜色',  //颜色配置项标题
      styleLabel: '粗细'   //线条配置项标题
    }
  },
  data: {
     borderColor: 'transparent',
     borderStyle: 'solid',       //solid(实线), dashed(虚线), dotted(点线)
     borderWidth: 0
  }
}

PropComponents.Checkbox

示例

{
  component: PropComponents.Checkbox,
  data: true
}

PropComponents.ColorPicker

示例

{
  component: PropComponents.ColorPicker,
  data: '#24BCFA'
}

PropComponents.DatePicker

示例

{
  component: {
    component: PropComponents.DatePicker,
    props:{
      single: false,
      parentEl: 'body'
    }
  },
  data: ['2017-08-16', '2017-10-25'] // single:true时，data:'2017-08-16'
}

PropComponents.FontStyle

示例

{
  component: PropComponents.FontStyle,
  data: {
     fontWeight: 'normal',   //bold, normal
     fontStyle: 'normal',    //italic, normal
     textDecoration: 'none'  //underline, none
  }
}

PropComponents.GridSpinner

示例

{
  component: {
    component: PropComponents.GridSpinner,
    props: {
      indent: false,
      options: [
        {
          name: 'width',
          label: '宽',
          max: +Infinity,
          min: 10,
          step: 1
        },
        {
          name: 'height',
          label: '高',
          max: +Infinity,
          min: 10,
          step: 1
        },
        {
          name: 'x',
          label: 'X',
          max: +Infinity,
          min: -Infinity,
          step: 1
        },
        {
          name: 'y',
          label: 'Y',
          max: +Infinity,
          min: -Infinity,
          step: 1
        }
      ]
    }
  },
  data: {
    width: 478,
    height: 360,
    x: 86,
    y: 44
  }
}

PropComponents.ImageUploader

示例

{
   component: PropComponents.ImageUploader,
   data: ''
}

PropComponents.Input

示例

{
  component: {
    component:PropComponents.Input,
    props:{
      type:'input', //input或textarea
      placeholder:''
    }
  },
  data: '文本框'
}

PropComponents.Select

示例

{
  component: {
    component: PropComponents.Select,
    props:{
      options:[
        { value: '文字', text: '文字' },
        { value: '图片', text: '图片' }
      ]
    }
  },
  data: "文字"
}

PropComponents.Slider

示例

{
  component: {
    component: PropComponents.Slider,
    props: {
      min: 0,
      max: 100,
      step: 1
    }
  },
  data: 50
}

PropComponents.Spinner

示例

{
  component: {
    component: PropComponents.Spinner,
    props:{
      max: 60,
      min: 12,
      step: 1,
      unit: 'px'
    }
  },
  data: 12
}

PropComponents.TimeSpinner

示例

{
  component: PropComponents.TimeSpinner,
  data: {
    time: 0,
    unit: 'hour'  //hour, minute, second
  }
}

PropComponents.TextAlign

示例

{
  component: PropComponents.TextAlign,
  data: 'left'  //left, center, right
}

六、样式配置组件扩展开发

开发者可扩展开发样式配置组件，以满足图表的个性配置

基础Prop属性:

• react示例

import { PropComponents } from 'dmp-chart-sdk'
import MyComponent from './components/mycomponent'

export default {
  chartConfig:[
    {
      field: 'module1',
      title: '模块1',
      show: true,
      spread: true,
      items: [
        {
          field: 'customItem',
          label: '自定义配置项',
          component: MyComponent,  //使用自己开发的配置组件
          data: 'test'
        }
      ]
    }
  }
}

mycomponent.jsx

import React from 'react'
import PropTypes from 'prop-types'
import _ from 'lodash'

class MyComponent extends React.Component {
  static propTypes = {
    chart: PropTypes.object,     //当前图表的相关配置(数据集、维度等)
    chartData: PropTypes.object, //当前图表请求返回的数据
    data: PropTypes.object,      //当前配置项的值
    onChange: PropTypes.func     //配置项值修改后需触发的事件
  }

  constructor(props) {
    super(props)
    this.state = {
      data: props.data
    }
  }

  componentWillReceiveProps(nextProps) {
    if (!_.isEqual(nextProps.chart, this.props.chart)) {
      this.setState({
        data: nextProps.data
      })
    }
  }

  render() {
    const { data } = this.state
    return (
      <div className="diagram-design-config-content">
        <div className="form">
          <input
            type="text"
            className="form-control"
            value={data}
            onChange={this.handleChange}
          />
        </div>
      </div>
    )
  }

  handleChange = (e) => {
    const data = e.target.value
    this.setState({
      data
    }, () => {
      this.props.onChange(data)
    })
  }
}

export default MyComponent

• vue示例

import { PropComponents, getVueComponent } from 'dmp-chart-sdk'
import MyComponent from './components/mycomponent.vue'

export default {
  chartConfig:[
    {
      field: 'module1',
      title: '模块1',
      show: true,
      spread: true,
      items: [
        {
          field: 'customItem',
          label: '自定义配置项',
          component: getVueComponent(MyComponent),  //引入自己开发的vue配置组件
          data: 'test'
        }
      ]
    }
  }
}

mycomponent.vue

<template>
  <div className="diagram-design-config-content">
    <div className="form">
      <color-picker :data="color" :onChange="onChangeColor"/>
    </div>
  </div>
</template>

<script>
import { PropComponents, convertToVueComponent } from "dmp-chart-sdk";

export default {
  props: {
    chart: Object,
    chartData: Object,
    data: String,
    onChange: Function
  },
  data() {
    return {
      color: this.data
    };
  },
  components: {
    ColorPicker: convertToVueComponent(PropComponents.ColorPicker)
  },
  methods: {
    onChangeColor(color) {
      this.$set({ color });
      this.onChange(color);
    }
  }
};
</script>

效果

七、平台功能调用

筛选

开发者在开发筛选器(chart_type === 'filter')时可扩展组件筛选功能，以满足筛选器图表对于其他图表组件进行筛选

平台筛选设置

基础Prop属性:

• react示例

  handleDateChange(value) {
    const { designTime, data, events, chartId } = this.props
    const { dims } = data.indicators || {}
    const dim = dims && dims[0]
    const newDate = _date2Range(value, this.state.type)
    const conditions = []
    newDate.forEach((item, i) => {
      if (i === 0 && !!item) {
        conditions.push({
          field_name: dim.col_name,
          field_id: dim.dim || dim.id,
          col_value: item,
          operator: '>=',
          formula_mode: dim.formula_mode,
          dim
        })
      } else if (item) {
        conditions.push({
          field_name: dim.col_name,
          field_id: dim.dim || dim.id,
          col_value: item,
          operator: '<=',
          formula_mode: dim.formula_mode,
          dim
        })
      }
    })
    this.setState({
      date: newDate
    }, () => {
      if (designTime) {
        events && events.onChangeDatasetDefaultValue && events.onChangeDatasetDefaultValue(this.state.date.join(','))
      } else {
        events && events.onFilterChange && events.onFilterChange(conditions, chartId)
      }
    })
  }

联动

开发者在开发图表组件(chart_type === 'chart')时可扩展组件联动功能，以满足图表对于其他图表组件进行联动

平台联动设置

基础Prop属性:

组件联动相关属性:

组件联动注意项： 1.优先级低于穿透(点击事件优先绑定穿透事件) 2.组件本身需要样式区分选中状态与非选中状态 3.组件如果要设置联动,必须存在维度字段

• react示例

    //维度存在且被联动单图list大于0
    if (dims && dims.length > 0 && linkList && linkList.length > 0) {
      this.hasBindClickEvent = true;
      this.validConnect = false;
      //2018-04-26 处理'{空}'的情况以区别currentName为''的无联动状态
      if (chartRelated && (params.name === currentName || currentName === '{空}')) {
        this.setState({
          currentName: '',
          chartRelated: false
        }, () => {
          if (events.onRelateChart) {
            events.onRelateChart(conditions, chartId, '', () => {
              this.hasBindClickEvent = false
              this.validConnect = true
              this.bindEvents()
            })
          }
        })
      } else {
        //拆分name 获得condition_value
        const valueArr = params.name.split('&')
        valueArr.forEach((item, index) => {
          let condition = { chart_id: chartId }
          // 拼接conditions
          item = item === '-' ? '' : item
          if (dims[index]) {
            condition = { ...condition, col_value: item, col_name: dims[index].col_name, dim: dims[index], operator: '=' }
            conditions.push(condition)
          }
        })
        //将params.name为''的情况处理为'空'
        this.setState({
          currentName: params.name || '{空}',
          chartRelated: true
        }, () => {
          if (events.onRelateChart) {
            events.onRelateChart(conditions, chartId, params.name || '{空}', () => {
              this.hasBindClickEvent = false
              this.validConnect = true
              this.bindEvents()
            })
          }
        })
      }
    }

跳转

开发者在开发有数据集的单图组件(chart_type === 'chart')时，以满足单图组件发起报告切换、路由切换、新开标签页功能

平台跳转设置

基础Prop属性:

平台跳转新API参数:

• 组件方法handlePlanformRedirect

  //只需要输出
  handlePlanformRedirect(rowObj, id, col) {
    const { events, data, dashboardName, userToken, platform } = this.props
    const type = 'table_like'
    const paramObj = {
      type,
      col,
      platform,
      events,
      router: this.context.router,
      dataset_field_id: id,
      dashboardName,
      token: userToken,
      data: rowObj,
      conditions: data.paramsConditions || []
    }
    events.onRedirect && events.onRedirect(paramObj)
  }

• 组件内处理数据

• 所有else if为新增逻辑判断，即先兼容平台旧跳转设置、如果旧跳转设置不存在的情况调用新API: handlePlanformRedirect

• 示例代码为柱状类跳转、是一种较为完整跳转设置（数值跳转、维度跳转、参数跳转、多数值维度同时设置跳转）
• 未来组件内处理数据会抽象到平台，所有组件只需要调用组件方法并输出参数即可

    //情况一存在维度
    if (dims && dims.length > 0) {
      dims.forEach((dim, index) => {
        const key = dim.alias || dim.alias_name || dim.col_name
        const reportObj = dimsReportRedirect[key]
        dimKeys.push(key)
        if (reportObj && !hasReportRedirect && reportObj.isOpen) {
          this.handleReportRedirect(reportObj, keys[index])
          hasReportRedirect = true
        } else if (redirectRelation && !hasReportRedirect) {
          const id = dim.dim || dim.dataset_field_id
          const redirect = _.find(redirectRelation.chart_redirect, item => item.dataset_field_id === id)
          //跳转设置存在并且是维度跳转
          if (redirect && redirect.type === 0) {
            this.handlePlanformRedirect({ [key]: keys[index] }, id, key)
            hasReportRedirect = true
          }
        }
      })
      nums.forEach((num, index) => {
        const key = num.alias || num.alias_name || num.col_name
        const reportObj = numsReportRedirect[key]
        //把params的值跟维度别名关联起来
        const keysArr = {}
        keys.forEach((k, i) => {
          keysArr[dimKeys[i]] = k
        })
        //2018-07-18加入新判断,目前会根据点击的柱子决定跳转顺序
        if (reportObj && !hasReportRedirect && reportObj.isOpen && index === params.seriesIndex) {
          this.handleReportRedirect(reportObj, keysArr, keysArr)
          hasReportRedirect = true
        } else if (redirectRelation && !hasReportRedirect && index === params.seriesIndex) {
          //如果存在维度,则默认
          const id = num.num || num.dataset_field_id
          const redirect = _.find(redirectRelation.chart_redirect, item => item.dataset_field_id === id)
          //跳转设置存在并且是数值跳转
          if (redirect && redirect.type === 1) {
            this.handlePlanformRedirect(keysArr, id, key)
            hasReportRedirect = true
          }
        }
      })
    } else {
      //情况二 无维度
      const key = params.seriesName
      const reportObj = numsReportRedirect[key]
      if (reportObj && !hasReportRedirect && reportObj.isOpen) {
        this.handleReportRedirect(reportObj, key)
        hasReportRedirect = true
      } else if (redirectRelation && !hasReportRedirect) {
        const id = this._getIdByAlias(key)
        this.handlePlanformRedirect({}, id)
        hasReportRedirect = true
      }
    }
    if (hasReportRedirect) return

八、报告主题开发

报告主题的加入提升了DMP的多样性，能够满足更多的报告风格的需求。为了使开发者可以快速的上手，开发一套独一无二的报告主题，接下来将介绍报告主题的具体开发步骤。

首先，我们得对单图中的配置文件（designer/index.js）进行升级，这里提供了两个函数，分别是getChartConfigColorByKey和generateDefaultColorTheme，其中第一个方法为单图中的样式动态的提供颜色（渐变色），第二个方法则是动态的改变配色方案。通过这两个方法可以读取echart.js文件中设置的主题样式和应用于单图，接下来我们就来看下如何应用这两个方法。

• 单图示例

  // 获取配色方案
  {
    title: '配色方案',
    spread: true,
    field: 'theme',
    items: [{
      label: '',
      field: 'colorTheme',
      theme_controled: true,
      component: {
        component: PropComponents.ColorThemeConfig,
        props: {
          gradient: true,
          dimensionSwitch: false,
          legends: 'line_like'
        }
      },
      data: generateDefaultColorTheme,
    }],
  }
  // 获取颜色
  {
    field: 'color',
    label: '颜色',
    theme_controled: true,
    component: PropComponents.ColorPicker,
    data: getChartConfigColorByKey.bind(null, 'text')
  }

注：每个需要使用到这两个函数的配置项都需要添加theme_controled字段，因为在编辑时切换主题需要通过这个字段来判断哪个配置项应用了动态获取颜色和配色方案

接下来，我们来看一下echart.js中的配置，首先需要一种配色方案，一般是由多个颜色组合而成的数组。如下所示：

• 配色方案示例

  gradual_blue: {
    name: '渐变蓝',
    colors: ['#297CBA', '#1f3a90', '#131568', '#0d1544', '#297cba', '#54c0d5', '#b3e2cf', '#dcedc8'],
    type: 0
  },

除了新增配色方案之外，还需要为几个单图中特别的字段进行配色，这里要注意，如果为一个主题新增了配色属性，那么其余所有的主题都需要新增这个配色。

• 单图配色示例

  // 渐变蓝
  gradual_blue: {
    rank: 4,
    name: '渐变蓝',
    dashboard_background: 'RGBA(255,255,255,1)',
    tooltip_background: '#FFFFFF',
    tooltip_extra_css: 'box-shadow: 1px 1px 4px 2px rgba(0,0,0,0.10);max-height: 450px;overflow-y:auto; transform: translateZ(1px);',
    tooltip_title_color: '#555555',
    default_color_theme: {
      v: '1',
      themeKey: 'gradual_blue',
      customColors: [],
      affect: 0
    },
    grad_color_theme: {
      v: '1',
      themeKey: 'gradual_blue',
      customColors: [
        {
          value: ['#54C0D5', '#1F3A90']
        }
      ],
      affect: 0
    },
    chart_colors: {
      text: 'RGBA(46,46,46,1)',
      content: 'RGBA(41,124,186,1)',
    }
  }

单图配色相关属性:

通过以上的步骤，一个全新的主题就算是成功创建了，接来下只需要在新增报告中加入一个新主题的选项，就可以尽情的欣赏自己的制作的主题了。

九、开发建议

1、平台内置，组件开发不再需要安装的Node包列表：

react react-dom react-bootstrap-myui dmp-chart-sdk prop-types echarts lodash moment jquery isomorphic-fetch

另外平台已引入高德地图开发API <script src="https://webapi.amap.com/maps?v=1.4.4&key="></script>