跳到主要内容

自定义系列：散点图

图表底层基于 ECharts，所以参考 ECharts 官方配置项文档使用即可。

同时，在 ECharts 之上我们对其能力做了扩展，暴露了部分自定义配置项（均以 dv 前缀进行命名，以和 ECharts 配置项做以区分），在这里进行说明。

概念约定​

【约定】：dv 开头的配置项称作【自定义配置项】

【约定】：每个气泡整体命名为【图形】，图形中的最小单元形状命名为【图元】

【约定】：data 数组中的单个数据命名为 dataItem

【约定】：dataItem 的 value 中，索引 0，1，2 分别代表 xValue，yValue，rValue

【约定】：dataItem.itemStyle只是dvScatterSeries.dvItemStyle在 data 中的的局部实现，上述俩个部分称作【图元属性】

【约定】：dataItem.itemConfig只是dvScatterSeries.dvItemConfig在 data 中的局部实现，上述俩个部分称作【图形配置项】

自定义散点图适应的问题场景​

自定义散点图基本全面覆盖的原有散点图的配置项

且扩展了以下功能

  • 支持任意数量、任意形状、任意交互、任意动画的图形组合为一个【气泡】

    1.这里的气泡代指代表一个(组)数据渲染的图形

    如果你对上述描述没有概念，可以查看ECharts 官方示例，该示例通过一个复杂图形，很好的描述了一组数据

    2.由于图形数量从一个变为了多个，所以原有的散点图的部分配置项将失效，见附录 4

  • 支持个性化配置每个【气泡】中每个图元的样式、动画、交互

  • 扩展了自定义配置项以及辅助函数，以满足范式中涉及的功能，比如历史轨迹、临近搜索、轴线范围自适应等

  • 重写交互，使其支持 click、hover 俩种交互效果

交互重写​

由于 ECharts 交互设计原因，无法满足气泡图应用场景，故在底层重新实现交互依赖的状态变更相关的 Action，Action 相应的 API 和回调都有所更改

如果你不关心或者不用控制图形元素的状态变化，那么你可以忽略掉这部分

ECharts 原有的 action 机制参考这里：ECharts 原生 Action

详细内容见：Action

以下是变化的部分：

  • 重写原有的highlight为dvHighlight

  • 重写原有的downplay为dvDownplay

  • 新增dvSelect

  • 新增dvUnselect

  • 新增dvEmphasis

  • 新增dvBlur

备注

原本的 echarts，虽然同样支持 click 与 hover，但是二者只能存在一个高亮，当开启’series.emphasis.focus‘配置时，另一个就会替换为 blur 状态。

比如先 click 选中一个点，然后 hover 另一个点，期望的是俩个点都保持高亮，但 ECharts 原生机制只会高亮 hover 的点

故重新实现底层状态控制

dvHighlight 与 dvDownplay 现在与 mouseover 与 mouseout 绑定，移入高亮，移出取消高亮（不会取消点击触发的高亮状态）

dvSelect 与 dvUnselect 现在与 click 绑定，点击气泡高亮，点击空白画布取消高亮

dvEmphasis 与 dvBlur 仅控制单个气泡的状态，不会像上述俩组影响全部气泡的状态，dvEmphasis 与 dvBlur 仅作为补丁 Action，一般不会被用到

自定义配置项​

以下配置项只在 series.type: 'dvScatter' 时有效

series.dvSymbol​

提示

目前只支持'circle'，后续根据业务需求扩展，详见附录 2

  • 类型string

  • 默认值'circle'

图形种类

series.dvSymbolSize​

  • 类型number|[number, number]

图形大小，如果传入数组，则根据数据范围线性分布自动计算每个图形的大小

series.dvItemStyle​

提示

详细可配置属性和配置示例见附录 1

  • 类型ItemStyleOption[]

图元样式数组，通过指定对应的 ID，可以配置所有图形中每个图元的样式。每个图形种类中的图元 ID 可能不同，详见附录 2

series.dvItemConfig​

  • 类型ItemConfigOption<T>

图形配置项，每个图形种类的配置项可能不同，详见附录 2

series.dvAnimationConfig​

  • 类型AnimationConfigs

