上周三晚上,我收到一张截图:甲方爸爸想要”园区设备分布地图”,我们前端小哥熬到十点,页面上只有一块空白加一个报错——Map xxx not exists。
他满头雾水:”代码跟掘金教程一模一样啊?”
我把他的 GeoJSON 文件打开一看,问题根本不在代码,而在他下载的那份地图数据里,properties 里压根没有 name 字段。ECharts 找不到名字,就匹配不上数据,地图自然死活渲染不出来。
这就是 ECharts 自定义地图最让人抓狂的地方:它明明是个图表库,却在地图上突然变得像个挑剔的地理信息系统。今天就把我这些年踩过的坑摊开讲,从数据从哪来、怎么注册,到名字对不上、飞地画不出来这些阴间问题,一次说清。
先搞懂一件事:ECharts 不生产地图,它只是 GeoJSON 的”搬运工”
很多人第一次做自定义地图,会下意识去找”ECharts 地图下载”。方向就错了。
从 4.x 版本开始,ECharts 基础包里就不再内置任何地图数据。它的角色很纯粹:你给它一份 GeoJSON(一种描述地理边界的 JSON 格式),它负责把边界画成可点击、可上色的区域。官方 FAQ 里也写得明白,自定义地图需要借助 mapshaper-plus 这类工具处理 GeoJSON 文件,因为 ECharts 对地图坐标做过额外的编码。
所以整个流程其实是三步:
搞到 GeoJSON:省市县的数据可以从阿里云 DataV 的地图接口拿(比如
geo.datav.aliyun.com/areas_v3/bound/350000_full.json就是福建省带区县边界的完整数据);更细颗粒度的街道、园区、厂区,就得自己画或用 BigMap 之类的工具导出再转换。注册地图:拿到数据后调一行
echarts.registerMap('myMap', geoJson),给它起个名字。使用地图:在
series里写type: 'map', map: 'myMap',或者作为geo组件的底图。
听起来三步就能下班?别急,每一步都有暗坑。比如很多人图省事直接把 JSON 文件 import 进来注册,几百 KB 的文件塞进首屏主包,页面白屏时间直接多了一秒。经验是:地图数据懒加载,进入地图页再注册。
名字对不上,地图白一半
这是自定义地图最高频的翻车现场,没有之一。
GeoJSON 里每个区域靠 properties.name 识别。麻烦在于,不同来源的数据命名口径天差地别:有的写”北京市”,有的写”北京”;有的是”广西壮族自治区”,你接口里传的是”广西”。ECharts 匹配区域就是拿名字做字符串比对,差一个字,这个区域就永远不上色,而且它不报错,就是静默地空着,让你以为数据没查到。
更隐蔽的是飞地问题。有开发者画上海普陀区的街道地图时发现,某个街道有两块不相连的区域,导出后 type 是 GeometryCollection,而 ECharts 对这个类型没有处理,直接报错或者画丢一块。解决办法很土但有效:把多块的坐标数组手动合并,type 改成 Polygon。
我的习惯是:拿到任何一份 GeoJSON,先用脚本扫一遍所有 features 的 name,跟业务数据里的地名做交集比对,对不上的建一张映射表统一清洗。这一步花十分钟,能省掉后面三天的”为什么湖南没颜色”的排查。
“registerMap is not a function”——这个报错骗了无数人
搜这个报错,你能看到一堆哀嚎。经典的段子是:有人以为 registerMap 在 init 之后的实例上,调 this.chart.registerMap() 直接报错。实际上它只挂在 echarts 这个全局对象上。
这背后是个更普遍的道理:自定义地图的一切,都发生在 setOption 之前。Vue、React 项目里最常见的时序 bug 就是:组件 mounted 时立刻 setOption,GeoJSON 还没 fetch 回来,注册更没执行,地图区域一片空白。注册了之后再 setOption?晚了,得在注册成功的回调里重新触发一次。
还有个版本坑:ECharts 5.x 跟旧版 china.js 地图包混搭,装错版本连中国地图都画不出来。接项目时把版本钉死,别用 “latest”。
把这些串起来,一套稳妥的加载骨架长这样:
fetch('/map/myMap.json')
.then(res => res.json())
.then(geoJson => {
echarts.registerMap('myMap', geoJson);
chart.setOption({
series: [{ type: 'map', map: 'myMap', roam: true, data }]
});
});
先取数、再注册、后渲染,顺序就是生命线。
自定义地图的尽头,不是填色,是”地图+图表”的自由组合
掌握了注册和避坑,才算拿到入场券。真正让大屏”哇塞”起来的,是那些组合拳。
最常见的进阶玩法是 geo 组件打底 + scatter 散点叠加:地图负责边界和区域样式,散点负责业务分布。这里有一个坑中坑:散点系列必须写 coordinateSystem: 'geo',而且要和 geo 组件里的 map 名字完全一致。我见过有人 geo 里注册了 china,scatter 的坐标系却写成 ‘map’,结果地图出来了,散点全堆在左下角——坐标系名字差一个字符,数据就”叛逃”到天涯海角。
再往上,可以用 convertToPixel 把经纬度转成像素坐标,往地图某个区域里塞迷你柱状图、饼图。官方示例里那种”每个省一个柱状图”的效果就是这么来的。还有炫光的涟漪散点、飞线图,本质都是自定义地图之上的图层叠放。
做这类叠加时,我的两个实战建议:
- tooltip 用
trigger: 'item'别用'axis'。地图上叠了散点、飞线好几层,axis 触发会让整个地图跟着高亮,糊成一片。 - 地图相关组件单独封装一个模块。注册逻辑、resize、销毁集中管理,避免重复注册同一个 map 名——它不报错,但会静默覆盖数据,排查起来要命。
写在最后
回到开头那个加班到十点的小哥。他的问题最后花五分钟解决了:给 GeoJSON 的 properties 补上 name,映射表对齐,地图就亮了。
ECharts 自定义地图这东西,难吗?API 就那几个。但它处在前端和地理数据的交界处,两个领域的规矩你都得懂:GeoJSON 的结构、命名的口径、时序的先后。地图画不出来,八成不是 ECharts 的错,是数据在跟你打哑谜。
下次再看到一片空白,别急着怀疑人生。先打印 name,再看注册时机——十有八九,答案就藏在这两步里。
你踩过最离谱的地图坑是什么?评论区聊聊,让大家提前排雷。
