VISALL 大事指标折线图 (Marker Line) 使用文档

简介

大事指标折线图是VISALL数据可视化库中的特殊图表类型，它结合了折线图和散点图的特性，用于展示时间序列数据中的重要事件和指标。该组件能够在连续的数据趋势线上标记关键事件点，并为每个事件提供详细说明。

基本用法

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

// 创建大事指标折线图
const chart = render(container, {
  layers: [
    {
      type: 'markerLine',
      dataIndex: 0,
      encoding: {
        x: '日期', // X轴字段名，字符串或日期类型
        y: '销售额', // Y轴字段名，数值类型
        y2: '事件类型', // 事件类型字段名，字符串类型
        subTitle: '子标题', // 可选，事件子标题
        desc: '描述', // 可选，事件详细描述
        link: '链接' // 可选，事件相关链接
      }
    }
  ],
  data: [
    {
      values: [
        { 日期: '2023-01-01', 销售额: 320, 事件类型: '产品发布', 子标题: '新版本', 描述: '发布了V2.0版本', 链接: 'https://example.com' },
        { 日期: '2023-02-01', 销售额: 120, 事件类型: null },
        { 日期: '2023-03-01', 销售额: 220, 事件类型: '市场活动', 子标题: '促销', 描述: '春季促销活动' },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	必填	说明
encoding.x	string	是	X轴映射字段，必须提供一个字符串或日期类型字段
encoding.y	string	是	Y轴映射字段，必须是数值类型，用于绘制趋势线
encoding.y2	string	是	事件类型字段，用于标记和分类重要事件
encoding.subTitle	string	否	事件子标题字段，补充事件类型的额外信息
encoding.desc	string	否	事件描述字段，提供事件的详细说明
encoding.link	string	否	事件链接字段，点击事件标记可跳转至此链接
dataIndex	number	否	指定使用的数据集索引，默认为0

数据要求

X轴字段要求为字符串或日期类型
Y轴字段要求为数值类型
Y2字段要求为字符串类型，用于显示事件类型
数据量至少需要大于1条
X轴数据需要有2个或以上的不同值
事件标记仅在y2字段有值的数据点上显示

高级用法

1. 添加事件详细描述

当需要为特定事件提供详细说明时，可以使用desc字段：

{
  type: 'markerLine',
  encoding: {
    x: '日期',
    y: '指标值',
    y2: '事件类型',
    desc: '事件描述'
  }
}

2. 添加可点击的链接

为事件标记添加链接，使用户能够点击查看相关详情：

{
  type: 'markerLine',
  encoding: {
    x: '日期',
    y: '指标值',
    y2: '事件类型',
    link: '详情链接'
  }
}

3. 事件分类展示

使用不同的事件类型值，系统会自动使用不同颜色区分展示：

{
  type: 'markerLine',
  encoding: {
    x: '时间',
    y: '股价',
    y2: '事件类型' // 数据中包含不同类型：'财报发布'、'人事变动'、'战略调整'等
  }
}

潜规则与注意事项

事件标记文本处理规则：
- 每个标记描述的单行最多显示14个字符
- 每个标记描述最多显示3行，超出部分会被截断并显示"..."
- 实现代码中的限制：processString(item[desc] as string, maxCharNum, maxLineNum)
同一X轴位置的多事件处理：
- 当同一个X轴位置存在多个事件时，会自动垂直堆叠显示
- 堆叠位置通过优先级计算：item[priorityAttr] = currPriority
- 事件标记高度会根据描述文本长度自适应
图例交互机制：
- 点击图例可以控制对应事件类型的显示/隐藏
- 趋势线（主Y轴数据）始终显示，不受图例控制
- 实现了单选切换功能：legendIns.on('legendClick', e => {...})
事件标记样式自动计算：
- 标记颜色根据事件类型自动分配
- 标记连接线使用虚线样式，高亮时显示实线
- 标记背景色为对应颜色的半透明版本
响应式布局：
- 系统会根据容器大小自动调整图表布局
- 当数据点较多时，会自动启用横向滚动条
- 图表高度会根据事件数量和容器大小自适应
点击跳转功能：
- 当配置了link字段时，点击事件标记会在新标签页打开链接
- 实现通过：window.open(e.data?.link, '_blank')

实现原理

大事指标折线图组件内部使用了复杂的数据处理和渲染逻辑，主要包括以下步骤：

数据预处理：对X轴数据进行排序和去重
事件标记处理：计算同一X轴位置的事件堆叠情况
文本处理：对超长描述进行分行和截断处理
交互处理：实现高亮、图例交互和点击跳转

示例

基础大事指标折线图

{
  type: 'markerLine',
  encoding: {
    x: '日期',
    y: '股价',
    y2: '重大事件'
  }
}

带详细描述的大事指标折线图

{
  type: 'markerLine',
  encoding: {
    x: '季度',
    y: '业绩',
    y2: '事件类型',
    subTitle: '事件子标题',
    desc: '详细描述'
  }
}

可点击跳转的大事指标折线图

{
  type: 'markerLine',
  encoding: {
    x: '时间线',
    y: '指标值',
    y2: '里程碑',
    link: '详情页面'
  }
}

常见问题解决

事件标记显示不全
- 检查容器高度是否足够
- 确认y2字段在数据中正确设置
事件描述过长
- 系统会自动截断过长的描述，每行最多14个字符，最多3行
- 如需显示更多内容，建议使用链接字段，引导用户查看详情
同一位置事件过多导致重叠
- 系统会自动垂直堆叠同一X轴位置的多个事件
- 如果事件过多，建议筛选最重要的事件显示
图例交互不生效
- 确保数据中的事件类型字段(y2)值正确设置
- 检查事件类型是否唯一，避免重复值导致混淆

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 添加事件详细描述​

2. 添加可点击的链接​

3. 事件分类展示​

潜规则与注意事项​

实现原理​

示例​

基础大事指标折线图​

带详细描述的大事指标折线图​

可点击跳转的大事指标折线图​

常见问题解决​

简介