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

简介

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

基本用法

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

// 创建排名双向条形图
const chart = render(container, {
  layers: [
    {
      type: 'rankingTwoWayHorizontalBar',
      dataIndex: 0,
      encoding: {
        x: '收入',    // 左侧数值字段
        x2: '支出',   // 右侧数值字段
        y: '部门名称', // 类别字段（用于标识每个条形）
      },
      animationDuration: 800 // 动画持续时间
    }
  ],
  data: [
    {
      values: [
        { 部门名称: 'A部门', 收入: 320, 支出: 280 },
        { 部门名称: 'B部门', 收入: 120, 支出: 90 },
        { 部门名称: 'C部门', 收入: 350, 支出: 310 },
        { 部门名称: 'D部门', 收入: 180, 支出: 150 },
        // ...更多数据
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string	-	左侧数值字段，显示在左侧条形图中，必须是数值类型
encoding.x2	string	-	右侧数值字段，显示在右侧条形图中，必须是数值类型
encoding.y	string	-	类别字段，用于标识每个条形，通常是字符串类型
dataIndex	number	0	指定使用的数据集索引
animationDuration	number	800	动画持续时间（毫秒）

数据要求

• x 字段要求为数值类型（表示左侧条形图数据）
• x2 字段要求为数值类型（表示右侧条形图数据）
• y 字段要求为字符串类型（表示排名的对象）
• 各字段数据数量需大于1
• 数据条数需大于1

高级用法

1. 自定义动画持续时间

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

{
  type: 'rankingTwoWayHorizontalBar',
  encoding: {
    x: '收入',
    x2: '支出',
    y: '部门名称'
  },
  animationDuration: 1200 // 1.2秒
}

2. 数据排序

排名双向条形图通常会自动对数据进行排序显示，无需手动排序：

{
  type: 'rankingTwoWayHorizontalBar',
  encoding: {
    x: '收入',
    x2: '支出',
    y: '部门名称'
  }
  // 数据会自动按y字段排序
}

潜规则与注意事项

1. 布局规则：

   • 左右两侧条形图布局比例固定，各占40%的容器宽度，中间留出20%空间。
   • 布局通过 grid 参数设置：width: 0.4 * containerWidth

2. 标签处理：

   • 当类别名称过长时，会自动截断并显示省略号。
   • 实现方式：if (String(value).length > 5) { return \${value.slice(0, 5)}...`; }`

3. 数据格式处理：

   • 图表会自动处理数值格式，支持多种单位显示。
   • 单位信息通过dataMetaInfo[字段名].unit获取。

4. 自动调整：

   • 图表会根据容器大小自动调整布局和元素尺寸。
   • 调整方式：Math.min(chartViewRect.width, chartViewRect.height) / 8

5. 提示框自定义：

   • 提示框会自动显示当前条形对应的类别和值。
   • 提示框通过buildTooltip函数定制。

实现原理

排名双向条形图组件内部实现包括以下几个关键步骤：

1. 数据处理：将原始数据拆分为左右两侧显示的数据集
2. 布局计算：根据容器尺寸计算左右两侧条形图的布局
3. 坐标轴配置：设置水平和垂直坐标轴的样式和显示方式
4. 条形渲染：配置条形的样式、颜色和动画效果
5. 交互响应：处理鼠标悬停等交互事件

示例

基础排名双向条形图

{
  type: 'rankingTwoWayHorizontalBar',
  encoding: {
    x: '收入',
    x2: '支出',
    y: '部门名称'
  }
}

自定义动画的排名双向条形图

{
  type: 'rankingTwoWayHorizontalBar',
  encoding: {
    x: '进口额',
    x2: '出口额',
    y: '国家'
  },
  animationDuration: 1500
}

常见问题解决

1. 图表显示不完整

   • 检查容器大小是否足够
   • 确保数据量不超出显示限制
   • 考虑调整容器大小或减少数据量

2. 数据显示异常

   • 确保x和x2字段为数值类型
   • 检查数据中是否存在异常值或缺失值
   • 检查y字段是否为唯一标识

3. 颜色配置问题

   • 默认使用系统配色方案（蓝色和橙色）
   • 可以通过主题或全局配置修改默认颜色

4. 文本溢出问题

   • 类别名称过长时会自动截断
   • 可以考虑使用更短的类别名称或自定义tooltips显示完整名称