跳到主要内容

VISALL 瀑布图 (Waterfall Chart) 使用文档

简介​

瀑布图是VISALL数据可视化库中的一种特殊柱状图类型，用于展示数值的累积变化过程，适合展示财务数据、收支变化或其他连续累积的数据序列。瀑布图通过不同颜色区分正负变化，清晰地展示从起始值到结束值的变化路径。

基本用法​

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

// 创建瀑布图
const chart = render(container, {
  layers: [
    {
      type: 'waterfall',
      dataIndex: 0,
      encoding: {
        x: '项目', // X轴字段名（类别）
        y: '金额', // Y轴字段名（数值）
        y2: '日期'  // 分组字段（时间）
      }
    }
  ],
  data: [
    {
      values: [
        { 项目: '期初', 金额: 1000, 日期: '2023-01' },
        { 项目: '收入', 金额: 500, 日期: '2023-01' },
        { 项目: '支出', 金额: -300, 日期: '2023-01' },
        { 项目: '期末', 金额: 1200, 日期: '2023-01' },
        { 项目: '期初', 金额: 1200, 日期: '2023-02' },
        { 项目: '收入', 金额: 600, 日期: '2023-02' },
        { 项目: '支出', 金额: -400, 日期: '2023-02' },
        { 项目: '期末', 金额: 1400, 日期: '2023-02' },
        // ...更多数据
      ]
    }
  ]
});

配置参数​

参数类型默认值说明
encoding.xstring-X轴映射字段，必须提供一个字符串类型字段，用于表示类别
encoding.ystring-Y轴映射字段，必须是数值类型，表示变化值
encoding.y2string-时间维度字段，用于多时间段数据的分组和时间轴展示
dataIndexnumber0指定使用的数据集索引

数据要求​

  • X轴字段要求为字符串类型，表示变化项目或类别
  • Y轴字段要求为数值类型，表示每个类别的变化值（可正可负）
  • y2字段要求为日期或字符串类型，用于时间轴分组
  • 数据量至少需要大于3条才能形成有意义的瀑布图
  • 提供准确的字段名映射

高级用法​

时间轴切换​

瀑布图支持按时间维度(y2)分组，并通过时间轴控件进行切换：

{
  type: 'waterfall',
  encoding: {
    x: '项目',
    y: '金额',
    y2: '季度'
  }
}

潜规则与注意事项​

  1. 数据转换机制：

    • 瀑布图内部使用了专门的数据转换器WaterfallHelper.transformDataset，将单一的数值序列转换为瀑布图所需的累积数据结构。
    • 无需手动计算累积值，组件会自动处理累积计算。

  2. 时间轴自动排序：

    • y2字段的值会自动按升序排列用于时间轴展示。
    • 排序通过util.dataTransform.transform(dates, [{ type: 'sort', order: 'ascending' }])实现。

  3. 标签自动显示：

    • 瀑布图会自动在柱顶显示数值标签。
    • 标签会显示原始值（非累积值）及单位。

  4. 时间水印显示：

    • 在大尺寸布局下，会在图表右上角显示当前时间段水印。
    • 当layout !== util.const.LAYOUT.SMALL时显示水印。

  5. X轴标签处理：

    • 当布局为小尺寸时，X轴标签会自动倾斜30度以避免重叠。
    • X轴标签宽度会自动根据文本长度计算，超出部分会被截断。

  6. 提示框格式化：

    • 提示框会显示每个类别的变化值，而非累积值。
    • 提示框中会自动包含单位信息。

实现原理​

瀑布图内部使用了堆叠柱状图实现，主要包括以下处理步骤：

  1. 数据分组：按照y2字段将数据分组
  2. 日期排序：对日期字段进行升序排序
  3. 数据转换：将原始数据转换为瀑布图所需的堆叠数据结构
  4. 时间轴绑定：实现时间轴与图表的交互

瀑布图内部使用了两个堆叠的系列：

  • 第一个系列是透明的，用于支撑瀑布图的结构
  • 第二个系列是可见的，展示实际的数据变化

类型兼容性问题​

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

  1. y字段必须严格为数值类型
  2. y2字段建议使用标准日期格式，如"YYYY-MM"或"YYYY-Q1"
  3. 避免使用undefined或null值，可能导致计算错误

示例​

基础瀑布图​

{
  type: 'waterfall',
  encoding: {
    x: '项目',
    y: '金额',
    y2: '月份'
  }
}

季度业绩瀑布图​

{
  type: 'waterfall',
  encoding: {
    x: '业务线',
    y: '利润贡献',
    y2: '季度'
  }
}

常见问题解决​

  1. 瀑布图显示不正确

    • 检查数据中是否存在非数值类型的y值
    • 确保数据按正确的顺序排列，类别顺序会影响瀑布图的连接关系

  2. 时间轴不显示

    • 检查y2字段是否正确设置
    • 确保数据中包含多个不同的时间值

  3. 标签显示问题

    • 如需自定义标签格式，可通过数据元信息设置单位信息
    • 大数值会自动进行单位转换，如1000显示为"1k"

  4. 自定义柱状图颜色

    • 瀑布图默认使用系统配色方案
    • 可通过全局主题设置修改颜色
编辑此页
最后由 gongyuzhouchang 于 更新