6. 自定义图表和插件

6.1. 自定义图表

新建图表时，将图表类型选择为自定义，即可实现自定义图表。

自定义图表不能单独展示，需要将其添加到看板中， 并设置其dg-chart-renderer属性， 完全实现图表渲染器逻辑，才能正常展示。

对于非自定义类型的图表，也可以为其添加dg-chart-renderer属性， 从而重写图表的内置图表渲染器部分逻辑。

6.2. 自定义图表插件

1. 编写插件

新建一个UTF-8编码的plugin.json文件，格式为：

  1. {
  2.   //插件唯一标识
  3.   id: "...",
  4.   //插件展示名称
  5.   nameLabel: "...",
  6.   //插件的数据标记定义，新建图表时即是使用它们设置数据标记，
  7.   //这样，在下面的chartRenderer处理逻辑中，即可获取期望标记的数据集结果数据
  8.   dataSigns:
  9.   [
  10.     {
  11.       //数据标记名
  12.       name: "...",
  13.       //数据标记展示名
  14.       nameLabel: "...",
  15.       //是否必须标记，值为：true、false
  16.       required: ...,
  17.       //是否可多次标记，值为：true、false
  18.       multiple: ...
  19.     },
  20.     ...
  21.   ],
  22.   //插件的图表渲染器
  23.   chartRenderer: 图表渲染器
  24. }

2. 打包插件

将上述plugin.json文件添加到以其id值命名的ZIP压缩包内，例如：

my-chart-plugin-line.zip

  1.   |--plugin.json

3. 上传插件

以管理员账号登录系统后，点击主页右上角的按钮， 点击弹出菜单中的上传图表插件条目，打开上传页面后，将上述的自定义图表插件ZIP压缩包上传即可。

4. 使用插件

在图表管理页面点击[添加]按钮，选择上述自定义的图表插件，新建图表即可。

6.3. 图表渲染器

图表渲染器用于为自定义图表、自定义图表插件实现渲染逻辑，它的格式如下所示：

  1. {
  2.   //可选，渲染图表函数是否是异步函数，默认为false
  3.   //chart 图表对象
  4.   asyncRender: true、false、function(chart){ ...; return true 或者 false; }
  6.   //必选，渲染图表函数
  7.   //chart 图表对象
  8.   render: function(chart){ ... },
  10.   //可选，更新图表数据函数是否是异步函数，默认为false
  11.   //chart 图表对象
  12.   //results 数据集结果对象数组
  13.   asyncUpdate: true、false、function(chart, results){ ...; return true 或者 false; }
  15.   //必选，更新图表数据函数
  16.   //chart 图表对象
  17.   //results 要更新的数据集结果对象数组
  18.   update: function(chart, results){ ... },
  20.   //可选，调整图表尺寸函数，希望图表支持dg-chart-auto-resize时应该定义
  21.   //chart 图表对象
  22.   resize: function(chart){ ... },
  24.   //可选，绑定图表事件处理函数，希望图表支持dg-chart-link、dg-chart-on-*时应该定义
  25.   //chart 图表对象
  26.   //eventType 事件类型，比如："click"、"mouseover"等
  27.   //handler 图表事件处理函数，格式为：function(chartEvent){ ... }
  28.   on: function(chart, eventType, handler){ ... },
  30.   //可选，解绑图表事件处理函数
  31.   //chart 图表对象
  32.   //eventType 事件类型
  33.   //handler 图表事件处理函数引用
  34.   off: function(chart, eventType, handler){ ... },
  36.   //可选，销毁图表函数
  37.   //chart 图表对象
  38.   destroy: function(chart){ ... }
  39. }

如果asyncRender返回true， 那么在render函数中完成异步操作后， 应该调用chart.statusRendered(true)，表明已完成异步渲染。

如果asyncUpdate返回true， 那么在update函数中完成异步操作后， 应该调用chart.statusUpdated(true)，表明已完成异步更新数据。

如果希望图表支持dg-chart-link特性， 那么对于on函数，应该构建规范的图表事件对象传递给图表事件处理函数。 通常的做法是：先捕获底层图表元素事件（比如Echarts事件、HTML事件），然后使用 chart.eventNewEcharts()、 chart.eventNewHtml()、 chart.eventData()、 chart.eventOriginalData() 构建 图表事件对象， 最后调用图表事件处理函数。