VISALL 动态排名双向条形图 (Dynamic Ranking Two-way Horizontal Bar) 使用文档

简介

动态排名双向条形图是VISALL数据可视化库中的一种特殊图表类型，用于同时展示两个数值维度随时间变化的对比情况。它通过左右两侧的条形图展示不同维度的数据，并能通过动画效果直观地展示随时间变化的排名情况，适用于双指标对比分析，如收入与支出、进口与出口、正负评价等数据的动态变化。

基本用法

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

// 创建动态排名双向条形图
const chart = render(container, {
  layers: [
    {
      type: 'dynamicRankingTwoWayHorizontalBar',
      dataIndex: 0,
      encoding: {
        x: '收入',    // 左侧数值字段
        x2: '支出',   // 右侧数值字段
        y: '部门名称', // 类别字段（用于标识每个条形）
        group: '年份' // 时间维度字段（用于动态变化）
      },
      animationDuration: 1200, // 动画持续时间
      dvShowWaterMark: true    // 是否显示时间水印
    }
  ],
  data: [
    {
      values: [
        { 部门名称: 'A部门', 收入: 320, 支出: 280, 年份: '2020-01' },
        { 部门名称: 'B部门', 收入: 120, 支出: 90, 年份: '2020-01' },
        { 部门名称: 'A部门', 收入: 350, 支出: 310, 年份: '2020-02' },
        { 部门名称: 'B部门', 收入: 180, 支出: 150, 年份: '2020-02' },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	左侧数值字段，显示在左侧条形图中，必须是数值类型
encoding.x2	string	-	右侧数值字段，显示在右侧条形图中，必须是数值类型
encoding.y	string	-	类别字段，用于标识每个条形，通常是字符串类型
encoding.group	string	-	时间维度字段，用于动态排名的时间轴，可以是日期或字符串类型
dataIndex	number	0	指定使用的数据集索引
animationDuration	number	1200	动画持续时间（毫秒）
dvShowWaterMark	boolean	false	是否显示时间水印

数据要求

x 字段要求为数值类型（表示左侧条形图数据）
x2 字段要求为数值类型（表示右侧条形图数据）
y 字段要求为字符串类型（表示排名的对象）
group 字段要求为日期类型（表示时间维度）
x、x2、y、group 字段数据数量需大于1
数据条数需大于1

高级用法

1. 自定义动画持续时间

可以通过设置 animationDuration 参数来控制动画的播放速度：

{
  type: 'dynamicRankingTwoWayHorizontalBar',
  encoding: {
    x: '收入',
    x2: '支出',
    y: '部门名称',
    group: '年份'
  },
  animationDuration: 2000 // 2秒
}

2. 水印显示

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

{
  type: 'dynamicRankingTwoWayHorizontalBar',
  encoding: {
    x: '收入',
    x2: '支出',
    y: '部门名称',
    group: '年份'
  },
  dvShowWaterMark: true // 显示时间水印
}

潜规则与注意事项

数据呈现限制：
- 图表会自动限制每侧显示的最大条目数，默认为8个或根据容器高度自动计算。
- 实现代码中的设置：const maxDisplayNumber = 8;
- 计算公式：const yMaxNum = Math.floor((chartViewRect.height - grid[0].top - grid[0].bottom) / 15);
布局规则：
- 左右两侧条形图布局比例固定，各占40%的容器宽度，中间留出20%空间。
- 布局通过 grid 参数设置：width: 0.4 * containerWidth
数据处理：
- 系统会自动补齐缺失的数据点，确保动画连续性。
- 补齐逻辑：if (!dataItem) { fillDataset.push({...}); }
时间格式处理：
- 时间字段会自动处理格式，支持多种日期格式。
- 内部会将日期转换为数字进行排序：Number(el[groupBy].replaceAll('-', ''))
标签处理：
- 当类别名称过长时，会自动截断并显示省略号。
- 实现方式：if (String(value).length > 5) { return \${value.slice(0, 5)}...`; }`
自动播放机制：
- 图表加载后会自动从最后一个时间点开始播放。
- 自动播放通过延时函数实现：setTimeout(() => { chartPlayByIndex(originDates.length - 1, 'axisClick'); }, 16);

实现原理

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

数据预处理：提取唯一的名称列表和时间列表
数据编码：将原始数据映射到左右两侧的条形图
缺失数据补齐：确保每个时间点都有完整的数据集
布局计算：根据容器大小计算左右两侧条形图的布局
动画控制：根据时间变化自动更新图表状态
交互处理：响应时间轴的变化事件

示例

基础动态排名双向条形图

{
  type: 'dynamicRankingTwoWayHorizontalBar',
  encoding: {
    x: '收入',
    x2: '支出',
    y: '部门名称',
    group: '季度'
  }
}

带水印的动态排名双向条形图

{
  type: 'dynamicRankingTwoWayHorizontalBar',
  encoding: {
    x: '进口额',
    x2: '出口额',
    y: '国家',
    group: '年份'
  },
  dvShowWaterMark: true,
  animationDuration: 1500
}

常见问题解决

图表无法正常播放
- 检查时间维度数据是否正确排序
- 确保每个时间点都有足够的数据
- 检查数据中是否存在无效或缺失值
部分数据未显示
- 检查容器高度是否足够
- 容器高度限制了可显示的最大条目数
- 默认最多显示8个条目，可能需要更大的容器
时间格式问题
- 确保时间字段格式一致且正确
- 支持的格式包括：'YYYY-MM'、'YYYY-MM-DD'等
左右两侧条形图比例不均
- 左右两侧条形图布局比例固定，各占40%的容器宽度
- 可能需要调整容器大小或考虑使用其他图表类型

简介​

基本用法​

配置参数​

数据要求​

高级用法​

1. 自定义动画持续时间​

2. 水印显示​

潜规则与注意事项​

实现原理​

示例​

基础动态排名双向条形图​

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

常见问题解决​

简介