VISALL 极坐标柱状图 (Polar Bar Chart) 使用文档

简介

极坐标柱状图是VISALL数据可视化库中的特殊图表类型，它将传统柱状图映射到极坐标系中，形成环形分布的柱状图。这种图表特别适合展示周期性数据或环形分布数据，能够有效地在有限空间内展示多维数据关系。

基本用法

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

// 创建极坐标柱状图
const chart = render(container, {
  layers: [
    {
      type: 'polarBar',
      dataIndex: 0,
      encoding: {
        x: '月份', // 径向轴字段名（对应极坐标中的角度）
        y: '销售额' // 角度轴字段名（对应极坐标中的半径）
      }
    }
  ],
  data: [
    {
      values: [
        { 月份: '1月', 销售额: 320 },
        { 月份: '2月', 销售额: 120 },
        { 月份: '3月', 销售额: 220 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

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

数据要求

• x 轴字段（径向轴）要求为字符串或日期类型
• y 轴字段（角度轴）要求为数值类型
• 数据量建议小于 30 条，以确保图表清晰可读
• x 轴和 y 轴字段的数据量都需要大于 1

高级用法

自动标签显示

极坐标柱状图会根据数据量自动决定是否显示标签：

// 当数据量小于5条时，会自动显示标签
{
  type: 'polarBar',
  encoding: {
    x: '方向',
    y: '风力'
  }
}

潜规则与注意事项

1. 值域自动放大：

   • 极坐标柱状图会自动将数值最大值放大1.2倍，以确保柱状图不会占满整个圆形区域。
   • 实现代码：valueMax *= 1.2;

2. 径向轴标签优化：

   • 极坐标柱状图会自动隐藏重叠的标签，以提高可读性。
   • 配置通过 hideOverlap: true 实现。

3. 数据量限制：

   • 极坐标柱状图适合展示少量数据（建议少于30条），数据过多会导致可读性下降。
   • 当数据量较大时，标签会自动隐藏，以避免标签重叠。

4. 标签自动控制：

   • 当数据量小于5条时，会自动在柱体中间显示标签。
   • 标签格式为 {b}: {c}，显示类别名称和对应的数值。
   • 实现代码：label: { show: valueData.length < 5, position: 'middle', formatter: '{b}: {c}' }

5. 角度轴的标签控制：

   • 最大值标签会被隐藏，以避免与0重叠。
   • 配置通过 showMaxLabel: false 实现。

实现原理

极坐标柱状图组件内部基于ECharts的polar坐标系实现，主要包括以下步骤：

1. 数据预处理：将y轴数据转换为数值类型
2. 计算数值最大值并放大1.2倍作为角度轴的最大值
3. 配置径向轴（radiusAxis）和角度轴（angleAxis）
4. 创建柱状图系列，并设置为极坐标系

类型兼容性问题

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

1. y 轴数据必须是数值类型或可以转换为数值类型的字符串
2. x 轴数据应为字符串或日期类型，用作分类数据
3. 对象属性访问前需要进行空值检查，特别是 presetOption.textStyle 属性

示例

基础极坐标柱状图

{
  type: 'polarBar',
  encoding: {
    x: '月份',
    y: '销售额'
  }
}

风向分布图

{
  type: 'polarBar',
  encoding: {
    x: '风向',
    y: '频率'
  }
}

常见问题解决

1. 图表显示不完整

   • 检查容器大小是否足够
   • 确保数据量不会过多导致标签重叠

2. 数值显示异常

   • 确保y轴字段的值是数值类型或可以转换为数值类型
   • 检查数据中是否有异常值导致比例失调

3. 标签重叠问题

   • 减少数据量
   • 如果必须使用大量数据，考虑对数据进行筛选或聚合