图表插件

本文档仅提供2.0API版本的相关功能说明，对于1.0API版本的功能，请参考旧版文档。

图表插件是系统中的可复用组件，能够将符合特定数据结构规范的数据绘制成图表，而无需关心数据结构细节。

一个图表插件是由：

plugin.json
renderer.js
manual.md（可选）
plugin-datasignspec.json（可选）
plugin-configform.json（可选）

五个UTF-8编码的核心文件，和其他资源文件（可选）组成的ZIP压缩包。

其中，plugin.json文件用于定义插件基本信息， renderer.js文件用于定义插件图表渲染器， manual.md文件用于提供插件使用手册。

图表插件有一个重要的核心概念：数据标记，由名称、是否必选、是否多选等特性组成，用于声明图表插件支持的数据结构规范。一个图表插件可以定义多个具有层级关系的数据标记，用户在定义图表时，为所选数据集的数据结构绑定数据标记，图表插件则依据数据标记绑定信息，从数据集中提取数据，绘制图表，从而实现数据结构解耦。

图表插件结构示例：

a-simple-chart-plugin.zip
  |--plugin.json
  |--renderer.js
  |--assets/
      |--style.css
      |--component.js
      |--bg.png

plugin.json

plugin.json文件用于定义图表插件的基本信息，包括：ID、名称、数据标记、配置表单、版本、类别等等，详细结构规范如下所示：

{
  //必填，插件ID，应在系统内唯一
  id: "...",
  //必填，插件展示名称
  nameLabel: "..."、{ value: "..." },
  //必填，声明插件支持的看板API版本，目前版本，此值需固定为：2.0
  apiVersion: "2.0",
  //可选，数据标记规范，用于定义选用此插件的图表在绑定数据标记时可用的数据标记信息，
  //可以在此定义，也可以在单独的plugin-datasignspec.json文件中定义
  dataSignSpec: [ 数据标记, ... ]、数据标记规范,
  //可选，配置表单，用于定义选用此插件的图表在设置图表配置时可编辑的配置表单信息，
  //可以在此定义，也可以在单独的plugin-configform.json文件中定义
  configForm: 配置表单,
  //可选，插件限制的数据集数目范围，不设则表示没有限制，定义图表时可选择的数据集数目受此限制
  dataSetRange:
  //仅声明插件限制的主件数据集最小数目
  数值、
  //仅声明插件限制的主件数据集最小数目min（可选）、最大数目max（可选）
  { min: 数值, max: 数值 }、
  //声明插件不需要任何数据集，等价于：{ main: { min: 0,  max: 0 }, attachment: { min: 0, max: 0 } }
  "none"、
  //声明插件限制的主件数据集最小/最大数目main（可选）、附件数据集最小/最大数目attachment（可选）
  { main: { min: 数值,  max: 数值 }, attachment: { min: 数值, max: 数值 } },
  //可选，插件描述
  descLabel: "..."、{ value: "..." },
  //可选，插件图标在插件包内的路径，或者分别在light浅色（可选）、dark深色（可选）系统主题下的图标路径
  icons: "..."、{ light: "...", dark: "..." },
  //可选，插件版本号，安装时将替换旧版本的插件，应符合语义化版本规范：X.Y.Z、X.Y.Z-BUILD
  version: "...",
  //可选，插件依赖的平台版本，示例：>=6.0.0
  platformVersion: "...",
  //可选，插件展示排序值，越小越靠前
  order : 数值,
  //可选，插件所属类别信息
  categoryInfos:
  //类别名称
  "..."、
  //类别对象
  { ... }、
  //类别信息对象，order表示在类别中的排序值
  { category: 类别, order: 数值 }、
  //类别名称字符串、类别对象、类别信息对象组成的数组
  [ ... ],
  //可选，插件作者
  author: "...",
  //可选，插件作者联系方式
  contact: "...",
  //可选，插件发布日期，示例：2025-03-16
  issueDate: "...",
  //可选，名/值附加信息
  additions: { ... }
}

renderer.js

renderer.js文件用于定义插件图表渲染器，它的内容是一段JavaScript自执行函数表达式，接受一个plugin参数，返回一个图表渲染器对象，详细格式如下所示：

(function(plugin)
{
  ...
  return 图表渲染器;
})
(plugin);

其中的plugin参数即是plugin.json定义的对象格式（未设置renderer属性）。

