插件化图表之图表参数设置表单
Stephen Cui ... 2021-11-25 15:00:00 About 10 min
# 插件化图表之图表参数设置表单
图表插件化的核心抽象能力之一即是图表参数表单的可配置化。其中基于Datart对于商业可视化BI的理解，我们将其抽象为两类事物：
数据配置和样式配置, 通过提供有限集的辅助功能来帮助插件图表制作者完成图表的制作。
首先，关于Datart插件化图表的相关概念和概要说明，请参考自定义插件化图表 (opens new window)这篇用户手册文章。接下来，我们来展开讲讲什么是图表参数表单，图表参数表单的作用以及可配置的功能。
数据配置组件结构定义和功能如下图1所示：
数据配置组件通用功能如下图2所示：
接下来，我们展开讲解各区域模块的作用和可配置规则说明。这里我们尝试使用两类用户User Journey来描述功能。
- 图表业务分析人员，👩 Rose 王
- 图表插件制作人员，👨 Jack 李
# 1 数据配置
该配置项的有两层含义：第一层含义是通过定义/使用不同的区域组件，来辅助分析人员选择数据字段（例如，选择维度和指标/度量）以及特殊数据字段提供对应的功能（例如，散点图的气泡大小设置、信息提示）；第二层含义是通过用户配置的数据字段来请求数据（例如，分组、聚合、过滤）
# 1.1 维度区域
作为图表制作人员Jack 👨，可以以如下的方式定义
维度区域功能
⚠️注意: 编辑修改图表配置项所在文件，请参考自定义插件化图表 (opens new window)
{
label: 'dimension',
key: 'dimension',
// optional
required: true,
type: 'group',
// optional
limit: [0, 1],
// optional
actions: [],
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
label: 功能区域对应的I18N的单key值，也可以通过.分割组合的字符串的形式，如my.custom.dimension作为key值的路径，在全局或者是自定义图表的I18N项中查找对应的翻译文字。
key: 必须保证同级/兄弟节点的值的唯一性，key作为图表绘制时可查找路径。
required: 该属性表明当前区域受图表最小limit属性约束，必须保证该区域有足够的数量才可以进行图表的展示，否则提示根据数量。
limit: 绘图所需的数量或者合理数量区间，例如limit: 3表明当前区域确切需要3个数据字段，limit: [1, 3]表明当前区域至少需要1个数据字段，至多需要3个数据字段，否则不绘制图表。当limit未设置时，会根据读取不同功能区域的默认值，如果为null，则不限制数量。
type: 维度对应的区域功能组件是group类型, 更多类型请参考ChartDataSectionType (opens new window)。
actions: 一般来讲，封装好的功能区域会有默认设置，对于维度区域来讲， 。当然Jack也可以进行手动配置来覆盖掉默认值。 基于可配置的原子化的actions是希望以更灵活的方式可以给Jack提供强大的组合功能，目前含有的功能列表有alias, sortable, format, aggregate, colorize, size等ChartDataSectionFieldActionType (opens new window)。
举例来讲，当前GroupTypeSection组件中actions的默认值是:
actions: {
[ChartDataViewFieldType.NUMERIC]: [
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Sortable,
],
[ChartDataViewFieldType.STRING]: [
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Sortable,
],
[ChartDataViewFieldType.DATE]: [
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Sortable,
],
},
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
等价于Jack需要在组件配置中的手动扩展的内容：
actions: {
NUMERIC: ['alias', 'sortable'],
STRING: ['alias', 'sortable'],
DATE: ['alias', 'sortable'],
},
1
2
3
4
5
2
3
4
5
至此，Jack完成了维度区域的基本配置，接下来我们来看一下分析人员Rose使用维度区域功能时的场景。
作为业务分析人员Rose 👩，当编辑维度区域的内容时可以有如下功能
详细功能如图3所示：
# 1.2 指标区域
作为图表制作人员Jack 👨，可以以如下的方式定义
指标区域功能
{
label: 'metrics',
key: 'metrics',
required: true,
type: 'aggregate',
limit: [1, 999],
}
1
2
3
4
5
6
7
2
3
4
5
6
7
配置中label, key, required, type, limit均与1.1维度中的说明相同。
当前keymetric对应的AggregateTypeSection的默认配置如下：
{
actions: {
[ChartDataViewFieldType.NUMERIC]: [
ChartDataSectionFieldActionType.Aggregate,
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Format,
ChartDataSectionFieldActionType.Sortable,
ChartDataSectionFieldActionType.ColorizeSingle,
],
[ChartDataViewFieldType.STRING]: [
ChartDataSectionFieldActionType.AggregateLimit,
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Format,
ChartDataSectionFieldActionType.Sortable,
ChartDataSectionFieldActionType.ColorizeSingle,
],
},
},
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
作为业务分析人员Rose 👩，当编辑
指标区域的内容时可以有如下功能
详细功能如图4所示：
指标格式化功能弹窗图如图5所示：
# 1.3 筛选区域
作为图表制作人员Jack 👨，可以以如下的方式定义
筛选区域功能
{
label: 'filter',
key: 'filter',
type: 'filter',
}
1
2
3
4
5
2
3
4
5
配置中label, key, type均与1.1维度中的说明相同。
当前keyfilter对应的FilterTypeSection的默认配置如下：
{
allowSameField: true,
},
{
actions: {
[ChartDataViewFieldType.NUMERIC]: [
ChartDataSectionFieldActionType.Filter,
],
[ChartDataViewFieldType.STRING]: [
ChartDataSectionFieldActionType.Filter,
],
[ChartDataViewFieldType.DATE]: [
ChartDataSectionFieldActionType.Filter,
],
},
},
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
allowSameField意思是允许重复的数据列被拖拽到该区域。
目前，筛选区域的实现是基于数据列的类型（数字类型，字符串类型，日期类型）来显示不同的设置方式，该过滤条件会应用在图表数据本身，同时也会被显示（隐藏）在图表预览界面。
作为业务分析人员Rose 👩，当编辑
筛选区域的内容时可以有如下功能
如果数据类型是字符串类型，则显示效果如下：
如果数据类型是数字类型，则显示效果如下：
如果数据类型是日期类型，则显示效果如下：
# 1.4 颜色区域
作为图表制作人员Jack 👨，可以以如下的方式定义
颜色区域功能
{
label: 'colorize',
key: 'color',
type: 'color',
limit: [0, 1],
},
1
2
3
4
5
6
2
3
4
5
6
配置中label, key, type, limit均与1.1维度中的说明相同。
当前keycolor对应的ColorTypeSection的默认配置如下：
{
[ChartDataViewFieldType.STRING]: [
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Colorize,
],
}
1
2
3
4
5
6
2
3
4
5
6
⚠️注意:当前颜色区域配置只支持字符串类型的数据字段（只针对离散型数据）
作为业务分析人员Rose 👩，当编辑
筛选区域的内容时可以有如下功能
如果数据类型是字符串类型，则显示效果如下：
# 1.5 信息区域
作为图表制作人员Jack 👨，可以以如下的方式定义
信息区域功能
{
label: 'info',
key: 'info',
type: 'info',
}
1
2
3
4
5
2
3
4
5
配置中label, key, type均与1.1维度中的说明相同。
当前keyinfo对应的InfoTypeSection的默认配置如下：
{
allowSameField: true,
},
{
actions: {
[ChartDataViewFieldType.NUMERIC]: [
ChartDataSectionFieldActionType.Aggregate,
ChartDataSectionFieldActionType.Alias,
ChartDataSectionFieldActionType.Format,
],
},
},
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
⚠️注意:当前颜色区域配置只支持数字类型的数据字段（只针对连续型数据）
作为业务分析人员Rose 👩，当编辑
筛选区域的内容时可以有如下功能
如果数据类型是数字类型，则显示效果如下：
# 1.6 大小区域
作为图表制作人员Jack 👨，可以以如下的方式定义
大小区域功能
{
label: 'size',
key: 'size',
type: 'size',
},
1
2
3
4
5
2
3
4
5
配置中label, key, type均与1.1维度中的说明相同。
当前keysize对应的SizeTypeSection的默认配置如下：
{
actions: {
[ChartDataViewFieldType.NUMERIC]: [
ChartDataSectionFieldActionType.Aggregate,
ChartDataSectionFieldActionType.Format,
ChartDataSectionFieldActionType.Alias,
],
},
},
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
⚠️注意:当前颜色区域配置只支持数字类型的数据字段（只针对连续型数据）
作为业务分析人员Rose 👩，当编辑
筛选区域的内容时可以有如下功能
如果数据类型是数字类型，则显示效果如下：
# 2 样式配置
样式配置（以及配置项）主要功能是提供基于业务的图表个性化配置参数，通过定义JSON Schema来渲染图表配置，例如图例、标签、参考线等配置，同时可以无限嵌套基础配置组合出更复杂的配置表单无限嵌套表单 (opens new window), 更详细的说明请参考ChartStyleSectionConfig (opens new window)。
样式配置主要分为三种类型：
- 原子组件
- 布局组件
- 自定义组件
# 2.1 原子组件
作为图表制作人员Jack 👨，可以以如下的方式定义
原子组件功能
原子组件comType包含如下类型：
- checkbox：单选框类型组件
- input：输入框类型组件
- switch：开关类型组件
- select：单选下拉框组件
- font：字体设置组件
- inputNumber：数字类型输入框组件
- slider：滑块组件
[
{
label: 'demo.title',
key: 'demo',
comType: 'group',
rows: [
{
label: 'demo.comType.checkbox',
key: 'demo.comType.checkbox',
comType: 'checkbox',
default: true,
},
{
label: 'demo.comType.input',
key: 'demo.comType.input',
comType: 'input',
default: '请输入内容...',
},
{
label: 'demo.comType.switch',
key: 'demo.comType.switch',
comType: 'switch',
default: true,
},
{
label: 'demo.comType.select',
key: 'demo.comType.select',
comType: 'select',
default: 'top',
options: {
items: [
{ label: '上', value: 'top' },
{ label: '左', value: 'left' },
{ label: '右', value: 'right' },
{ label: '下', value: 'bottom' },
],
},
},
{
label: 'demo.comType.font',
key: 'demo.comType.font',
comType: 'font',
default: {
fontFamily: 'PingFang SC',
fontSize: '12',
fontWeight: 'normal',
fontStyle: 'normal',
color: '#495057',
},
},
{
label: 'demo.comType.inputNumber',
key: 'demo.comType.inputNumber',
default: 20211130,
comType: 'inputNumber',
},
{
label: 'demo.comType.slider',
key: 'demo.comType.slider',
default: 4,
comType: 'slider',
options: {
min: 2,
max: 20,
},
},
],
}
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
这里的options会依据不同的原子组件进行设置，例如silder包含min,max等最小值、最大值选项。
作为业务分析人员Rose 👩，当编辑样式配置的内容时可以有如下功能
# 2.2 布局组件
作为图表制作人员Jack 👨，可以以如下的方式定义
布局组件功能
布局组件comType包含如下类型：
- group
- panel(默认)
- modal
- tabs
[
{
label: 'bar.title',
key: 'bar',
comType: 'group',
rows: [/* basic components or layout components here */]
},
{
label: 'bar.title',
key: 'bar',
comType: 'group',
rows: [/* basic components or layout components here */],
options: { type: 'modal' }
}
{
label: 'bar.title',
key: 'bar',
comType: 'tabs',
rows: [/* basic components or layout components here */],
options: { editable: true }
}
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
如果当前配置项设置了options: { type: 'modal' }, 则表明，这是一个对话框形式、嵌套的配置面板。
作为业务分析人员Rose 👩，当编辑样式配置的内容时可以有如下功能
# 2.3 自定义组件
自定义组件属于二次开发功能，实现二次开发有两种方式：
- 可基于图表的
原子组件和布局组件组合出配置表单，可参考文件DataReferencePanel.tsx (opens new window)- 可基于Datart组件接口开发自定义组件，可参考文件ListTemplatePanel.tsx (opens new window)