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

简介

柱状图组件是VISALL数据可视化库中的核心图表类型之一，支持常规柱状图、堆叠柱状图、分组柱状图以及水平条形图等多种展现形式。该组件能够灵活处理多维数据，支持多Y轴和多系列数据的展示。

基本用法

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

// 创建柱状图
const chart = render(container, {
  layers: [
    {
      type: 'bar',
      dataIndex: 0,
      encoding: {
        x: '月份', // X轴字段名
        y: ['销售额'] // Y轴字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 月份: '1月', 销售额: 320 },
        { 月份: '2月', 销售额: 120 },
        { 月份: '3月', 销售额: 220 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须提供一个字符串或日期类型字段
encoding.y	string[]	-	Y轴映射字段，支持单个字段或多个字段，必须是数值类型
encoding.z	string	-	可选的第三维度分类字段，用于多系列数据
dataIndex	number	0	指定使用的数据集索引
showBackground	boolean	false	是否显示柱状图背景
dvStack	boolean	false	是否启用堆叠模式
dvHorizontal	boolean	false	是否启用水平条形图模式

数据要求

X轴字段要求为字符串或日期类型
Y轴字段要求为数值类型
数据量至少需要大于1条
提供准确的字段名映射

高级用法

1. 堆叠柱状图

当需要展示数据的累积效果时，可以使用堆叠柱状图：

{
  type: 'bar',
  encoding: {
    x: '季度',
    y: ['销售额', '利润']
  },
  dvStack: true
}

2. 水平条形图

当类别较多或类别名称较长时，水平条形图通常更适合：

{
  type: 'bar',
  encoding: {
    x: '产品名称',
    y: ['销售量']
  },
  dvHorizontal: true
}

3. 多维度分析

使用z字段进行多维度分析：

{
  type: 'bar',
  encoding: {
    x: '月份',
    y: ['销售额'],
    z: '地区'
  }
}

潜规则与注意事项

多Y轴与Z维度的限制：
- 柱状图不支持同时使用多Y轴和Z维度。如果同时设置，多Y轴会被降级为单Y轴。
- 实现代码中的限制：if (isMultiYAxisWithZ) { y = [y[0]]; }
数据排序机制：
- 柱状图默认会对X轴数据进行升序排序，无需手动排序。
- 排序通过utils.dataTransform.transform(data, [{ type: 'sort', field: x, order: 'ascending' }])实现。
柱宽自适应：
- 柱状图会根据容器宽度和数据量自动计算合适的柱宽。
- 柱宽计算公式：(容器宽度 - 边距) / (数据点数 * 系列数) * 0.8
- 默认有一个最大柱宽限制，通过utils.const.BAR_MAX_WIDTH定义。
DataZoom智能显示：
- 当数据量较大导致柱宽过小时（水平方向柱宽≤12px），系统会自动显示滚动条。
- 垂直方向默认显示最后的8个数据点。
单位显示规则：
- 如果数据中包含单位信息，会自动在坐标轴名称和提示框中显示单位。
- 单位信息通过dataMetaInfo[字段名].unit获取。
复杂图表降级处理：
- 条形图模式下存在多Y轴时，会自动调整部分布局参数，如grid.top。
- X轴与Y轴在条形图模式下会自动对调。

实现原理

柱状图组件内部使用了复杂的数据处理逻辑，主要包括以下步骤：

数据预处理：排序、去重和类型转换
数据编码：将原始数据映射到视觉通道
自适应计算：根据容器大小计算图表元素尺寸
条件判断：根据配置参数和数据特性动态生成图表选项

类型兼容性问题

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

某些参数需要严格的类型定义，例如dataZoom的type属性值必须是"slider"或"inside"
数据转换函数需要注意输入类型，避免undefined值导致错误
对象属性访问前需要进行空值检查

示例

基础柱状图

{
  type: 'bar',
  encoding: {
    x: '月份',
    y: ['销售额']
  }
}

多系列分组柱状图

{
  type: 'bar',
  encoding: {
    x: '季度',
    y: ['销售额', '利润', '成本']
  }
}

堆叠条形图

{
  type: 'bar',
  encoding: {
    x: '产品',
    y: ['国内销售'],
    z: '季度'
  },
  dvStack: true,
  dvHorizontal: true
}

常见问题解决

柱状图显示不全
- 检查容器大小是否足够
- 检查数据量是否过大，考虑启用dataZoom
多维度数据展示混乱
- 注意多Y轴与Z维度不能同时使用
- 检查数据结构是否符合要求
单位显示问题
- 确保在数据元信息中正确设置了单位信息
自定义柱状图宽度
- 可通过调整容器大小或数据量间接控制柱宽
- 柱宽有最大限制，不会超过barMaxWidth设定值

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 堆叠柱状图​

2. 水平条形图​

3. 多维度分析​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础柱状图​

多系列分组柱状图​

堆叠条形图​

常见问题解决​

简介