视觉映射组件完全指南 - visualMap

📋 概述

**visualMap（视觉映射组件）**是ECharts中用于将数据维度映射到视觉通道的核心组件。它支持颜色、大小、透明度、符号等多种视觉编码方式，是构建热力图、地图、散点图等复杂可视化的关键。

核心价值

• 数据可视化增强：通过颜色渐变直观展示数据分布
• 多维度表达：同时映射多个视觉通道
• 交互控制：支持用户手动调整映射范围
• 自动适配：根据数据范围自动生成合理的映射规则

---

🎯 核心概念

1. visualMap类型

// 连续型视觉映射 - 适用于连续数据
visualMap: {
  type: 'continuous', // 默认类型
  min: 0,
  max: 1000,
  inRange: {
    color: ['#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8', 
            '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026']
  }
}

// 分段型视觉映射 - 适用于分类数据
visualMap: {
  type: 'piecewise',
  pieces: [
    {min: 0, max: 100, label: '低', color: '#313695'},
    {min: 100, max: 500, label: '中', color: '#fee090'},
    {min: 500, max: 1000, label: '高', color: '#d73027'}
  ]
}

2. 视觉通道类型

通道	属性名	适用图表	示例
颜色	color	所有图表	热力图、地图
符号大小	symbolSize	散点图、气泡图	人口规模
透明度	opacity	所有图表	数据密度
符号类型	symbol	散点图、折线图	类别区分
线宽	lineWidth	折线图、关系图	流量大小

---

🔧 使用场景

场景1：热力图数据可视化

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    calculable: true, // 显示拖拽手柄
    orient: 'vertical',
    left: 'right',
    top: 'middle',
    inRange: {
      color: ['#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8', 
              '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026']
    },
    textStyle: {
      color: '#fff'
    }
  },
  series: [{
    type: 'heatmap',
    data: heatmapData
  }]
};

场景2：地图区域着色

option = {
  visualMap: {
    type: 'piecewise',
    min: 0,
    max: 100000,
    left: 'left',
    bottom: 'bottom',
    text: ['高', '低'],
    realtime: false, // 关闭实时更新，提升性能
    calculable: true,
    inRange: {
      color: ['#f2f2f2', '#ffb6b6', '#ff7f7f', '#ff4d4d', '#cc0000']
    },
    seriesIndex: 0 // 只控制第一个系列
  },
  series: [{
    type: 'map',
    map: 'china',
    data: provinceData
  }]
};

场景3：散点图气泡大小

option = {
  visualMap: [
    {
      type: 'continuous',
      dimension: 2, // 映射第三个维度（数据索引从0开始）
      min: 0,
      max: 1000000,
      inRange: {
        symbolSize: [10, 50] // 气泡大小范围
      }
    },
    {
      type: 'continuous',
      dimension: 0,
      min: 0,
      max: 100,
      inRange: {
        color: ['#313695', '#d73027'] // 颜色映射
      }
    }
  ],
  series: [{
    type: 'scatter',
    data: scatterData // [x, y, value]
  }]
};

---

📝 配置详解

1. continuous（连续型）完整配置

visualMap: {
  type: 'continuous',
  
  // === 数据范围 ===
  min: 0,           // 最小值
  max: 1000,        // 最大值
  range: [100, 800], // 用户选择的范围（可动态调整）
  
  // === 视觉映射 ===
  inRange: {
    color: ['#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8', 
            '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026'],
    symbolSize: [10, 50],
    opacity: [0.3, 1],
    lineWidth: [1, 10],
    lineLength: [5, 30] // 关系图边长
  },
  
  // === 超出范围的处理 ===
  outOfRange: {
    color: ['#999'], // 超出范围的数据颜色
    symbolSize: [5],
    opacity: [0.1]
  },
  
  // === 外观布局 ===
  left: 'right',
  top: 'center',
  orient: 'vertical', // 'horizontal' | 'vertical'
  itemWidth: 20,      // 图形宽度
  itemHeight: 140,    // 图形高度
  
  // === 交互功能 ===
  calculable: true,   // 显示拖拽手柄
  hoverLink: true,    // 鼠标悬停联动
  realtime: true,     // 实时更新（影响性能）
  
  // === 文本标签 ===
  text: ['High', 'Low'],
  textGap: 10,
  textStyle: {
    color: '#333',
    fontSize: 12
  },
  
  // === 格式化 ===
  formatter: function(value) {
    return value.toFixed(0);
  },
  
  // === 精确控制 ===
  precision: 0,       // 数值精度
  seriesIndex: 0,     // 控制的系列索引
  dimension: 2        // 映射的数据维度
}

