ECharts 内置中国地图完全指南

文档类型: 深度技术文档
难度等级: ⭐⭐
源码版本: ECharts 5.x
本文行数: 约450行

---

📋 目录

1. 引入内置地图
2. 省级下钻
3. 南海诸岛处理
4. 常见问题解决

---

🎯 引入内置地图

npm方式引入

npm install echarts

import * as echarts from 'echarts';
import 'echarts/map/js/china.js';  // 引入中国地图

const option = {
  geo: {
    map: 'china'
  }
};

chart.setOption(option);

---

CDN方式引入

<script src="https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/echarts/map/js/china.js"></script>

<script>
  var chart = echarts.init(document.getElementById('chart'));
  chart.setOption({
    geo: { map: 'china' }
  });
</script>

---

TypeScript项目配置

// tsconfig.json
{
  "compilerOptions": {
    "types": ["echarts"]
  }
}

// types/echarts.d.ts
declare module 'echarts/map/js/china.js' {
  const content: any;
  export default content;
}

---

🔍 省级下钻

省份代码对照表

const provinceCodes: Record<string, string> = {
  '北京': '110000',
  '天津': '120000',
  '河北': '130000',
  '山西': '140000',
  '内蒙古': '150000',
  '辽宁': '210000',
  '吉林': '220000',
  '黑龙江': '230000',
  '上海': '310000',
  '江苏': '320000',
  '浙江': '330000',
  '安徽': '340000',
  '福建': '350000',
  '江西': '360000',
  '山东': '370000',
  '河南': '410000',
  '湖北': '420000',
  '湖南': '430000',
  '广东': '440000',
  '广西': '450000',
  '海南': '460000',
  '重庆': '500000',
  '四川': '510000',
  '贵州': '520000',
  '云南': '530000',
  '西藏': '540000',
  '陕西': '610000',
  '甘肃': '620000',
  '青海': '630000',
  '宁夏': '640000',
  '新疆': '650000',
  '台湾': '710000',
  '香港': '810000',
  '澳门': '820000'
};

---

动态加载省级地图

async function loadProvince(provinceName: string) {
  const code = provinceCodes[provinceName];
  if (!code) {
    throw new Error(`未知的省份: ${provinceName}`);
  }
  
  const url = `https://geo.datav.aliyun.com/areas_v3/bound/${code}_full.json`;
  const response = await fetch(url);
  const geoJson = await response.json();
  
  echarts.registerMap(provinceName, geoJson);
  
  return provinceName;
}

// 使用
async function drillDown(provinceName: string) {
  const mapName = await loadProvince(provinceName);
  
  chart.setOption({
    title: { text: `${provinceName}省` },
    geo: {
      map: mapName,
      roam: true
    }
  });
}

---

🏝️ 南海诸岛处理

显示南海诸岛

const option = {
  geo: {
    map: 'china',
    
    // 确保包含南海诸岛
    regions: [
      {
        name: '南海诸岛',
        itemStyle: {
          areaColor: '#323c48',
          borderColor: '#111'
        },
        label: {
          show: true,
          color: '#fff'
        }
      }
    ]
  }
};

---

隐藏南海诸岛 (简化地图)

const option = {
  geo: {
    map: 'china',
    
    // 过滤掉南海诸岛
    regions: [
      {
        name: '南海诸岛',
        itemStyle: {
          opacity: 0  // 透明
        },
        label: {
          show: false
        }
      }
    ]
  }
};

---

❓ 常见问题解决

问题1: 地图不显示

原因: 未正确引入地图数据

// ❌ 错误 - 忘记引入
import * as echarts from 'echarts';
// 缺少: import 'echarts/map/js/china.js';

// ✅ 正确
import * as echarts from 'echarts';
import 'echarts/map/js/china.js';

---

问题2: 地图变形

原因: 容器宽高比不合适

// ✅ 设置合适的容器
<div id="chart" style="width: 100%; aspect-ratio: 3/2;"></div>

// 或者固定尺寸
<div id="chart" style="width: 900px; height: 600px;"></div>

---

问题3: 标签重叠

解决方案: 调整标签显示策略

const option = {
  geo: {
    map: 'china',
    label: {
      show: false  // 默认不显示
    },
    emphasis: {
      label: {
        show: true  // 高亮时显示
      }
    }
  }
};

---

问题4: 点击事件无效

原因: 未启用roam或事件绑定错误

const option = {
  geo: {
    map: 'china',
    roam: true  // 启用交互
  }
};

chart.on('click', (params: any) => {
  console.log('点击了:', params.name);
});

---

🎯 最佳实践总结

✅ DO - 推荐做法

1. 始终检查地图是否注册成功

   if (!echarts.getMap('china')) {
     console.error('地图未注册');
   }

2. 提供加载状态

   chart.showLoading();
   await loadProvince(name);
   chart.hideLoading();

3. 缓存已加载的地图

   const cache = new Map<string, any>();

❌ DON'T - 避免做法

1. 避免在循环中重复注册

   // ❌ 不好
   for (let province of provinces) {
     echarts.registerMap(province, data);
   }
   
   // ✅ 好 - 按需加载
   echarts.registerMap(currentProvince, data);

---

🔗 相关资源

• ECharts地图示例
• 行政区划代码

---

上一篇: registerMap注册
下一篇: 飞线图实现