图形的全局动画配置项，详见附录 3，一般不需要手动干预

series.dvRValueRange​

提示

与series.dvSymbolSize搭配使用。由于图表是单周期渲染，所以需要用户提供该属性，以保证所有时间周期内，半径数据相同的气泡大小相同。不提供时，以当前周期传入的数据中的极值为准。单周期可以省略该配置项。

  • 类型[number, number]

全周期 RValue 极值

series.dvKeepHighlight​

  • 类型boolean

  • 默认值false

是否总保持一个点高亮，即在点击空白画布与开启临近搜索且没有搜到点时不会取消高亮

series.dvMultipleSelect​

注意

仅在 PC 端有效

  • 类型boolean

  • 默认值false

是否开启多选

series.dvAutoHide​

  • 类型{enable: boolean, delay?: number}

是否开启自动取消高亮，即触发自动取消高亮的延时

series.dvNearSearch​

注意

仅在移动端有效

  • 类型{enable: boolean, trigger?: 'mousemove' | 'click' | 'all'}
  • 默认值{enable:false, trigger: 'mousemove'}

是否开启临近搜索，以及临近搜索的触发方式

series.labelLayout.dvAutoLayout​

  • 类型boolean
  • 默认值true

是否开启 label 的自动布局，即坐标系的上半部分散点 label position 为'bottom'，下半部分散点 label position 为'top'

xAxis.dvNameLocation​

  • 类型'right'|'center'|'left'

X 轴名称所在的位置

yAxis.dvNameLocation​

  • 类型'right'|'left'

Y 轴名称所在的位置

数据配置项​

沿用 ECharts 的设计理念，传入的数据可以是数组，也可以是对象

在气泡图中，推荐使用对象，通过原生或者扩展的配置项，可以更加细粒度的控制单个气泡的样式和行为

option:{
    series:{
        type:'dvScatter',
        data: [
   // arr
            [10,10,10], // [xValue,yValue,rValue]
            // object
            {
    value:[10,10,10],// [xValue,yValue,rValue]
                itemStyle: [],
                itemConfig: [],
                // ...other options
            }
        ]
    }
}

dataItem.name​

备注

该属性为 ECharts 原生属性，此处仅作补充说明

在不同生命周期中，name属性相同的数据会开启过度动画，如果没有name属性，则默认使用数据下标

dataItem.value​

备注

该属性为 ECharts 原生属性，此处仅作补充说明

value 为数组，其中索引 0，1，2 与组件约定为 XValue，YValue，RValue，用户可以在后续索引追加自定义信息以便在各种 API 中获取这部分信息，比如 label 的 formatter，或者 tooltip 的 formatter 等

当用户场景下的 RValue 没有差异时，可以均设置为 1

dataItem.itemStyle​

注意

按照命名规则，dataItem中的itemStyle和itemConfig应该增加dv前缀

但是由于这里已经取代了原有的 ECharts 设计，为了防止使用者在dataItem.itemStyle与dataItem.dvItemStyle中混淆不清，故采用itemStyle

在简单情况下，series.itemStyle中的部分属性仍然有效，比如color，但还是推荐使用series.dvItemStyle

  • 类型ItemStyleOption[]

图元样式数组，通过指定对应的 ID，可以配置所有图形中每个图元的样式。每个图形种类中的图元 ID 可能不同，详见附录 2

dataItem.itemConfig​

  • 类型ItemConfigOption<T>

图形配置项，每个图形种类的配置项可能不同，详见附录 2

dataItem.nextValue​

注意

这看起来不是一个很好的封装，可能会在后续版本中变更

  • 类型number[]

传入一组 X，Y 数据，绘制时，生成一条线，连接【该数据对应的坐标点】与【当前图形中心】，可以通过该配置项实现历史轨迹

dataItem.preValue​

注意

这看起来不是一个很好的封装，可能会在后续版本中变更

  • 类型number[]

传入一组 X，Y 数据，图形将会从圆形气泡变为外接等边三角形，并旋转到与前一个点链接线的角度，一般用于最后一个点用以指明运动趋势

Action​

这里的 API 需要通过 ECharts 实例的 dispatchAction 方法调用。

调用示例参考ECharts 原生 highlight 调用

提示

