VISALL 环比变化柱状图 (Chain Change Bar Chart) 使用文档

简介

环比变化柱状图是VISALL数据可视化库中的专用图表类型，用于展示数据的环比变化情况。该图表以柱状图为基础，结合了箭头标记和颜色编码，直观地展示数据上升或下降的趋势及变化幅度。适用于各类环比数据分析场景，如销售额环比、用户增长环比等。

基本用法

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

// 创建环比变化柱状图
const chart = render(container, {
  layers: [
    {
      type: 'chainChangeBar',
      dataIndex: 0,
      encoding: {
        x: '月份', // X轴类别字段名
        y: '当月值', // 当前值字段名
        y1: '上月值' // 对比值字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 月份: '1月', 当月值: 320, 上月值: 280 },
        { 月份: '2月', 当月值: 120, 上月值: 190 },
        { 月份: '3月', 当月值: 220, 上月值: 150 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须提供一个字符串类型字段，用于分类
encoding.y	string	-	当前值映射字段，必须是数值类型，表示当前周期的数据值
encoding.y1	string	-	对比值映射字段，必须是数值类型，表示上一周期的数据值
dataIndex	number	0	指定使用的数据集索引

数据要求

• X轴字段要求为字符串类型
• Y和Y1轴字段要求为数值类型
• 数据量至少需要大于1条
• 提供准确的字段名映射
• Y和Y1字段必须同时存在于数据中

图表特性

1. 柱状图基础：

   • 使用渐变色柱状显示当前值(Y)
   • 柱状图使用蓝色系渐变色彩

2. 变化指示器：

   • 上升趋势使用红色标记(当Y>Y1)
   • 下降趋势使用绿色标记(当Y<Y1)
   • 包含连接线和箭头指示变化方向

3. 颜色编码：

   • 上升趋势区域填充为淡红色
   • 下降趋势区域填充为淡绿色
   • 保持视觉一致性的颜色处理

实现原理

环比变化柱状图组件内部使用了自定义渲染逻辑，主要包括以下实现细节：

1. 基础柱图渲染：使用标准柱状图展示当前值
2. 自定义图形绘制：使用ECharts的custom系列实现变化指示器
3. 变化计算：对比Y和Y1字段值确定变化方向和幅度
4. 颜色处理：使用rgbaToEquivalentRgb函数处理半透明颜色，确保视觉一致性
5. 动态箭头生成：根据数据变化计算箭头方向和大小

内部逻辑

图表内部实现了几个关键逻辑：

1. 变化方向判断：

   const isUp = api.value(2) < api.value(1); // Y1 < Y表示上升

2. 高度自适应：

   const interpoleHeight = Math.abs(highPoint[1] - lowPoint[1]);

3. 元素宽度计算：

   const halfWidth = barLayout[0].width * 0.5;
   const arrowWidth = Math.min(maxHalfWidth, halfWidth);

4. 箭头显示条件：

   const isShowArrow = halfWidth > 2;

潜规则与注意事项

1. 颜色编码规则：

   • 上升趋势：红色 (#ED2D00)
   • 下降趋势：绿色 (#0B975C)
   • 基础柱状：蓝色渐变 (rgba(77,89,153,0.5) 到 rgba(77,89,153,0.24))

2. 箭头显示逻辑：

   • 当柱宽足够大时才显示箭头(halfWidth > 2)
   • 箭头大小有最大限制(maxHalfWidth = 8)

3. 透明度处理：

   • 使用特殊函数处理RGBA颜色，确保在白色背景下视觉效果一致

4. 图例处理：

   • 图例项不可选择(disableSelect: true)
   • 固定图例颜色顺序: ['#4D5999', '#ED2D00', '#0B975C']

5. 渲染优先级：

   • 变化指示器的z索引设置为100，确保显示在最上层

示例

基础环比变化柱状图

{
  type: 'chainChangeBar',
  encoding: {
    x: '月份',
    y: '当月销售额',
    y1: '上月销售额'
  }
}

年度环比分析

{
  type: 'chainChangeBar',
  encoding: {
    x: '年份',
    y: '当年利润',
    y1: '上年利润'
  }
}

常见问题解决

1. 箭头显示不清晰

   • 检查容器宽度是否足够
   • 减少数据点数量或增加容器宽度

2. 颜色显示异常

   • 检查数据值是否正确
   • 确认Y和Y1字段映射是否准确

3. 图表显示不全

   • 确保容器高度足够
   • 检查数据是否包含极端值

4. 自定义颜色

   • 目前不支持直接自定义颜色，颜色编码固定表示上升/下降趋势
   • 如需自定义，需要修改源码中的颜色常量