2. piecewise（分段型）完整配置

visualMap: {
  type: 'piecewise',
  
  // === 分段方式（三选一）===
  
  // 方式1：自定义分段
  pieces: [
    {min: 0, max: 100, label: '低', color: '#313695'},
    {min: 100, max: 500, label: '中', color: '#fee090'},
    {min: 500, max: 1000, label: '高', color: '#d73027'},
    {value: 1000, label: '极高', color: '#a50026'} // 等于1000
  ],
  
  // 方式2：等分分段
  splitNumber: 5,     // 分成5段
  min: 0,
  max: 1000,
  
  // 方式3：离散数据
  categories: ['优', '良', '轻度污染', '中度污染', '重度污染'],
  inRange: {
    color: ['#00e400', '#ffff00', '#ff7e00', '#ff0000', '#99004c']
  },
  
  // === 视觉映射 ===
  inRange: {
    color: ['#313695', '#fee090', '#d73027'],
    symbolSize: [10, 30, 50],
    opacity: [0.3, 0.6, 1]
  },
  
  outOfRange: {
    color: ['#ccc'],
    opacity: [0.1]
  },
  
  // === 选择模式 ===
  selectedMode: 'multiple', // 'single' | 'multiple'
  
  // === 外观 ===
  itemWidth: 25,
  itemHeight: 14,
  itemGap: 10,
  align: 'left',      // 'auto' | 'left' | 'right'
  
  // === 文本 ===
  text: ['High', 'Low'],
  showLabel: true,
  label: {
    formatter: '{value}%',
    position: 'inside'
  },
  
  // === 特殊标记 ===
  minText: '最小',
  maxText: '最大',
  
  // === 维度控制 ===
  dimension: 2,
  seriesIndex: 0,
  
  // === 其他 ===
  inverse: false,     // 是否反转
  precision: 2,       // 小数位数
  hoverLink: true,
  tooltip: {
    show: true,
    formatter: function(params) {
      return params.value + '人';
    }
  }
}

---

💡 实战案例

案例1：全国疫情热力图

// 数据准备
const covidData = [
  {name: '北京', value: 1234},
  {name: '上海', value: 890},
  {name: '广东', value: 2345},
  // ... 更多省份数据
];

option = {
  title: {
    text: '全国疫情分布图',
    left: 'center'
  },
  tooltip: {
    trigger: 'item',
    formatter: '{b}<br/>确诊: {c}人'
  },
  visualMap: {
    type: 'piecewise',
    min: 0,
    max: 5000,
    left: 'right',
    top: 'bottom',
    text: ['多', '少'],
    calculable: true,
    inRange: {
      color: ['#f2f2f2', '#ffb6b6', '#ff7f7f', '#ff4d4d', '#cc0000']
    },
    textStyle: {
      color: '#333'
    }
  },
  series: [{
    name: '确诊病例',
    type: 'map',
    map: 'china',
    roam: true,
    label: {
      show: true,
      color: '#333',
      fontSize: 10
    },
    emphasis: {
      label: { show: true },
      itemStyle: {
        areaColor: '#ffe6e6'
      }
    },
    data: covidData
  }]
};

案例2：全球GDP散点图

// 数据结构：[人均GDP, 人口, 总GDP, 国家名称]
const gdpData = [
  [65000, 330000000, 21400000000000, '美国'],
  [42000, 1400000000, 14300000000000, '中国'],
  [48000, 67000000, 2800000000000, '英国'],
  // ... 更多国家
];

