VISALL 多指标环状仪表盘 (Multi-indicator Ring Gauge) 使用文档

简介

多指标环状仪表盘是VISALL数据可视化库中的专用图表类型之一，用于同时展示多个指标值。该组件以环形布局展示各指标，使用进度条形式直观呈现各指标数值，适用于多KPI指标展示、多维度评估、多项目进度监控等场景。

基本用法

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

// 创建多指标环状仪表盘
const chart = render(container, {
  layers: [
    {
      type: 'multiIndicatorRingGauge',
      dataIndex: 0,
      encoding: {
        x: ['收入完成率', '利润完成率', '成本控制率'] // 多个数值字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 
          收入完成率: 75.5, 
          利润完成率: 68.3, 
          成本控制率: 90.2
        }
      ]
    }
  ]
});

配置参数

参数	类型	默认值	说明
encoding.x	string[]	-	映射字段数组，必须提供至少一个数值类型字段
dataIndex	number	0	指定使用的数据集索引

数据要求

• 所有字段要求为数值类型
• 数据量必须为1条
• 提供准确的字段名映射

高级用法

利用单位信息

多指标环状仪表盘会自动从数据元信息中读取单位并展示

潜规则与注意事项

1. 自适应布局：

   • 组件会根据容器大小和指标数量自动调整布局，确保合理展示所有指标。
   • 指标名称和值会根据实际宽度自动计算位置以避免重叠。

2. 数据展示规则：

   • 指标值支持动态数字变化效果（通过valueAnimation: true实现）。
   • 指标值会以小方框形式展示，包含边框和填充。

3. 图表与K线图兼容性：

   • 当与HXKLine图表共存时，仪表盘会自动调整布局以适应K线图的显示需求。
   • 相关代码：const hasSubKLine = hooks.layout(api).mainView.hasHXKLineLayer;

4. 单位显示规则：

   • 如果数据中包含单位信息，会自动在指标名称后以括号形式显示单位。
   • 单位获取逻辑：

     const name = `${gauge}${result.unit ? `(${result.unit})` : ''}`;
   • 值框中也会自动展示带单位的格式化数值。

实现原理

多指标环状仪表盘组件内部使用了ECharts的gauge类型，主要包括以下步骤：

1. 数据解析：获取多个指标数值并格式化
2. 布局计算：根据指标数量和容器大小计算合适的环形大小和位置
3. 文本布局：计算指标名称和值的位置，避免重叠
4. 样式应用：设置环形进度条、标签等视觉元素

类型兼容性问题

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

1. encoding.x必须是字符串数组而非单个字符串
2. 确保所有提供的数据字段都是数值类型
3. 数据处理过程中需要进行正确的类型转换

示例

基础多指标环状仪表盘

{
  type: 'multiIndicatorRingGauge',
  encoding: {
    x: ['指标A', '指标B', '指标C']
  }
}

双指标环状仪表盘

{
  type: 'multiIndicatorRingGauge',
  encoding: {
    x: ['完成率', '满意度']
  }
}

常见问题解决

1. 指标显示重叠

   • 减少指标数量，建议不超过4个
   • 增加容器宽度以获得更好的布局效果
   • 使用简短的指标名称

2. 数值格式问题

   • 确保数据类型为数值
   • 如需特定格式，可在数据元信息中设置单位

3. 布局调整需求

   • 当前组件会自动计算最佳布局，暂不支持手动调整
   • 如需特殊布局，可通过调整容器大小间接影响布局