VISALL 时间线图表 (TimeLine) 使用文档

简介

时间线图表是VISALL数据可视化库中的一种文本类图表，专门用于展示按时间顺序排列的事件列表。该组件能够支持不同重要程度的事件展示，并支持标签分类和自定义事件交互。

基本用法

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

// 创建时间线图表
const chart = render(container, {
  layers: [
    {
      type: 'timeLine',
      dataIndex: 0,
      encoding: {
        time: '日期',      // 时间字段名
        title: '标题',     // 事件标题字段名
        label: '分类',     // 事件分类标签字段名
        importance: '重要性' // 事件重要性字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 日期: '2023-01-01', 标题: '项目启动', 分类: '里程碑', 重要性: 3 },
        { 日期: '2023-02-15', 标题: '阶段评审', 分类: '会议,评审', 重要性: 2 },
        { 日期: '2023-03-20', 标题: '功能发布', 分类: '里程碑', 重要性: 3 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.time	string	-	时间字段映射，必须提供一个日期类型字段
encoding.title	string	-	事件标题字段映射，必须是字符串类型
encoding.label	string	-	事件标签字段映射，必须是字符串类型，可以是逗号分隔的多标签
encoding.url	string	-	可选的链接字段映射，必须是字符串类型
encoding.importance	string	-	事件重要性字段映射，必须是数值类型
dataIndex	number	0	指定使用的数据集索引
maxHeight	number	520	时间线组件最大高度
width	number	570	时间线组件宽度
customEvent	function	-	自定义事件回调函数

数据要求

time字段要求为日期类型
title字段要求为字符串类型
label字段要求为字符串类型，可以是单个值或逗号分隔的多个值
url字段（可选）要求为字符串类型
importance字段要求为数值类型
数据量至少需要大于1条
提供准确的字段名映射

高级用法

1. 自定义事件处理

时间线组件支持自定义事件处理，通过customEvent回调函数捕获用户交互：

{
  type: 'timeLine',
  encoding: {
    time: '日期',
    title: '标题',
    label: '分类',
    importance: '重要性'
  },
  customEvent: (event) => {
    console.log('用户选择了事件:', event.data);
    // 执行其他操作...
  }
}

2. 配置链接跳转

为事件添加可点击的链接：

{
  type: 'timeLine',
  encoding: {
    time: '日期',
    title: '标题',
    label: '分类',
    url: '链接',
    importance: '重要性'
  }
}

3. 自定义高度和宽度

根据容器大小调整时间线尺寸：

{
  type: 'timeLine',
  encoding: {
    time: '日期',
    title: '标题',
    label: '分类',
    importance: '重要性'
  },
  maxHeight: 800,
  width: 650
}

潜规则与注意事项

标签处理机制：
- 标签(label)字段支持两种格式：单一字符串或逗号分隔的多个标签。
- 当检测到逗号时，系统会自动将其拆分为数组：transformLabel = (item[label] as string).split(',');
重要性等级：
- 时间线使用重要性字段(importance)来区分事件的视觉显示效果。
- 重要性值越高，在视觉上的强调效果越明显。
自定义事件回调：
- 用户可通过customEvent函数捕获时间线的交互事件。
- 主要事件为'change:selected'，当用户选择时间线中的某个事件时触发。
主题配置：
- 时间线支持通过token.dvTimeLine配置自定义主题。
- 可以通过themeConfig参数调整时间线的外观样式。
标签转换规则：
- 当label字段值为字符串时，会检查是否包含逗号，如包含则自动转换为字符串数组。
- 自动转换实现方式：
```
let transformLabel = item[label];
if (typeof item[label] === 'string') {
  transformLabel = (item[label] as string).split(',');
}
```

实现原理

时间线组件内部使用了UI库中的TimeLine组件实现，主要包括以下步骤：

数据转换：将原始数据转换为TimeLine组件所需的格式
事件监听：为TimeLine组件添加事件监听
自适应布局：根据配置的maxHeight和width调整组件大小
主题适配：应用全局主题配置到时间线组件

类型兼容性问题

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

label字段的类型转换需要特别注意，在内部实现中会将字符串转换为数组
确保importance字段提供的值是有效的数值
如果提供了url字段，确保值是有效的URL格式

示例

基础时间线

{
  type: 'timeLine',
  encoding: {
    time: '时间',
    title: '事件',
    label: '类型',
    importance: '等级'
  }
}

带链接的时间线

{
  type: 'timeLine',
  encoding: {
    time: '日期',
    title: '事件名称',
    label: '事件类型',
    url: '详情链接',
    importance: '优先级'
  }
}

自定义高度的时间线

{
  type: 'timeLine',
  encoding: {
    time: '发生时间',
    title: '事件标题',
    label: '标签',
    importance: '重要性'
  },
  maxHeight: 700,
  width: 650
}

常见问题解决

标签显示不正确
- 检查label字段值的格式，如果要显示多个标签，确保使用逗号分隔
- 确认label字段在数据中存在且类型正确
时间顺序混乱
- 确保time字段的值是有效的日期格式
- 可以在数据处理阶段对时间进行预排序
自定义事件不触发
- 确保正确传入customEvent回调函数
- 检查回调函数内的代码是否有错误
显示不全或截断
- 调整maxHeight和width参数以适应容器大小
- 确保容器元素有足够的空间显示完整的时间线

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 自定义事件处理​

2. 配置链接跳转​

3. 自定义高度和宽度​

潜规则与注意事项​

实现原理​

类型兼容性问题​

示例​

基础时间线​

带链接的时间线​

自定义高度的时间线​

常见问题解决​

简介