option = {
  title: {
    text: '全球各国GDP分析',
    subtext: '气泡大小=总人口，X轴=人均GDP，Y轴=GDP总量，颜色=增长率',
    left: 'center'
  },
  grid: {
    left: '10%',
    right: '15%',
    bottom: '10%',
    containLabel: true
  },
  xAxis: {
    name: '人均GDP（美元）',
    type: 'log',
    axisLabel: {
      formatter: '${value}'
    }
  },
  yAxis: {
    name: 'GDP总量（亿美元）',
    type: 'log',
    axisLabel: {
      formatter: '${value}'
    }
  },
  visualMap: [
    {
      type: 'continuous',
      dimension: 3, // 第四列：增长率
      min: -5,
      max: 10,
      orient: 'vertical',
      right: 0,
      top: 'middle',
      text: ['增长率高', '增长率低'],
      inRange: {
        color: ['#d73027', '#fee090', '#1a9850']
      },
      outOfRange: {
        color: ['#999']
      }
    },
    {
      type: 'continuous',
      dimension: 1, // 第二列：人口
      min: 1000000,
      max: 1500000000,
      show: false, // 隐藏控件，仅用于映射
      inRange: {
        symbolSize: [10, 60]
      }
    }
  ],
  tooltip: {
    formatter: function(params) {
      return `<strong>${params.data[3]}</strong><br/>
              人均GDP: $${params.data[0].toLocaleString()}<br/>
              人口: ${(params.data[1] / 10000).toFixed(0)}万<br/>
              GDP总量: $${(params.data[2] / 100000000).toFixed(0)}亿<br/>
              增长率: ${params.data[3]}%`;
    }
  },
  series: [{
    type: 'scatter',
    data: gdpData,
    emphasis: {
      focus: 'series',
      itemStyle: {
        shadowBlur: 10,
        shadowColor: 'rgba(0,0,0,0.3)'
      }
    }
  }]
};

案例3：城市空气质量地图

option = {
  title: {
    text: '全国城市AQI分布',
    left: 'center'
  },
  tooltip: {
    trigger: 'item',
    formatter: function(params) {
      const aqiLevel = getAQILevel(params.value);
      return `${params.name}<br/>AQI: ${params.value}<br/>等级: ${aqiLevel}`;
    }
  },
  visualMap: {
    type: 'piecewise',
    categories: [
      '0-50 优',
      '51-100 良',
      '101-150 轻度污染',
      '151-200 中度污染',
      '201-300 重度污染',
      '>300 严重污染'
    ],
    min: 0,
    max: 500,
    left: 'right',
    top: 'bottom',
    itemWidth: 20,
    itemHeight: 14,
    inRange: {
      color: ['#00e400', '#ffff00', '#ff7e00', '#ff0000', '#99004c', '#7d0023']
    },
    textStyle: {
      color: '#333'
    }
  },
  series: [{
    type: 'map',
    map: 'china',
    roam: true,
    zoom: 1.2,
    label: {
      show: false
    },
    emphasis: {
      label: { show: true },
      itemStyle: {
        areaColor: '#ffeeee'
      }
    },
    data: cityAQIData
  }]
};

function getAQILevel(aqi) {
  if (aqi <= 50) return '优';
  if (aqi <= 100) return '良';
  if (aqi <= 150) return '轻度污染';
  if (aqi <= 200) return '中度污染';
  if (aqi <= 300) return '重度污染';
  return '严重污染';
}

案例4：销售数据多维度分析

option = {
  title: {
    text: '产品销售多维分析',
    subtext: 'X=价格，Y=销量，气泡=销售额，颜色=利润率',
    left: 'center'
  },
  legend: {
    data: ['电子产品', '服装', '食品'],
    top: 'bottom'
  },
  grid: {
    left: '10%',
    right: '15%',
    bottom: '15%',
    containLabel: true
  },
  xAxis: {
    name: '价格（元）',
    type: 'value',
    scale: true
  },
  yAxis: {
    name: '销量（件）',
    type: 'value',
    scale: true
  },
  visualMap: {
    type: 'continuous',
    dimension: 4, // 利润率维度
    min: 0,
    max: 100,
    right: 0,
    top: 'center',
    text: ['利润率高', '利润率低'],
    calculable: true,
    inRange: {
      color: ['#2a8bc2', '#66c2a5', '#fc8d59', '#d73027']
    },
    formatter: function(value) {
      return value.toFixed(0) + '%';
    }
  },
  tooltip: {
    formatter: function(params) {
      return `<strong>${params.data[5]}</strong><br/>
              类别: ${params.seriesName}<br/>
              价格: ¥${params.data[0]}<br/>
              销量: ${params.data[1]}件<br/>
              销售额: ¥${params.data[2].toLocaleString()}<br/>
              库存: ${params.data[3]}件<br/>
              利润率: ${params.data[4]}%`;
    }
  },
  series: [
    {
      name: '电子产品',
      type: 'scatter',
      data: electronicsData,
      symbolSize: function(data) {
        return Math.sqrt(data[2]) / 5; // 根据销售额计算气泡大小
      }
    },
    {
      name: '服装',
      type: 'scatter',
      data: clothingData,
      symbolSize: function(data) {
        return Math.sqrt(data[2]) / 5;
      }
    },
    {
      name: '食品',
      type: 'scatter',
      data: foodData,
      symbolSize: function(data) {
        return Math.sqrt(data[2]) / 5;
      }
    }
  ]
};

