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

如果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() 构建 图表事件对象, 最后调用图表事件处理函数。