以下action接受同一参数类型：

export type ActionPayloadApplication = ActionPayload & {
  // 可选，是否开启反选
  reverse?: boolean;
};

type ActionPayload = {
  // 用 index 或 name 来指定系列。
  // 可以使用数组指定多个系列。
  seriesIndex?: number | number[];
  seriesName?: string | string[];

  // 用 index 或 name 来指定数据。
  // 可以使用数组指定多个数据。
  dataIndex?: number | number[];
  dataName?: string | string[];

  // 用 dataIndex 或 dataName 来指定数据。
  itemsInfo?: { seriesIndex: number; dataIndex: number }[];
};

dvHighlight​

  • dvHighlight

触发指定范围内气泡的高亮样式

dispatchAction({
    type: 'dvHighlight',
    ...params:ActionPayloadApplication
})

dvDownplay​

  • dvDownplay

触发指定范围内气泡取消高亮

dispatchAction({
    type: '`dvDownplay',
    ...params:ActionPayloadApplication
})

dvSelect​

  • dvSelect

触发指定范围内气泡的选中样式（目前取高亮样式，后续有需求后再做扩展）

dispatchAction({
    type: 'dvSelect',
    ...params:ActionPayloadApplication
})

dvUnselect​

  • dvUnselect

触发指定范围内气泡的选中样式（目前取高亮样式，后续有需求后再做扩展）

dispatchAction({
    type: 'dvUnselect',
    ...params:ActionPayloadApplication
})

dvEmphasis​

  • dvEmphasis

触发指定范围内气泡的选中样式（目前取高亮样式，后续有需求后再做扩展）

dispatchAction({
    type: 'dvEmphasis',
    ...params:ActionPayloadApplication
})

dvBlur​

  • dvBlur

触发指定范围内气泡的选中样式（目前取高亮样式，后续有需求后再做扩展）

dispatchAction({
    type: 'dvBlur',
    ...params:ActionPayloadApplication
})

事件​

dvhighlight​

  • dvhighlight

监听高亮事件

chart.on('dvhighlight', (event) => {
  // your code
});

dvdownplay​

  • dvdownplay

监听取消高亮事件

chart.on('dvdownplay', (event) => {
  // your code
});

dvselect​

  • dvselect

监听选中事件

chart.on('dvselect', (event) => {
  // your code
});

dvunselect​

  • dvunselect

监听取消选中事件

chart.on('dvunselect', (event) => {
  // your code
});

dvemphasis​

  • dvemphasis

监听高亮事件，与dvhighlight的区别是dvhighlight会同事触发其他未选中点的dvBlur状态

chart.on('dvemphasis', (event) => {
  // your code
});

dvblur​

  • dvblur

监听高亮事件，与dvhighlight的区别是dvhighlight会同事触发其他未选中点的dvBlur状态

chart.on('dvblur', (event) => {
  // your code
});

dv:autoHideScatter​

  • dv:autoHidScatter

监听自动取消高亮事件

chart.on('dv:autoHidScatter', (event) => {
  // your code
});

dv:nearSearch​

  • dv:nearSearch

监听临近搜索事件

chart.on('dv:nearSearch', (event) => {
  // your code
});

附录 1：itemStyle​

提示

1.一般情况下，使用者只需要关注*标记的内容

2.style 中的配置项会与 ECharts 外部的配置项有所不同，比如外部的 color，在内部一般是 fill（填充颜色）或者 stroke（描边颜色）,是更加原生的属性

