VISALL 动态饼图 (Dynamic Pie Chart) 使用文档

简介

动态饼图是VISALL数据可视化库中的一种时间序列饼图，能够随着时间变化展示数据分布的动态变化过程。该组件通过时间轴控制，展示各个时间点数据的饼图分布情况，适合于展示数据随时间变化的趋势和比例关系。

基本用法

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

// 创建动态饼图
const chart = render(container, {
  layers: [
    {
      type: 'dynamicPie',
      dataIndex: 0,
      encoding: {
        x: '类别', // 类别字段名
        y: '数值',  // 数值字段名
        date: '日期' // 日期字段名，用于时间序列
      }
    }
  ],
  data: [
    {
      values: [
        { 类别: '类别A', 数值: 320, 日期: '2023-01-01' },
        { 类别: '类别B', 数值: 120, 日期: '2023-01-01' },
        { 类别: '类别A', 数值: 220, 日期: '2023-02-01' },
        { 类别: '类别B', 数值: 180, 日期: '2023-02-01' },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	类别映射字段，必须提供一个字符串类型字段
encoding.y	string	-	数值映射字段，必须是数值类型
encoding.date	string	'date'	日期映射字段，用于时间序列数据，必须是日期类型
dataIndex	number	0	指定使用的数据集索引
roseType	boolean \| string	false	是否启用南丁格尔玫瑰图模式
radius	string \| string[]	'75%'	饼图半径，可设置内外径实现环形图效果

数据要求

x字段要求为字符串类型，表示各个扇区的类别
y字段要求为数值类型，表示各个扇区的数值大小
date字段要求为日期类型，用于时间轴展示
数据量建议在10条以内（每个时间点）
对于同一个时间点，x字段值不应重复

高级用法

1. 南丁格尔玫瑰图

当需要更加直观地比较各扇区大小时，可以使用南丁格尔玫瑰图：

{
  type: 'dynamicPie',
  encoding: {
    x: '产品',
    y: '销售额',
    date: '季度'
  },
  roseType: true
}

2. 环形图

当需要在中间展示额外信息或提升美观度时，可以使用环形图：

{
  type: 'dynamicPie',
  encoding: {
    x: '支出类别',
    y: '金额',
    date: '月份'
  },
  radius: ['50%', '70%']
}

潜规则与注意事项

数据排序机制：
- 动态饼图会对每个时间点的数据按照y值进行降序排序
- 排序通过util.dataTransform.transform(data, [{ type: 'sort', field: y, order: 'descending' }])实现
- 在时间轴播放过程中，为了避免扇区位置突变，会按照类别名称排序呈现
日期数据处理：
- 动态饼图会自动提取不同的日期值，并按升序排列生成时间轴
- 日期数据通过util.dataEncoding.encoding处理，会进行去重和排序
标签自适应显示：
- 在小尺寸布局下（如sm-1*1、sm-1*2），标签会自动隐藏以优化视觉效果
- 通过showLabel = ![util.const.LAYOUT.SMALL, util.const.LAYOUT.SMALL_1_2].includes(layout)实现
环形图交互增强：
- 当设置radius参数为数组时，会自动配置hover效果，突出显示被选中的扇区
- 通过emphasis: { label: { show: true, fontSize: layout.includes('lg') ? 24 : 12 } }实现
时间轴控制逻辑：
- 每切换一个时间点时，会保持图例的选中状态
- 默认显示最后一个时间点的数据
- 时间轴的变化通过timelineIns.on('change', callback)监听并更新图表

实现原理

动态饼图组件内部使用了复杂的数据处理和时间序列控制逻辑，主要包括以下步骤：

数据预处理：按y值降序排序，提取日期数据
时间轴生成：对日期进行去重和排序，生成时间轴
数据分组：按日期将数据分组，为每个时间点生成一个饼图配置
动态渲染：通过时间轴控制动态切换不同时间点的饼图

类型兼容性问题

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

y字段必须是单一字段，不支持数组形式的多字段
date字段必须能够被转换为有效的日期格式
处理函数需要注意输入类型，避免undefined值导致错误

示例

基础动态饼图

{
  type: 'dynamicPie',
  encoding: {
    x: '地区',
    y: '销售额',
    date: '年份'
  }
}

南丁格尔玫瑰动态饼图

{
  type: 'dynamicPie',
  encoding: {
    x: '人口构成',
    y: '人口数',
    date: '年代'
  },
  roseType: 'radius'
}

环形动态饼图

{
  type: 'dynamicPie',
  encoding: {
    x: '投资类别',
    y: '投资额',
    date: '季度'
  },
  radius: ['40%', '70%']
}

常见问题解决

时间轴不显示
- 检查date字段是否正确设置
- 检查数据中是否包含多个不同的日期值
饼图扇区顺序混乱
- 在数据中保持一致的类别名称
- 数据预处理时会按y值降序和x值字母顺序排序
标签重叠问题
- 减少数据类别数量
- 考虑使用环形图配置
- 在小尺寸下标签会自动隐藏
日期格式问题
- 确保date字段的值是有效的日期格式
- 如果日期无法正确解析，可能会导致时间轴异常

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 南丁格尔玫瑰图​

2. 环形图​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础动态饼图​

南丁格尔玫瑰动态饼图​

环形动态饼图​

常见问题解决​

简介