VISALL 带状区间趋势折线图 (Banded Interval Trend Line) 使用文档

简介

带状区间趋势折线图是VISALL数据可视化库中的一种特殊折线图类型，它不仅展示了数据的主要趋势线，还通过带状区间（区间带）展示了数据的置信区间或波动范围。这种图表特别适合于展示包含不确定性的时间序列数据，如股票价格预测、天气预报、销售预测等场景。

基本用法

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

// 创建带状区间趋势折线图
const chart = render(container, {
  layers: [
    {
      type: 'bandedIntervalTrendLine',
      dataIndex: 0,
      encoding: {
        x: '日期',      // X轴字段名（时间维度）
        y: '实际值',    // 主要趋势线字段名
        y2: '上限值',   // 区间上边界字段名
        y3: '下限值'    // 区间下边界字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 日期: '2023-01-01', 实际值: 120, 上限值: 50, 下限值: 30 },
        { 日期: '2023-01-02', 实际值: 132, 上限值: 45, 下限值: 25 },
        { 日期: '2023-01-03', 实际值: 101, 上限值: 40, 下限值: 20 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须提供一个日期类型字段
encoding.y	string	-	主趋势线映射字段，必须是数值类型
encoding.y2	string	-	区间上边界映射字段，必须是数值类型
encoding.y3	string	-	区间下边界映射字段，必须是数值类型
dataIndex	number	0	指定使用的数据集索引

数据要求

X轴字段要求为日期类型
Y、Y2、Y3轴字段要求为数值类型
数据量至少需要大于1条
提供准确的字段名映射
区间上下限数据应当合理（上限≥下限）

高级用法

1. 预测区间展示

当需要展示预测数据及其可能的波动范围时，可以使用带状区间趋势折线图：

{
  type: 'bandedIntervalTrendLine',
  encoding: {
    x: '日期',
    y: '预测销售额',
    y2: '预测上限',
    y3: '预测下限'
  }
}

2. 历史波动分析

分析历史数据的波动范围，可以设置上下限表示历史最大最小值：

{
  type: 'bandedIntervalTrendLine',
  encoding: {
    x: '月份',
    y: '平均温度',
    y2: '最高温度',
    y3: '最低温度'
  }
}

潜规则与注意事项

数据排序机制：
- 带状区间趋势折线图默认会对X轴数据（日期）进行升序排序，确保折线的连续性。
- 排序通过util.dataTransform.transform(data, [{ type: 'sort', field: x, order: 'ascending' }])实现。
区间带显示效果：
- 区间带的颜色默认是主曲线颜色的半透明版本（透明度为0.15）。
- 区间上下边界的曲线默认是不可见的（opacity: 0），仅显示填充区域。
数据类型转换：
- Y轴相关的所有数值字段都会通过toNumeric转换函数确保为数值类型。
- 这意味着您可以传入字符串形式的数字，系统会自动转换。
图例显示规则：
- 图例中只显示主趋势线（Y轴字段），不显示上下边界的线条。
- 这样保持图例的简洁性，避免图例项过多。
提示框内容过滤：
- 提示框中只显示主趋势线的数据，不显示上下边界的数据。
- 这是通过在formatter函数中筛选实现的：if (item.seriesName !== y) { return; }
单位显示规则：
- 如果数据中包含单位信息，会自动在坐标轴名称和提示框中显示单位。
- 单位信息通过dataMetaInfo[字段名].unit获取。

实现原理

带状区间趋势折线图内部使用了三条折线来实现效果：

主趋势线：可见的折线，展示核心数据趋势。
下边界线：不可见的折线，用于构建区间带的下边缘。
上边界线：不可见的折线，用于构建区间带的上边缘，带有区域填充样式。

这三条线通过stack属性进行堆叠，形成一个区间带效果。具体实现包括：

数据预处理：对日期进行排序
数据编码：将原始数据映射到视觉通道
设置系列配置：主线可见，区间线不可见但有填充区域
使用stack属性堆叠上边界和下边界线，形成区间带

类型兼容性问题

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

X轴字段必须是日期类型或可以被解析为日期的字符串
Y、Y2、Y3字段必须是数值类型或可以被转换为数值的字符串
避免使用undefined或null值作为区间边界值

示例

基础带状区间趋势折线图

{
  type: 'bandedIntervalTrendLine',
  encoding: {
    x: '时间',
    y: '股价',
    y2: '上限',
    y3: '下限'
  }
}

预测数据可视化

{
  type: 'bandedIntervalTrendLine',
  encoding: {
    x: '预测日期',
    y: '预测值',
    y2: '预测最大值',
    y3: '预测最小值'
  }
}

常见问题解决

区间带不显示
- 检查Y2和Y3字段是否正确设置
- 确保Y2和Y3的数值合理，上限值应大于下限值
时间轴显示错误
- 检查日期格式是否标准
- 确保日期数据可以被正确解析
区间透明度太高或太低
- 区间透明度固定为0.15，如需调整可以修改源码
- 修改areaStyle: { opacity: 0.15 }中的opacity值
趋势线与区间颜色不协调
- 区间颜色默认继承自主趋势线，如需自定义可修改areaStyle

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 预测区间展示​

2. 历史波动分析​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础带状区间趋势折线图​

预测数据可视化​

常见问题解决​

简介