VISALL 动态排名条形图 (Dynamic Ranking Horizontal Bar) 使用文档

简介

动态排名条形图是VISALL数据可视化库中的一种特殊图表类型，用于展示随时间变化的数据排名情况。它能够通过动画效果直观地展示不同时间点下各项数据的排名变化，常用于展示销售排名、人口变化、经济指标等随时间变化的排名数据。

基本用法

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

// 创建动态排名条形图
const chart = render(container, {
  layers: [
    {
      type: 'dynamicRankingHorizontalBar',
      dataIndex: 0,
      encoding: {
        x: '销售额', // 数值字段名（用于排名依据）
        y: '产品名称', // 类别字段名（用于标识每个条形）
        group: '年份' // 时间维度字段（用于动态变化）
      },
      dvShowWaterMark: true // 是否显示时间水印
    }
  ],
  data: [
    {
      values: [
        { 产品名称: 'A产品', 销售额: 320, 年份: '2020-01' },
        { 产品名称: 'B产品', 销售额: 120, 年份: '2020-01' },
        { 产品名称: 'A产品', 销售额: 350, 年份: '2020-02' },
        { 产品名称: 'B产品', 销售额: 180, 年份: '2020-02' },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	数值字段，用于条形图长度的表示和排名依据，必须是数值类型
encoding.y	string	-	类别字段，用于标识每个条形，通常是字符串类型
encoding.group	string	-	时间维度字段，用于动态排名的时间轴，可以是日期或字符串类型
dataIndex	number	0	指定使用的数据集索引
dvShowWaterMark	boolean	false	是否显示时间水印

数据要求

X轴字段要求为数值类型（表示排名的依据）
Y轴字段要求为字符串类型（表示排名的对象）
Group字段要求为日期类型（表示时间维度）
X轴数据数量需大于1
Y轴数据数量需大于3
Group数据数量需大于1
数据条数需大于1

高级用法

1. 水印显示

可以显示时间水印，显示当前数据对应的时间点：

{
  type: 'dynamicRankingHorizontalBar',
  encoding: {
    x: '销售额',
    y: '产品名称',
    group: '年份'
  },
  dvShowWaterMark: true // 显示时间水印
}

潜规则与注意事项

动画效果：
- 动态排名条形图有固定的动画更新频率，默认为1200毫秒。
- 实现代码中的设置：const updateFrequency = 1200;
排名标识：
- 前三名会使用特殊颜色标识（第一名为红色，第二名为橙色，第三名为黄色）。
- 标识通过富文本实现：{rank${index > 2 ? '' : index + 1}|${index + 1}}
自适应显示：
- 图表会根据容器高度自动计算能够显示的最大条形数量。
- 计算公式：const yMaxNum = Math.floor((chartViewRect.height - grid.top - grid.bottom) / 15);
时间格式处理：
- 时间字段会自动处理格式，支持多种日期格式。
- 内部会将日期转换为数字进行排序：const year = +item[groupBy].replaceAll('-', '');
条形标签：
- 每个条形的右侧会显示对应的数值，并自动格式化单位。
- 标签通过hook.formatDataNumberValue格式化。
自动排序：
- 时间维度会自动按升序排序，确保动画播放顺序正确。
- 排序通过util.dataTransform.transform(Array.from(years), [{ type: 'sort', order: 'ascending' }])实现。

实现原理

动态排名条形图组件内部使用了ThsDataVStandardChart库的DynamicHistogramHelper辅助类实现动态效果，主要包括以下步骤：

数据预处理：提取唯一的名称列表和时间列表
时间轴构建：按时间顺序排序并构建时间轴
数据映射：将原始数据映射到可视化元素
动画控制：根据时间变化自动更新图表状态
交互处理：响应时间轴的变化事件

示例

基础动态排名条形图

{
  type: 'dynamicRankingHorizontalBar',
  encoding: {
    x: '销售额',
    y: '产品名称',
    group: '季度'
  }
}

带水印的动态排名条形图

{
  type: 'dynamicRankingHorizontalBar',
  encoding: {
    x: '利润',
    y: '公司名称',
    group: '年份'
  },
  dvShowWaterMark: true
}

常见问题解决

图表无法正常播放
- 检查时间维度数据是否正确排序
- 确保每个时间点都有足够的数据
部分数据未显示
- 检查容器高度是否足够
- 容器高度限制了可显示的最大条目数
时间格式问题
- 确保时间字段格式一致且正确
- 支持的格式包括：'YYYY-MM'、'YYYY-MM-DD'等
自定义排名标记
- 可通过自定义主题修改排名标记的样式
- 修改rich.rank相关配置

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 水印显示​

潜规则与注意事项​

实现原理​

示例​

基础动态排名条形图​

带水印的动态排名条形图​

常见问题解决​

简介