VISALL 动态折线图 (Dynamic Line Chart) 使用文档

简介

动态折线图是VISALL数据可视化库中的一种高级图表类型，专为展示时间序列数据的动态变化设计。该组件能够生动地展示数据随时间的变化趋势，并支持动画效果，使数据变化过程更加直观可视。

基本用法

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

// 创建动态折线图
const chart = render(container, {
  layers: [
    {
      type: 'dynamicLine',
      dataIndex: 0,
      encoding: {
        x: '日期', // X轴时间字段名
        y: '销售额' // Y轴数值字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 日期: '2023-01-01', 销售额: 320 },
        { 日期: '2023-01-02', 销售额: 120 },
        { 日期: '2023-01-03', 销售额: 220 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	X轴映射字段，必须是日期类型字段
encoding.y	string	-	Y轴映射字段，必须是数值类型
encoding.z	string	-	可选的第三维度分类字段，用于多系列数据
dataIndex	number	0	指定使用的数据集索引
dvShowWaterMark	boolean	false	是否显示水印

数据要求

• X轴字段要求为日期类型
• Y轴字段要求为数值类型
• 数据量至少需要大于1条
• 按时间顺序提供数据，图表会自动排序

高级用法

1. 多系列动态折线图

当需要展示多个指标或多个类别的时间序列数据时，可以使用z字段进行分类：

{
  type: 'dynamicLine',
  encoding: {
    x: '日期',
    y: '销售额',
    z: '地区'
  }
}

2. 添加水印

在重要的数据可视化场景中，可以添加水印：

{
  type: 'dynamicLine',
  encoding: {
    x: '日期',
    y: '销售额'
  },
  dvShowWaterMark: true
}

潜规则与注意事项

1. 时间轴排序机制：

   • 动态折线图会自动对X轴日期数据进行升序排序，确保数据按时间顺序展示。
   • 排序通过transforms: [{ type: 'sort', order: 'ascending' }, { type: 'deDuplication' }]实现。

2. 动画过渡：

   • 数据更新时会有平滑的动画过渡效果，默认动画持续时间为1000毫秒。
   • 动画通过stateAnimation属性和LineTimeLineHelper辅助类实现。

3. 末端标签显示：

   • 动态折线图在线条末端显示标签，包含系列名称和数值。
   • 标签通过endLabel属性配置，支持富文本格式。

4. 时间轴控制：

   • 图表自带时间轴控制组件，可以手动控制数据展示的时间点。
   • 默认会显示所有时间点，按时间顺序排列。

5. 单位显示规则：

   • 如果数据中包含单位信息，会自动在坐标轴名称和提示框中显示单位。
   • 单位信息通过dataMetaInfo[字段名].unit获取。

6. 水印显示：

   • 水印默认显示当前时间点的日期信息。
   • 时间轴改变时，水印内容会自动更新。

实现原理

动态折线图组件内部实现了复杂的时间序列数据处理和动画效果：

1. 数据预处理：排序、去重和类型转换
2. 时间点提取：从数据中提取所有时间点形成时间轴
3. 多系列处理：根据z字段分类创建多条折线
4. 动画控制：使用LineTimeLineHelper辅助类控制动画效果
5. 事件监听：处理时间轴变化事件，更新图表显示

类型兼容性问题

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

1. X轴日期字段必须是有效的日期格式字符串或Date对象
2. Y轴数值必须是有效的数字类型，undefined值会导致数据点缺失
3. 时间轴处理函数依赖于正确的数据格式和事件处理

示例

基础动态折线图

{
  type: 'dynamicLine',
  encoding: {
    x: '日期',
    y: '销售额'
  }
}

多系列动态折线图

{
  type: 'dynamicLine',
  encoding: {
    x: '日期',
    y: '销售额',
    z: '产品类别'
  }
}

带水印的动态折线图

{
  type: 'dynamicLine',
  encoding: {
    x: '日期',
    y: '股价',
    z: '股票代码'
  },
  dvShowWaterMark: true
}

常见问题解决

1. 折线图不显示动画效果

   • 检查数据时间点是否正确排序
   • 确保时间轴控件正常初始化

2. 多系列数据显示不完整

   • 检查z字段值是否正确
   • 确保每个时间点的所有系列数据都存在

3. 标签显示问题

   • 检查数据单位信息是否正确设置
   • 标签格式可通过endLabel.formatter自定义

4. 水印不随时间变化

   • 确认dvShowWaterMark设置为true
   • 检查时间轴事件监听是否正常工作