DataGear 自定义数据可视化图表插件

DataGear内置的70余种图表（折线图、柱状图、饼图、散点图、雷达图、地图、桑基图、K线图、箱形图、路径图等等），都是以图表插件的形式提供的，当这些内置图表无法满足应用需求时，则可以通过自定义图表或插件的方式，实现特定业务的数据可视化需求。

自定义图表简单快捷，缺点是仅能在其所处看板内使用，且只能绘制已知结构的数据；自定义图表插件稍微复杂，却可在整个系统内使用，并且可绘制符合特定规范的任意结构的数据。

在【DataGear 自定义数据可视化图表】文章中，已经介绍了自定义图表实现方式，本文将以折线图为例，介绍如何自定义图表插件。

在开始之前，需要了解图表插件的一个重要的概念：数据标记，它由名称、是否必须等特性组成，用于定义图表插件的数据规范。用户在定义图表时，将所选数据集的数据结构（数据集属性）绑定图表插件提供的数据标记，图表插件则依据数据标记绑定信息，从数据集中提取数据，绘制图表，从而实现数据结构解耦。

图表插件由两个核心的 plugin.json 和 renderer.js 文件组成，它们的结构规范参考官网文档【自定义图表插件】章节，自定义图表插件的主要工作即是定义它们。

注意：上述图表插件规范需要 DataGear 4.1.0+ 版本

首先，编写 plugin.json 文件，定义图表插件ID、名称基本信息：

//plugin.json

{
  id: "my-line-chart",
  nameLabel: "自定义折线图"
}

折线图的数据结构比较简单：

名称：折线数据点的名称（横坐标）
数值：折线数据点的数值（纵坐标）

因此，图表插件的数据标记可定义为：

//plugin.json

{
  id: "my-line-chart",
  nameLabel: "自定义折线图",
  dataSigns:
  [
    {
      name: "name",
      nameLabel: "名称",
      required: true,
      multiple: false
    },
    {
      name: "value",
      nameLabel: "数值",
      required: true,
      multiple: true
    }
  ]
}

上述数据标记中，name和value标记的required: true表示图表的数据集必须为其属性绑定这两个标记，name标记的multiple: false表示图表的数据集仅能有一个属性绑定它，value标记的multiple: true表示图表的数据集可以有多个属性绑定它，这样插件可支持一个数据集里包含多条折线数据。

例如，对于数据集：

COL_NAME, COL_VAL_0, COL_VAL_1
...,      ...,       ...

绑定了数据标记：

COL_NAME    ->  name（名称）
COL_VAL_0   ->  value（数值）
COL_VAL_1   ->  value（数值）

那么，它将被绘制为两条折线，COL_NAME列值将被绘制为两条折线共同的横坐标，COL_VAL_0列值将被绘制为第一条折线的纵坐标，COL_VAL_1列值将被绘制为第二条折线的纵坐标。

定义了数据标记后，下一步要做的是定义图表渲染器，它的结构已在官网文档【图表渲染器】章节有说明，在【DataGear 自定义数据可视化图表】文章中也有相关说明，这里不再介绍。

图表插件和自定义图表的图表渲染器有一个重要的不同，自定义图表的图表渲染器直接读取数据构建图表展示数据，而图表插件的图表渲染器则通过数据标记绑定信息读取数据构建图表展示数据，相关的图表API如下所示（具体参考官网文档【图表对象】章节）：

chart.dataSetPropertyOfSign(chartDataSet, signName);

chart.dataSetPropertiesOfSign(chartDataSet, signName);

chart.resultNameValueObjects(result, nameProperty, valueProperty);

chart.resultValueObjects(result, valueProperty);

chart.resultMapObjects(result, propertyMap);

本例折线图插件的 renderer.js 图表渲染器文件定义如下所示：

//renderer.js

(function(plugin)
{
  var r =
  {
    render: function(chart)
    {
      var chartDataSet = chart.chartDataSetMain();
      var np = chart.dataSetPropertyOfSign(chartDataSet, plugin.dataSigns[0]);
      var vps = chart.dataSetPropertiesOfSign(chartDataSet, plugin.dataSigns[1]);
    
      var options = chart.inflateRenderOptions(
      {
        title:
        {
          text: chart.name
        },
        xAxis:
        {
          name: chart.dataSetPropertyAlias(chartDataSet, np),
          type: "category"
        },
        yAxis:
        {
          name: (vps.length == 1 ? chart.dataSetPropertyAlias(chartDataSet, vps[0]) : ""),
          type: "value"
        },
        series:
        [
          {
            type: "line"
          }
        ]
      });
      
      chart.echartsInit(options);
    },
    update: function(chart, results)
    {
      var chartDataSets = chart.chartDataSetsMain();
      var legendData = [];
      var series = [];
      
      //图表可关联多个数据集
      for(var i=0; i<chartDataSets.length; i++)
      {
        var chartDataSet = chartDataSets[i];
        var dataSetName = chart.dataSetAlias(chartDataSet);
        var result = chart.resultOf(results, chartDataSet);
        var np = chart.dataSetPropertyOfSign(chartDataSet, plugin.dataSigns[0]);
        var vps = chart.dataSetPropertiesOfSign(chartDataSet, plugin.dataSigns[1]);
        for(var j=0; j<vps.length; j++)
        {
          var legendName = chart.dataSetPropertyAlias(chartDataSet, vps[j]);
          var data = chart.resultNameValueObjects(result, np, vps[j]);
          chart.originalDataIndex(data, chartDataSet);
          var mySeries = {type: "line", name: legendName, data: data};
          legendData.push(legendName);
          series.push(mySeries);
        }
      }
      
      var options = { legend: {data: legendData}, series: series };
      options = chart.inflateUpdateOptions(results, options);
      chart.echartsOptions(options);
    }
  };
  
  return r;
})
(plugin);

在实现了图表渲染器功能后，按照官网【自定义图表插件】章节的步骤，将上述插件上传至DataGear系统即可。

官网地址：

http://www.datagear.tech

源码地址：

Gitee：https://gitee.com/datagear/datagear

Github：https://github.com/datageartech/datagear