---

⚠️ 常见问题

问题1：visualMap不生效

症状：配置了visualMap但图表没有变化

原因：

1. dimension指定的维度不存在
2. seriesIndex与实际系列不匹配
3. 数据格式不符合要求

解决：

// ❌ 错误：维度索引错误
visualMap: {
  dimension: 5, // 数据只有3列
  min: 0,
  max: 100
}

// ✅ 正确：检查数据维度
console.log(data[0]); // [x, y, value] → dimension应该是0、1或2
visualMap: {
  dimension: 2, // 第三列
  min: 0,
  max: 100
}

问题2：颜色渐变不平滑

症状：颜色过渡生硬

原因：颜色节点太少

解决：

// ❌ 错误：只有两个颜色
inRange: {
  color: ['#313695', '#d73027']
}

// ✅ 正确：使用多个颜色节点
inRange: {
  color: ['#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8', 
          '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026']
}

问题3：拖拽卡顿

症状：拖动visualMap手柄时响应慢

原因：realtime: true导致频繁重绘

解决：

visualMap: {
  type: 'piecewise',
  realtime: false, // 关闭实时更新
  hoverLink: false, // 关闭悬停联动
  // 只在松开手柄时更新
}

问题4：legend与visualMap冲突

症状：两者都配置时显示异常

解决：

// 确保位置不重叠
legend: {
  top: 'top',
  left: 'center'
},
visualMap: {
  left: 'right',
  bottom: 'bottom'
}

---

🎯 最佳实践

1. 选择合适的类型

// 连续数据 → continuous
// 温度、湿度、销售额、人口

// 分类数据 → piecewise
// AQI等级、风险等级、年龄段

2. 优化性能

// 大数据量时
visualMap: {
  realtime: false,     // 关闭实时更新
  hoverLink: false,    // 关闭悬停联动
  throttle: 50         // 节流50ms
}

3. 提供清晰的颜色方案

// 使用ColorBrewer等专业配色
const divergingColors = [
  '#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8', 
  '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026'
];

// 避免使用纯红纯绿（色盲友好）
const colorblindFriendly = [
  '#0072B2', '#009E73', '#D55E00', '#CC79A7', '#F0E442'
];

4. 添加交互反馈

visualMap: {
  calculable: true,    // 显示拖拽手柄
  hoverLink: true,     // 悬停联动
  tooltip: {
    show: true,
    formatter: '{value}人'
  }
}

5. 处理边界情况

visualMap: {
  min: 0,
  max: 1000,
  outOfRange: {
    color: ['#999'],   // 超出范围用灰色
    opacity: [0.1]     // 降低透明度
  }
}

---

📊 性能指标

不同数据量的性能表现

数据量	渲染时间	FPS	内存占用	建议
<1,000	10-30ms	60	5-10MB	无限制
1,000-10,000	30-100ms	55-60	10-30MB	关闭realtime
10,000-100,000	100-500ms	45-55	30-100MB	关闭hoverLink
>100,000	500ms+	30-45	100MB+	使用large模式

优化效果对比

// 未优化
visualMap: {
  realtime: true,
  hoverLink: true
}
// 10,000数据点 → 拖拽帧率：35 FPS

// 优化后
visualMap: {
  realtime: false,
  hoverLink: false,
  throttle: 50
}
// 10,000数据点 → 拖拽帧率：58 FPS

---

🔗 相关链接

• ECharts官方文档 - visualMap
• ColorBrewer配色方案
• 数据可视化设计原则
• 散点图完全指南.md)
• 地图完全指南.md)
• tooltip富文本配置

---

📚 学习路线

---

💎 总结

visualMap核心价值：

• ✅ 将抽象数据转化为直观的视觉表达
• ✅ 支持连续和分段两种映射模式
• ✅ 提供多种视觉通道（颜色、大小、透明度等）
• ✅ 具备交互能力（拖拽、悬停联动）
• ✅ 适用于热力图、地图、散点图等多种场景

关键决策点：

1. 数据类型：连续 → continuous，分类 → piecewise
2. 视觉通道：颜色最常用，气泡图用大小，密度图用透明度
3. 性能权衡：大数据量时关闭realtime和hoverLink
4. 用户体验：提供清晰的文本标签和格式化提示

下一步学习：

• 结合tooltip实现丰富的信息展示
• 使用dispatchAction编程式控制视觉映射
• 探索自定义主题中的颜色系统

掌握visualMap，让你的数据可视化更具表现力！🎨