VISALL 叠加看板柱状图 (Stack Board Bar Chart) 使用文档

简介

叠加看板柱状图是VISALL数据可视化库中的特色图表类型之一，结合了柱状图和迷你趋势图的特点，能够在柱状图的基础上叠加数据趋势看板，直观展示数据的当前值和历史变化趋势。该组件非常适合用于展示带有时间序列的关键指标数据，特别是需要关注数值变化趋势的场景。

基本用法

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

// 创建叠加看板柱状图
const chart = render(container, {
  layers: [
    {
      type: 'stackBoardBar',
      dataIndex: 0,
      encoding: {
        x: '月份', // X轴字段名（类别）
        y: '销售额', // Y轴字段名（数值）
        z: '趋势数据' // Z轴字段名（趋势数组）
      }
    }
  ],
  data: [
    {
      values: [
        { 月份: '1月', 销售额: 320, 趋势数据: [300, 310, 320, 330, 320] },
        { 月份: '2月', 销售额: 120, 趋势数据: [150, 140, 130, 120, 110] },
        { 月份: '3月', 销售额: 220, 趋势数据: [180, 190, 200, 210, 220] },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须提供一个字符串类型字段作为类别
encoding.y	string	-	Y轴映射字段，必须是数值类型，表示柱状图的高度
encoding.z	string	-	Z轴映射字段，必须提供一个包含数值数组的字段，用于展示趋势
dataIndex	number	0	指定使用的数据集索引

数据要求

X轴字段要求为字符串类型
Y轴字段要求为数值类型
Z轴字段要求为数值数组，表示历史趋势数据
趋势数据数组至少需要两个点才能展示变化趋势
数据量至少需要大于1条

高级用法

1. 数据排序

叠加看板柱状图默认会对X轴数据进行升序排序，无需手动排序：

// 数据会自动按月份进行排序
{
  type: 'stackBoardBar',
  encoding: {
    x: '月份',
    y: '销售额',
    z: '趋势数据'
  }
}

2. 趋势上升/下降颜色区分

看板中的趋势图会根据趋势的上升或下降自动使用不同的颜色：

上升趋势：绿色 (rgba(11,151,92,1))
下降趋势：红色 (rgba(237,45,0,1))

潜规则与注意事项

趋势数据判断规则：
- 通过比较趋势数组的第一个值和最后一个值来判断趋势方向
- 上升趋势：第一个值 > 最后一个值时，使用绿色
- 下降趋势：第一个值 <= 最后一个值时，使用红色
看板布局规则：
- 看板高度固定为26px
- 看板底部与柱状图顶部的间距为6px
- 趋势图容器高度为9px
- 看板具有3px的圆角和阴影效果
边缘情况处理：
- 当趋势数据不存在或只有一个数据点时，将显示一条水平线
- 当趋势数据最后一个值不存在时，显示"--"作为替代文本
数据排序机制：
- 图表默认对X轴数据进行升序排序，确保数据展示的一致性
- 排序通过utils.dataTransform.transform(data, [{ type: 'sort', field: x, order: 'ascending' }])实现

实现原理

叠加看板柱状图内部结合了标准柱状图和自定义图形绘制功能，主要包括以下步骤：

数据预处理：对原始数据进行排序和转换
柱状图绘制：使用标准ECharts柱状图作为基础
看板绘制：使用自定义系列（custom series）绘制趋势看板
趋势线绘制：根据Z轴数据绘制小型折线图

看板由以下几个部分组成：

背景面板：白色背景，带有阴影和圆角
趋势区域：根据趋势数据绘制的渐变色填充区域
趋势线：根据趋势数据绘制的折线
数值显示：显示当前值（趋势数据的最后一个值）

类型兼容性问题

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

Z轴字段必须是数组类型，否则会导致图表无法正确渲染
趋势数据数组应包含数值类型的元素
空值或异常值可能导致趋势线不连续

示例

基础叠加看板柱状图

{
  type: 'stackBoardBar',
  encoding: {
    x: '月份',
    y: '销售额',
    z: '趋势数据'
  }
}

实际应用场景

{
  type: 'stackBoardBar',
  encoding: {
    x: '产品',
    y: '当前库存',
    z: '历史库存'
  }
}

常见问题解决

看板不显示
- 检查Z轴字段是否正确配置
- 确认趋势数据是否为数组类型
趋势线颜色不符合预期
- 检查趋势数据的第一个和最后一个值是否符合上升/下降的判定规则
看板显示"--"
- 趋势数据的最后一个值可能不存在或为无效值
- 确保提供完整的趋势数据数组

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 数据排序​

2. 趋势上升/下降颜色区分​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础叠加看板柱状图​

实际应用场景​

常见问题解决​

简介