ECharts 5.x地图下钻实战：GeoJSON获取与registerMap

简介面向需要在ECharts中嵌入湖南区域地图的前端开发者这份资料提供了湖南省及下辖14个市州的GeoJSON地图数据可直接用于各类地理数据可视化项目。数据包含区域名称、唯一标识与边界坐标且已对各级地名的标签显示位置做了手工校正在缩放或移动地图时能显著减少文字重叠保证标注清晰。压缩包内共有22个文件以15个JSON地图文件为主体另附4个JS处理脚本、1个可直接运行的HTML示例、1个CSS样式文件及1张效果预览图整体仅1.84MB非常轻量。HTML示例完整演示了如何初始化地图、绑定统计值以及设置视觉映射开发者可以参考该结构快速搭建带有颜色分级或数据提示的湖南地图应用比如人口分布、经济指标等场景。已有2302人学习使用适合需要快速交付省级与市级统计地图的数据可视化工程师、报表开发人员或数据分析师。 上个月接了个政务大屏的单子需求是把湖南省以及14个地级市的数据做成一张可点击下钻的地图。我原本估着给 ECharts 塞一个 JSON 就完事结果真正动手才发现光地图数据怎么拿就折腾了小半天老教程里内置的 china.json 在 ECharts 5.x 里已经没了网上很多 CDN 地址也早不是原来那套。这篇文章就把 echart 湖南省及各市地图的完整做法拆开讲从 GeoJSON 获取、registerMap 注册、省市两级下钻到样式调优、移动端适配再把大家最近常搜的为什么访问不了了怎么让最后一个点显示 tooltip这类问题一起收个尾。做政务大屏、统计报表、招商地图这类可视化需求的人可以直接照着做。1. 地图数据从哪来GeoJSON 的获取与清洗1.1 为什么 5.x 之后没有内置地图可用了先说一个很多人踩过的坑ECharts 4 时代npm 包里是有echarts/map/json/china.json的网上几乎所有教程都是直接 import 这个文件然后注册代码短得很。但到了 5.x官方明确不再分发地图数据把内置的省市 JSON 全部移除了。也就是说你照着三四年前的教程做第一步就会报错这就是为什么访问不了了最常见的来源之一。ECharts 本身并没有挂只是地图数据已经不在安装包里了。你要自己准备 GeoJSON 文件再通过echarts.registerMap()去注册这已经是 5.x 的标准姿势。注意只要是 5.x 版本就别再找什么echarts/map/json/china.json了这个路径在源码里根本不存在。1.2 省市级 GeoJSON 从哪找现在最通用的做法是去阿里云 DataV.GeoAtlas 提供的地理数据接口拿边界数据省市县三级都有请求也很简单。拿湖南来说省级地图直接请求这个地址https://geo.datav.aliyun.com/areas_v3/bound/430000_full.json拿到的是一个标准 GeoJSON FeatureCollection每个 feature 对应一个地级行政区包括湘西土家族苗族自治州。需要哪个市的独立地图就把 430000 换成对应的行政区划代码。湖南省 14 个地级行政区的 adcode 我列出来后面做下钻映射的时候直接抄地级行政区adcode长沙市430100株洲市430200湘潭市430300衡阳市430400邵阳市430500岳阳市430600常德市430700张家界市430800益阳市430900郴州市431000永州市431100怀化市431200娄底市431300湘西土家族苗族自治州433100接口地址里带_full的是完整边界文件会包含到县级区划展示更精细不带_full的只到市级轮廓只有几十 KB加载更快。如果只是做省级大图市级轮廓就够用了如果后续要做市到区县的下钻那就得用_full。开发阶段图方便可以直接请求这个接口但生产环境我建议把 JSON 下载下来放到自己的静态目录里后面我会专门讲为什么。1.3 先检查再注册别让脏数据坑你一晚上从接口拿到的 GeoJSON 我建议先格式化看一眼再往代码里放。首先要确认根节点是 FeatureCollection其次每个 feature 的properties里一定要有name字段这个值会作为地图区域的默认名称直接决定后面的 tooltip、事件绑定、数据映射能不能对上。有的渠道下载下来的数据name 可能带空格、简繁体不一致或者市名只有长沙没有市字而你的业务数据里写的是长沙市结果就是地图画出来了但数据颜色一块都不显示。这种情况不用怀疑就是名字对不上。处理办法有两个要么把业务数据的 name 改成和 GeoJSON 完全一致要么在注册后通过nameMap做名字映射。我一般倾向于后者因为业务数据通常来自后端改字段名影响面大用 nameMap 集中处理更安全。另外如果发现地图某些区域形状异常、边界错乱多半是 GeoJSON 里有自相交的坐标点可以用 Mapshaper 这类工具做一次简化修复。这类问题不常见但真遇到的时候靠肉眼排查边界坐标会让人崩溃直接丢进工具里跑一遍反而是最快的。2. 基础地图怎么搭registerMap 与 series-map 核心配置2.1 一个能跑起来的最小示例地图数据就绪后剩下的就是 ECharts 的标准操作了。我习惯用 async/await 把数据加载写得直白一点避免一层层 then 看得头晕。下面这个例子放在一个 HTML 里就能跑!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / script srchttps://cdn.jsdelivr.net/npm/echarts5.5.0/dist/echarts.min.js/script /head body stylemargin:0; div idmap stylewidth:100vw;height:100vh;/div script const chart echarts.init(document.getElementById(map)); (async () { const geoJson await fetch(https://geo.datav.aliyun.com/areas_v3/bound/430000_full.json) .then(res res.json()); echarts.registerMap(hunan, geoJson); chart.setOption({ tooltip: { trigger: item, formatter: {b}br/{c} }, series: [{ type: map, map: hunan, roam: true, label: { show: true, color: #fff, fontSize: 12 }, itemStyle: { areaColor: #1e3a8a, borderColor: #60a5fa, borderWidth: 1 }, emphasis: { label: { show: true }, itemStyle: { areaColor: #f59e0b } } }] }); })(); /script /body /htmlregisterMap的第一个参数是给这张地图起的名字后面series.map必须引用同一个名字。这个 key 不一定要叫 hunan但前后必须一致否则控制台会直接报Map not found。这个报错也是很多人初学阶段最常遇到的。2.2 为什么用 map 系列而不是 geo 组件ECharts 里画地图有两条路一条是geo组件另一条是series-map系列。如果只是画一个静态底图比如只展示边界轮廓geo就够了渲染性能也更好。但要绑定业务数据、按数值给每个市染色就必须用 map 系列因为只有 map 系列能和 visualMap 组件产生数据联动。实际项目中我经常两者混用用 geo 做底图样式再用 map 系列叠加数据层这样可以在不破坏底色效果的情况下单独控制数据呈现。不过对大多数需求来说一个 map 系列已经够用了别一上来就把配置堆得太复杂。2.3 绑定数据与 visualMap 分段配色给湖南各市绑定数据核心是 series.data 里的name要和 GeoJSON 里的properties.name一一对应。我习惯把数据和地图配置分开维护这样 setOption本文还有配套的精品资源点击获取