配置项类型默认值描述
typestring/图元类型，一般不需指定
xnumber/图元 X 坐标，一般不需指定
ynumber/图元 Y 坐标，一般不需指定
rotationnumber0图形旋转弧度（非角度），一般不需指定
scaleXnumber1x 方向缩放倍率，一般不需指定
scaleYnumber1y 方向缩放倍率，一般不需指定
originXnumber0缩放 X 原点，一般不需指定
originYnumber0缩放 Y 原点，一般不需指定
transitionstring|Array/图元变换时参与动画的属性，一般不需指定
enterFromObject/图元入场动画，允许同一组图元由各自的入场动画，一般不需指定
leaveToObject/图元出场动画，允许同一组图元由各自的出场动画，一般不需指定
silentbooleanfalse图元是否响应鼠标事件，一般不需指定
invisblebooleanfalse图元是否可见，一般不需指定
ignorebooleanfalse图元是否既不可见，也不响应事件，一般不需指定
*textContentObject/图元上的 label 样式配置，参见ECharts 官方文档-Text，需要通过该属性来指定标签的文本内容，见下方示例
*textConfigObject/图元上的 label 功能配置，参见ECharts 官方文档-textConfig，开启dvAutoLayout后，会自动计算其中的position属性
shapeObject/图元形状配置项，一般不需指定
*styleObject/图元样式配置项
*emphasis.styleObject/图元高亮状态下的样式
*blur.styleObject/图元非高亮状态下的样式
*select.styleObject/图元选中状态下的样式

label example:

dataItem:{
    value:[1,2,3],
    itemStyle:[
        {
            id: 'circle', //每个图形下的主图元ID，见附录2
            textContent:{
               style:{ ext: '' },  //常态下的label
                blur:{
     style:{ text:'' }, //非高亮状态下的label
             },
          emplasis: {
           style: { text: '' }, //高亮状态下的label
          }
            },
        }
    ]
}

查看官方文档以获取最新版本 ECharts 的属性：

ECharts 官方文档—自定义系列

还有部分属性，官方文档中并没有描述

比如enterFrom和leaveTo等，这些部分可以在这里找到

ECharts 官方文档—图形

附录 2：图形类型​

本附录着重描述每种图形类型的自定义配置项与图元 ID

circle​

图示： img

图元 ID：

  • group：所有图形的抽象父级，可以在 group 上绑定动画&事件，focus属性只在 group 上生效

  • circle：气泡本体，即主图元

  • image：图片，当自定义配置项中传入image时有效，为图示中的绿色部分

    需要注意，image 并不会被外层的 circle 裁切

itemConfig：

配置项类型默认值描述
image?string''图片地址，传入后，会在气泡上层绘制出图片，大小为气泡大小+气泡边宽/2
badgeText?stringundefined徽标上的文字，传入后徽标和文字一同显现
insideText?stringundefined气泡中心的文字，与 label 有所区别

附录 3：AnimationConfig​

将 ECharts 中颗粒度更小的动画时长抽象为一整个配置项，使得用户可以在这里控制所有图形的动画时长

interface AnimationConfigs {
  enterAnimation?: AnimationConfig;
  updateAnimation?: AnimationConfig;
  leaveAnimation?: AnimationConfig;
  keyframeAnimation?: KeyFrameAnimationConfig;
}

interface AnimationConfig {
  duration?: number;
  easing?: string;
  delay?: number;
}

interface KeyFrameAnimationConfig extends AnimationConfig {
  loop?: boolean;
  keyframes: Keyframe[];
}

附录 4：相比 ECharts 原生的散点图不再支持的配置项​

注意

由于实现方式不同， 原有的部分配置项可能失效，或者迁移到了新的自定义配置项中

ECharts 官方文档—散点图 dataItem 原生配置项

罗列如下：

1.【失效】symbol 失效，由于目前自定义散点图只有一种图形类型，所以该配置项目前没有作用，后续图形类型增加时会开放

2.【失效】symbolSize 失效，目前的图形大小，依赖自定义配置项中的series.dvSymbolSize和series.dvRValueRange，自动计算得出，暂不支持手动指定

提示

如果有特殊场景，可以暂时通过手动配置图形样式的方法实现

3.【迁移】symbolRotate 失效，可以在series.dvItemStyle或者dataItem.itemStyle中指定图形的旋转、缩放、偏移等样式

4.【失效】symbolKeepAspect 失效，长期内不接受path类型的图形，包括后续的扩展。如果有具体需求，可以再沟通

5.【迁移】symbolOffset 失效，可以在series.dvItemStyle或者dataItem.itemStyle中指定图形的旋转、缩放、偏移等样式

6.【迁移】emphasis、blur 与 select 失效（包括其中 label 的配置项），可以在series.dvItemStyle或者dataItem.itemStyle中指定图形、具体图元以及标签的高亮及非高亮样式

编辑此页
最后由 zhouchangju 于 更新