VISALL 柱状分布图 (Bar Distribution Chart) 使用文档

简介

柱状分布图是VISALL数据可视化库中的一种特殊柱状图类型，用于展示数据的分布情况。该图表通过将数据按子项名称进行分组，并以半透明背景柱体和前景柱体相结合的方式，直观地展示各类别数据在不同维度上的分布状况。

基本用法

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

// 创建柱状分布图
const chart = render(container, {
  layers: [
    {
      type: 'barDistribution',
      dataIndex: 0,
      encoding: {
        x: '类别', // X轴字段名
        y: '数值'  // Y轴字段名
      }
    }
  ],
  data: [
    {
      values: [
        {
          类别: '类别A',
          数值: 100,
          children: [
            { name: '子项1', value: 30 },
            { name: '子项2', value: 70 }
          ]
        },
        {
          类别: '类别B',
          数值: 200,
          children: [
            { name: '子项1', value: 80 },
            { name: '子项2', value: 120 }
          ]
        },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须提供一个字符串或日期类型字段
encoding.y	string	-	Y轴映射字段，必须是数值类型
dataIndex	number	0	指定使用的数据集索引

数据要求

• X轴字段要求为字符串或日期类型
• Y轴字段要求为数值类型
• 每条数据必须包含children数组，每个子项必须包含name和value属性
• 数据量建议不超过10条，以保证图表的可读性
• X轴字段数量需要大于1，以体现分布特性

数据结构示例

柱状分布图要求的数据结构如下：

const data = [
  {
    values: [
      {
        类别: '类别A',   // X轴字段
        数值: 100,      // Y轴字段，总值
        children: [     // 子项数组，用于分布展示
          { name: '子项1', value: 30 },
          { name: '子项2', value: 70 }
        ]
      },
      // ...更多数据
    ]
  }
];

实现原理

柱状分布图内部实现包括以下主要部分：

1. 数据分组处理：使用groupDataByChildrenName函数，将所有数据中的子项按名称进行分组
2. 背景柱体：半透明的大柱体，表示该类别的总数值
3. 前景柱体：按子项分组显示的小柱体，叠加显示在背景柱体上
4. 布局设置：通过设置恰当的柱宽比例和间距，确保视觉美观

潜规则与注意事项

1. 子项分组机制：

   • 所有数据中的子项会按照name属性进行自动分组，相同名称的子项会在图表中以相同颜色显示
   • 实现依赖groupDataByChildrenName函数，确保数据中子项的name属性有一致性

2. 柱宽设置：

   • 背景柱宽度固定为90%
   • 前景分布柱宽度固定为12.85%
   • 分布柱间距固定为50%，确保视觉美观

3. 颜色设置：

   • 背景柱默认使用半透明的蓝色：rgba(77,89,153,0.20)
   • 前景分布柱默认使用实心蓝色：#4D5999
   • 目前颜色方案是固定的，未来版本可能会支持自定义

常见问题解决

1. 子项显示不全或混乱

   • 检查数据中的children数组格式是否正确
   • 确保所有子项都有唯一的name属性
   • 子项的value值之和应该等于或接近总数值

2. 图表显示不全

   • 检查容器大小是否足够
   • 数据量过大可能导致显示不佳，建议控制在10条以内

3. 自定义样式

   • 当前版本暂不支持自定义颜色和样式
   • 如需自定义，可以通过修改源码中的相关配置实现

示例

产品销售分布

{
  type: 'barDistribution',
  encoding: {
    x: '产品',
    y: '销售额'
  }
}

// 数据示例
[
  {
    产品: 'A产品',
    销售额: 1200,
    children: [
      { name: '国内', value: 700 },
      { name: '国外', value: 500 }
    ]
  },
  {
    产品: 'B产品',
    销售额: 1500,
    children: [
      { name: '国内', value: 900 },
      { name: '国外', value: 600 }
    ]
  }
]

部门人员分布

{
  type: 'barDistribution',
  encoding: {
    x: '部门',
    y: '人数'
  }
}

// 数据示例
[
  {
    部门: '技术部',
    人数: 50,
    children: [
      { name: '初级', value: 20 },
      { name: '中级', value: 18 },
      { name: '高级', value: 12 }
    ]
  },
  {
    部门: '销售部',
    人数: 40,
    children: [
      { name: '初级', value: 15 },
      { name: '中级', value: 20 },
      { name: '高级', value: 5 }
    ]
  }
]