VISALL 仪表盘 (Gauge Chart) 使用文档

简介

仪表盘组件是VISALL数据可视化库中的专用图表类型之一，用于展示单一数值相对于特定区间的位置。该组件适用于KPI指标展示、进度监控、资源使用率等场景，能够直观地表达数据在目标区间内的位置。

基本用法

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

// 创建仪表盘
const chart = render(container, {
  layers: [
    {
      type: 'gauge',
      dataIndex: 0,
      encoding: {
        x: '使用率' // 数值字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 使用率: 68.5 }
      ]
    }
  ]
});

配置参数

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

数据要求

• 数值字段要求为数值类型
• 数据量至少需要大于1条
• 提供准确的字段名映射

潜规则与注意事项

1. 刻度范围自动计算：

   • 仪表盘会根据输入数值自动计算合适的刻度范围。
   • 计算方式：取数值的整数部分的最高位，确定基础单位，然后设置范围为该基础单位的整数倍。
   • 实现代码：

     const l = gaugeValue.toString().split('.')[0].length;
     const lValue = 10 ** (l - 1);
     const lowerBound = Math.floor(gaugeValue / lValue) * lValue;
     const upperBound = lowerBound + lValue;

2. 自适应布局：

   • 仪表盘会根据容器大小自动调整显示效果，包括字体大小、指针宽度等。
   • 当检测到大尺寸布局时，会使用更大的字体和更粗的指针。
   • 相关逻辑：const isLargeLayout = layout.includes('lg');

3. 单位显示规则：

   • 如果数据中包含单位信息，会自动在仪表盘名称中显示单位。
   • 单位信息通过数据元信息获取，例如：

     name: `${x}${hooks.formatDataNumberValue(+data.values[0][x]).unit ? `(${hooks.formatDataNumberValue(+data.values[0][x]).unit})` : ''}`

4. 颜色区间划分：

   • 仪表盘默认将值域分为三个区间：0-30%（浅绿色）、30-70%（蓝色）、70-100%（红色）。

实现原理

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

1. 数据解析：获取数值并格式化
2. 范围计算：根据数值自动确定刻度范围
3. 布局适配：根据容器大小调整视觉效果
4. 样式应用：设置指针、刻度线和颜色

类型兼容性问题

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

1. 确保提供的数据字段是数值类型
2. presetOption.color可能为undefined，代码中已做相应处理
3. 数据处理过程中需要进行类型转换，避免NaN值

示例

基础仪表盘

{
  type: 'gauge',
  encoding: {
    x: 'CPU使用率'
  }
}

常见问题解决

1. 仪表盘显示异常

   • 检查数据类型是否为数值
   • 确保容器大小足够显示仪表盘

2. 单位显示问题

   • 确保在数据元信息中正确设置了单位信息