VISALL 动态气泡图 (Dynamic Bubble) 使用文档

简介

动态气泡图是VISALL数据可视化库中的高级散点图表类型之一，通过时间序列展示数据点在二维空间中的动态变化。该组件支持气泡大小映射、多维度数据分析以及时间序列动画，适用于展示随时间变化的多维数据关系。

基本用法

import { render } from 'path/to/bundle.esm.min.js';

// 创建动态气泡图
const chart = render(container, {
  layers: [
    {
      type: 'dynamicBubble',
      dataIndex: 0,
      encoding: {
        x: 'GDP',      // X轴字段名
        y: '人均收入',  // Y轴字段名
        color: '国家',  // 颜色分类字段
        group: '年份',  // 时间分组字段
        size: '人口'    // 气泡大小字段（可选）
      },
      animationDuration: 1500
    }
  ],
  data: [
    {
      values: [
        { 国家: '中国', 年份: '2018', GDP: 13.6, 人均收入: 9700, 人口: 14 },
        { 国家: '美国', 年份: '2018', GDP: 20.5, 人均收入: 62000, 人口: 3.3 },
        { 国家: '中国', 年份: '2019', GDP: 14.3, 人均收入: 10500, 人口: 14.1 },
        { 国家: '美国', 年份: '2019', GDP: 21.4, 人均收入: 65000, 人口: 3.3 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须提供一个数值类型字段
encoding.y	string	-	Y轴映射字段，必须提供一个数值类型字段
encoding.color	string	-	气泡颜色映射字段，通常是分类字段
encoding.group	string	-	时间分组字段，用于动态展示不同时间点的数据
encoding.size	string	-	可选的气泡大小映射字段，必须是数值类型
dataIndex	number	0	指定使用的数据集索引
animationDuration	number	1200	动画过渡时间，单位为毫秒
dvShowWaterMark	boolean	false	是否显示水印（通常包含当前时间点信息）

数据要求

X轴字段要求为数值类型
Y轴字段要求为数值类型
分组字段通常为日期或字符串类型
同一个时间点内的数据项color字段值不应重复
每个时间点数据量至少需要2条以上
时间序列至少需要2个时间点

高级用法

1. 调整气泡大小范围

动态气泡图会根据视图大小自动调整气泡的最小和最大尺寸，也可通过设置布局类型间接控制：

{
  type: 'dynamicBubble',
  encoding: {
    x: 'GDP',
    y: '人均收入',
    color: '国家',
    group: '年份',
    size: '人口'
  },
  layout: 'large' // 可选值: small, small_2_1, small_1_2, large, large_3_2
}

2. 调整动画速度

通过animationDuration参数控制动画过渡的速度：

{
  type: 'dynamicBubble',
  encoding: {
    x: 'GDP',
    y: '人均收入',
    color: '国家',
    group: '年份'
  },
  animationDuration: 2000 // 动画时长为2秒
}

3. 显示水印

在动态气泡图上显示当前时间点水印：

{
  type: 'dynamicBubble',
  encoding: {
    x: 'GDP',
    y: '人均收入',
    color: '国家',
    group: '年份'
  },
  dvShowWaterMark: true
}

潜规则与注意事项

气泡大小自适应规则：

气泡大小会根据layout类型自动调整范围，例如在large_3_2布局下范围为[20, 120]

实现代码中的映射关系：

const sizeRangeMap = {
  [util.const.LAYOUT.SMALL]: [8, 28],
  [util.const.LAYOUT.SMALL_2_1]: [8, 46],
  [util.const.LAYOUT.SMALL_1_2]: [8, 46],
  [util.const.LAYOUT.LARGE]: [16, 92],
  [util.const.LAYOUT.LARGE_3_2]: [20, 120]
};

数据排序机制：
- 时间分组字段会自动按升序排序，确保动画从早到晚展示
- 排序通过util.dataTransform.transform(data, [{ type: 'sort', field: groupBy, order: 'ascending' }])实现
颜色映射规则：
- 当分类数量超过颜色列表长度时，会循环使用颜色列表
- 颜色通过colorList[index % colorList.length]分配
时间轴与图例联动：
- 时间轴变化时会自动更新图例内容，反映当前时间点的数据分类
- 通过timelineIns?.on('change', e => { legendIns?.update(helperOptions[e.index].legend.data); })实现
单位显示规则：
- 坐标轴名称会自动附加单位信息，格式为"字段名(单位)"
- 单位信息通过dataMetaInfo[字段名].unit获取

实现原理

动态气泡图组件内部使用了复杂的数据处理和动画逻辑，主要包括以下步骤：

数据预处理：按时间分组、排序、去重和类型转换
数据编码：将原始数据映射到视觉通道（位置、颜色、大小）
时间轴构建：为每个时间点创建对应的图表配置
动画控制：使用专用的DynamicDvScatterHelper控制动画过渡效果

类型兼容性问题

使用本组件时，需要注意以下类型兼容性问题：

所有数值类型字段必须能够正确转换为数字类型
时间分组字段需要能够正确排序（最好是标准日期格式或有序字符串）
确保每个时间点内的分类标识（color字段）不重复

示例

基础动态气泡图

{
  type: 'dynamicBubble',
  encoding: {
    x: 'GDP',
    y: '人均收入',
    color: '国家',
    group: '年份'
  }
}

带大小映射的动态气泡图

{
  type: 'dynamicBubble',
  encoding: {
    x: 'GDP',
    y: '人均收入',
    color: '国家',
    group: '年份',
    size: '人口'
  },
  animationDuration: 1500,
  dvShowWaterMark: true
}

常见问题解决

气泡不显示或重叠
- 检查数据中x/y值是否有效数值
- 确保同一时间点的分类字段没有重复值
动画效果不流畅
- 减少数据量或增加animationDuration值
- 检查浏览器性能是否足够
时间轴不显示
- 确保group字段值有多个不同的时间点
- 检查group字段值是否能正确排序
单位显示问题
- 确保在数据元信息中正确设置了单位信息

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 调整气泡大小范围​

2. 调整动画速度​

3. 显示水印​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础动态气泡图​

带大小映射的动态气泡图​

常见问题解决​

简介