manual.md

manual.md是一个Markdown格式的文件，用于编写和提供图表插件使用手册。

示例：

# 插件官网

[datagear.tech](http://www.datagear.tech)

# 图表选项

```
{
  title:
  {
    text: "...",
    color: "..."
  },
  data:
  [
    { name: "...", value: ... },
    ...
  ]
}
```

# 支持事件类型

`click`、`mouseover`、`select`

# 事件对象结构

```
{
  name: "...",
  value: ...,
  seriesType: "...",
  seriesIndex: ...,
  data: { ... }
}
```

plugin-datasignspec.json

plugin-datasignspec.json是一个可选文件，用于拆分定义plugin.json中的dataSignSpec属性，当plugin.json中的dataSignSpec属性内容过多时，可选在plugin-datasignspec.json文件中单独定义，结构为：

[
  数据标记,
  ...
]

或者

{
  dataSigns:
  [
    数据标记,
    ...
  ]
}

plugin-configform.json

plugin-configform.json是一个可选文件，用于拆分定义plugin.json中的configForm属性，当plugin.json中的configForm属性内容过多时，可选在plugin-configform.json文件中单独定义，结构为：

配置表单

数据结构

数据标记规范

{
  dataSigns:
  [
    数据标记,
    ...
  ]
}

数据标记

{
  //必填，名称，在本级数组中应唯一
  name: "...",
  //可选，全名，在所属插件内应唯一，如果不设置，系统会自动生成
  fullname: "...",
  //可选，支持绑定目标，默认值为："field"，其中：
  //"field" 表示支持绑定至数据集字段；"dataset" 表示支持绑定至数据集
  targets: "field"、"dataset"、["field", "dataset"],
  //可选，展示名
  nameLabel: "..."、{ value: "..." },
  //可选，描述
  descLabel: "..."、{ value: "..." },
  //可选，是否必须在图表的每一个主件数据集中至少绑定一个目标，默认值为：true
  required: true、false,
  //可选，是否可在多个目标上绑定，默认值为：false
  multiple: false、true,
  //可选，子级数据标记数组，它们只能绑定至子级数据集字段
  children: [ 数据标记, ... ],
  //可选，名/值附加信息
  additions: { ... }
}

配置表单

{
  //必填，表单属性数组，其元素可以是对象型表单属性或者基本型表单属性对象
  properties: [ { ... }, ... ],
  //可选，分组信息，用于将properties分组展示
  groups: [ 表单属性分组, ... ],
  //可选，名/值附加信息
  additions: { ... }
}

对象型表单属性

{
  //必填，属性名
  name: "...",
  //必填，子级属性数组，其元素可以是对象型表单属性或者基本型表单属性对象
  properties: [ { ... }, ... ],
  //可选，展示名称
  nameLabel: "..."、{ value: "..." },
  //可选，描述信息，鼠标悬浮时显示的详细说明信息
  descLabel: "..."、{ value: "..." },
  //可选，是否必填，默认值为：false
  required: false、true,
  //可选，是否数组，默认值为：false
  array: false、true,
  //可选，分组信息，用于将properties分组展示
  groups: [ 表单属性分组, ... ],
  //可选，名/值附加信息，另参考配置表单内置附加信息
  additions: { ... }
}

基本型表单属性

{
  //必填，属性名
  name: "...",
  //可选，类型，可选值为：
  //"string" 字符串；"boolean" 布尔值；"integer" 整数；"number" 数值。默认值为："string"
  type: "...",
  //可选，展示名称
  nameLabel: "..."、{ value: "..." },
  //可选，描述信息，鼠标悬浮时显示的详细说明信息
  descLabel: "..."、{ value: "..." },
  //可选，是否必填，默认值为：false
  required: false、true,
  //可选，是否数组，默认值为：false。
  //注意，当inputType是复选框或者多选下拉框时，其属性值本身已是数组，如果这里再设为true的话，对应的属性值将是一个二维数组
  array: false、true,
  //可选，输入框类型，可选值为：
  //"text" 文本框；"select" 下拉框；"radio" 单选框；"checkbox" 复选框；
  //"textarea" 文本域；"color" 颜色选择器。
  //如果不填，当type为"boolean"时将默认为"radio"；否则默认为"text"
  inputType: "...",
  //可选，输入框配置，由inputType值而定
  inputPayload: 基本型表单属性输入框配置,
  //可选，名/值附加信息，另参考配置表单内置附加信息
  additions: { ... }
}

表单属性分组

{
  //必填，分组中包含的表单属性名，即对象型表单属性或者基本型表单属性的name值
  names: [ "...", ... ],
  //可选，展示名称
  nameLabel: "..."、{ value: "..." },
  //可选，描述信息，鼠标悬浮时显示的详细说明信息
  descLabel: "..."、{ value: "..." },
  //可选，名/值附加信息，另参考配置表单内置附加信息
  additions: { ... }
}

基本型表单属性输入框配置

输入框类型 `inputType`	输入框配置格式 `inputPayload`
文本框 `text`	无
下拉框 `select`	单选下拉框选项名/值格式： [ `待选项名/值对象`, ... ] 或者，使用内置地图名作为选项时的格式： "DG_MAP" 多选下拉框选项名/值格式： { multiple: true, options: [ `待选项名/值对象`, ... ] } 或者，使用内置地图名作为选项时的格式： { multiple: true, options: "DG_MAP" } 待选项名/值对象格式为： { name: "...", value: ... } 当`name`和`value`相同时，则可简写为选项值，示例： `"..."`、`3`、`true`。除了直接在此定义选项名/值信息，也可以使用引用对象格式： { "$refId": "..." } { multiple: true, options: { "$refId": "..." } } 其中，`"$refId"`的值应是在配置表单的`additions`中定义的附加信息名，附加信息值应符合上述选项名/值格式之一。
单选框 `radio`	单选框选项名/值格式： [ `待选项名/值对象`, ... ] 待选项名/值对象格式为： { name: "...", value: ... } 当`name`和`value`相同时，则可简写为选项值，示例： `"..."`、`3`、`true`。除了直接在此定义选项名/值信息，也可以使用引用对象格式： { "$refId": "..." } 其中，`"$refId"`的值应是在配置表单的`additions`中定义的附加信息名，附加信息值应符合上述选项名/值格式之一。
复选框 `checkbox`	复选框选项名/值格式： [ `待选项名/值对象`, ... ] 待选项名/值对象格式为： { name: "...", value: ... } 当`name`和`value`相同时，则可简写为选项值，示例： `"..."`、`3`、`true`。除了直接在此定义选项名/值信息，也可以使用引用对象格式： { "$refId": "..." } 其中，`"$refId"`的值应是在配置表单的`additions`中定义的附加信息名，附加信息值应符合上述选项名/值格式之一。
文本域 `textarea`	无
颜色选择器 `color`	无

配置表单内置附加信息

对象型表单属性、基本型表单属性、表单属性分组都支持如下附加信息：

disableIf
禁用表单属性或分组的JavaScript表达式字符串，当表达式返回true时将禁用，否则启用
enableIf
启用表单属性或分组的JavaScript表达式字符串，当表达式返回true时将启用，否则禁用

disableIf和enableIf只支持设置其中之一，表达式中可以使用$this、$root两个变量，其中，$this表示当前属性或分组所属的父级表单数据对象，$root表示根级表单数据对象。

示例：

{
  ...,
  additions:
  {
    disableIf: "!$root.enableBorder || $this.borderWith == null || $this.borderWith < 1"
  }
}

{
  ...,
  additions:
  {
    enableIf: "$root.enableBorder && $this.borderWith != null && $this.borderWith > 0"
  }
}

其中，enableBorder是在配置表单的properties中定义的表单属性名， borderWith是在当前对象型表单属性的properties中定义的表单属性名。

另外，基本型表单属性还支持如下附加信息：

前置条件	支持的附加信息
当`type`为`"string"`时	`minlength` 限制字符串最小长度 `maxlength` 限制字符串最大长度示例： `{ ..., additions: { minlength: 2, maxlength: 10 } }`
当`type`为`"integer"`或`"number"`时	`min` 限制数值最小值 `max` 限制数值最大值示例： `{ ..., additions: { min: 1, max: 9 } }`
当`array`为`true`时	`minsize` 限制数组最小长度 `maxsize` 限制数组最大长度示例： `{ ..., additions: { minsize: 1, maxsize: 5 } }`

类别

{
  //必填，类别名
  name: "...",
  //可选，类别展示名
  nameLabel: "..."、{ value: "..." },
  //可选，类别排序值，越小越靠前
  order: 数值
}