ECharts 5省市县地图下钻实战：Vue与React自定义GeoJSON方案

第一次接省市县三级地图需求是在给客户做数据大屏的时候。需求本身听起来不复杂全国页签展示各省汇总点进某个省要能看到市级分布再点一个市就得落到区县。我以为用 ECharts 的 map 系列就是顺手的事结果在 Vue 项目里一跑页面干干净净地白屏。后来才知道新版 ECharts 根本不内置行政区划数据当年流传的 map: china 写法在新项目里已经失效。而且不只是 VueReact 项目遇到的是同一套问题。这篇就把我在 Vue 和 React 里用 ECharts 做自定义省市县地图的完整思路拆开包含 GeoJSON 底图怎么组织、两套框架下组件怎么封装、配色下钻怎么设计以及实战中至少可以帮你少熬三个晚上的坑。1. 先说一个很多人会踩的坑新版 ECharts 不再内置行政区划 GeoJSON1.1 为什么老代码能直接 map:china新项目却白屏在 ECharts 4.x 时代中国地图以及各省市地图数据是直接打包在 echarts 主包里的所以大家写series: [{ type: map, map: china }]就能渲染一张全国地图。那时网上的教程也都是这么教代码一贴图表就有。但从 ECharts 5 开始官方把地图数据从主包里移了出去。目的很直接主包瘦身把地图数据的更新权利交还给开发者。这也意味着你再也不应该指望echarts自带china、jiangsu这类名称的地图。任何地图都要先通过echarts.registerMap(name, geoJson)注册才能在setOption里使用。我遇到很多同学卡住就是因为还在照搬旧资源包。比如从某些旧项目里复制一个china.js文件或者在 node_modules 里翻出来一堆map/json目录然后发现代码版本、名称字段、边界精度全都不对地图要么白屏要么某个区域 hover 后没反应。正确姿势其实很清晰先准备一份标准 GeoJSON 数据里面是完整的边界坐标和行政区划属性然后在代码里调用registerMap把这份数据挂到一个自定义名字下面。之后series.map写同一个名字ECharts 才能找到它。1.2 ECharts 5 的地图模块化策略还改变了哪些隐性规则官方把制图数据外置表面上只是“少了点内置数据”实际影响体现得很全面尤其是当你做省市县三级下钻时。包体积变小不需要地图数据的项目不用再背几 MB 的 JSON 包袱。数据更新变快行政区划一旦变化只要替换 GeoJSON 数据源即可不用等库版本更新。渲染流程多了一步地图从 setOption 直接出图 变成了 registerMap 之后再 setOption。名称匹配成了开发者的责任业务数据里的name必须和 GeoJSON 中的properties.name完全一致或者你在代码里做映射否则点了没反馈、数值不显示。我在实际项目里最头疼的不是渲染而是名称不一致。比如 GeoJSON 里写的是“江苏省”业务数据里写个“江苏”视觉上没差代码层面就是匹配不上。这类问题不会报错只会表现为“地图区域的颜色没变化”排查起来特别耗时间。所以第一步值得做扎实先把你需要的地图 GeoJSON 下载到本地保存为 JSON 文件统一放到src/assets/map/目录下不要直接依赖外部在线接口。上线后一旦外网访问不稳定或服务变动整个大屏会白给你看这个体验我实在不想你再经历一遍。对比项4.x 时代5.x / 6.x 时代中国地图数据内置在 echarts 包内移出核心包需自行准备注册方式默认可用echarts.registerMap(name, geoJson)包体积较大可显著减小名称更新跟随版本由开发者控制业务数据匹配内置名称校正完全依赖 GeoJSON properties.name2. 行政区划 GeoJSON 的获取与裁剪省市县三级底图的核心玩法2.1 先看懂 GeoJSON 的关键字段后面才不慌GeoJSON 说到底是地理空间数据的标准结构。ECharts 最关心的是其中的FeatureCollection和features数组。每个 feature 通常包含两块信息properties里放行政区划的属性比如名称、代码、级别geometry里放边界坐标数组多边形或多边形集合。数据结构大概长这样{ type: FeatureCollection, features: [ { type: Feature, properties: { adcode: 320000, name: 江苏省, level: province, childrenNum: 13 }, geometry: { type: Polygon, coordinates: [...] } }, { type: Feature, properties: { adcode: 320500, name: 苏州市, level: city, childrenNum: 6 }, geometry: { type: Polygon, coordinates: [...] } } ] }这里最值得关注的是adcode也就是行政区划代码。国内这套代码规则很有规律省级代码是两位有效数字加四个零比如320000代表江苏省市级代码是四位有效数字加两个零320500代表苏州市区县级是完整的六位比如320583这类。ECharts 本身不强制使用 adcode但你在做点击下钻时它是最适合做文件命名的 ID。name字段决定了地图和业务数据的关联。level字段帮你判断当前点击的层级是省份、城市还是区县。childrenNum告诉你当前节点还有没有下级数据这个字段在判断“要不要继续下钻”时很好用。2.2 三级地图的底图文件建议按 adcode 分片保存很多新手想一步到位直接下载一个全国级的大 JSON然后幻想能一直钻到区县。实际上全国 GeoJSON 里通常只包含省级边界省和市的边界并不在同一个文件里。要么你单独准备省市两级的数据包要么运行到对应层级时再加载对应的下一级文件。我习惯把文件组织成这样的结构src/assets/map/ 100000_full.json 320000_full.json 320500_full.json 320583_full.json100000_full.json是全国底图包含所有省边界320000_full.json是江苏省底图包含所有市边界320500_full.json是苏州市底图包含所有区县边界320583_full.json就是昆山市的区县级边界再往下没有行政子级时就不需要继续下钻了。按需加载最大的好处是首屏体积可控。全国底图本身可能几个 MB如果你一上来就把全国地图所需的 JSON 全部打包进主 bundle页面加载速度会有明显影响。而按 adcode 分片后每次只加载当前层级的数据。在 Vite 项目里我会用import.meta.glob配合动态导入实现很顺手const mapModules import.meta.glob(/src/assets/map/*.json) async function loadMapJson(adcode) { const loader mapModules[/src/assets/map/${adcode}.json] const module await loader() return module.default }这套机制在 React 里同样适用因为import.meta.glob是构建工具层的能力框架不参与。如果用 Webpack改成require.context也是同一个思路。目的只有一个代码里不用手写一串 JSON import只要传 adcode就能拿到对应层级的 GeoJSON。3. Vue 项目接入从注册到卸载的完整闭环3.1 先用 Composition API 封装一个地图组件在 Vue 3 项目中我通常把地图封装成一个公共组件这样后台多个页面复用的时候不用重新写初始化和销毁逻辑。组件接收两个 props一个是当前要渲染的 adcode一个是业务数据数组。业务数组中每一项的name对应地图区域名称value对应展示数值。一个最小可用的 Vue 3 地图组件长这样template div refchartRef classmap-chart/div /template script setup import * as echarts from echarts import { ref, onMounted, onBeforeUnmount, nextTick } from vue const props defineProps({ adcode: { type: Number, required: true }, mapData: { type: Array, default: () [] } }) const chartRef ref(null) let chart null let resizeObserver null async function loadAndRender(adcode) { const geoJson await loadMapJson(adcode) echarts.registerMap(String(adcode), geoJson) chart.setOption({ series: [ { type: map, map: String(adcode), roam: true, data: props.mapData } ] }) } onMounted(async () { await nextTick() chart echarts.init(chartRef.value) await loadAndRender(props.adcode) resizeObserver new ResizeObserver(() { if (chart) chart.resize() }) resizeObserver.observe(chartRef.value) }) onBeforeUnmount(() { if (resizeObserver) resizeObserver.disconnect() if (chart) chart.dispose() chart null }) /script style scoped .map-chart { width: 100%; height: 100%; } /style这段代码里的loadMapJson就是前面提到的按 adcode 动态导入方法。组件挂在页面上后echarts.init拿到容器实例再去加载对应层级的 GeoJSONregisterMap后通过setOption渲染。代码看上去不复杂但真正影响成败的是细节。如果你是放在一个隐藏 tab 页里容器初始化时宽度是 0图表就会缩成一团。这种场景下不能用v-if配合固定时机而是要在容器真正显示后再初始化或者用nextTick先确保 DOM 布局已经稳定。我更推荐的做法是在初始化前检查一下chartRef.value.clientWidth 0如果等于 0 就等下一次切换触发这比盲目加setTimeout更可控。3.2 为什么 Vue 组件里必须处理 resize 和 disposeVue 的组件生命周期给了我们两个很好的清理时机组件挂载后注册监听组件卸载前释放资源。很多同学写完echarts.init就不再管了结果路由切走再切回来会发现页面里的 canvas 图层越叠越多内存和 CPU 肉眼可见地往上涨。chart.dispose()会彻底销毁 ECharts 实例回收内部监听和 canvas 对象这不是可有可无的一步。resizeObserver.disconnect()负责解除容器尺寸变化的监听。这两者配合才能保证在单页应用里频繁切换页面时不拖垮浏览器。很多老教程还在用window.addEventListener(resize, chart.resize)。如果地图组件是放在固定的大屏容器里这样写没太大问题。但一旦地图被放进抽屉、弹窗、或者可以折叠的面板里容器尺寸可能变了而窗口尺寸没变窗口监听就失效了。ResizeObserver直接观察容器盒子尺寸比 window 级监听准确得多。现在各大主流浏览器都已经原生支持我在 Vue 和 React 两个框架里统一都用它。如果地图组件需要响应 props 变化比如点击省份后父组件传入了新的 adcode那就在组件里加一个watch等数据加载完再registerMap和setOption。这里注意不要重新init同一容器初始化一次就足够了。4. React 项目接入useRef useEffect 的清理比想象中重要4.1 先写一个可复用的 hook 地图加载逻辑React 的写法没有 Vue 模板那么直观但逻辑反而更集中。我习惯把图表实例和地图数据加载拆成一个自定义 hook组件的代码只负责传入数据和拿到容器 ref。一个比较干净的 React 版本是这样的import * as echarts from echarts import { useEffect, useRef } from react interface MapDataItem { name: string value: number } export function useEchartsMapT extends HTMLElement( adcode: string, data: MapDataItem[] ) { const containerRef useRefT(null) const chartRef useRefecharts.ECharts | null(null) useEffect(() { if (!containerRef.current) return // 如果旧实例还在先释放掉避免重复初始化 if (chartRef.current) { chartRef.current.dispose() } const chart echarts.init(containerRef.current) chartRef.current chart let cancelled false async function render() { const geoJson await loadMapJson(adcode) if (cancelled || !chartRef.current) return echarts.registerMap(adcode, geoJson) chartRef.current.setOption({ series: [ { type: map, map: adcode, roam: true, data } ] }) } render() const observer new ResizeObserver(() { chartRef.current?.resize() }) observer.observe(containerRef.current) return () { cancelled true observer.disconnect() chartRef.current?.dispose() chartRef.current null } }, [adcode, data]) return containerRef }组件里使用时把返回的 ref 绑到 div 上即可。hook 内部已经处理了地图注册、图表初始化、数据渲染、尺寸监听和实例销毁业务组件里基本不需要关心 ECharts 的细节。这里有个关键点自定义 hook 接收的data如果是内联数组比如useEchartsMap(320000, [{ name: 苏州市, value: 32 }])每次渲染都会生成新引用useEffect 就会频繁执行。在实际项目里建议把数据放到组件外部的常量里或者用useMemo包一层。否则你会发现地图一直在重复初始化排查半天以为是框架问题其实就是引用地址在变化。4.2 React 18 严格模式下的“双实例”警告React 18 开发模式默认开启 StrictMode组件挂载后 effect 会先执行一次然后立即清理再执行一次。这个机制是为了帮你发现副作用问题但它会让 “init 一个 ECharts 实例” 的代码看起来很吓人。第一次 effect 执行 init清理函数里如果写了chart.dispose()第二次 effect 再 init 就没有问题。但如果你把echarts.init写在了 setup 阶段或者清理函数没有正确执行控制台很容易出现 “There is a chart instance already initialized on the dom” 的报错然后页面上叠了两个 canvas交互错乱。我在 hook 的 effect 开头加了一段判断if (chartRef.current) chartRef.current.dispose()。这样即使清理时机晚了第二次监听执行时也会先把旧实例释放再创建新实例。再加上异步渲染函数里的cancelled标志避免旧请求结束后又往已经卸载的实例上传数据。React 和 Vue 在处理地图时最大的差异其实只在这套生命周期管理。Vue 有模板编译帮我们保证onBeforeUnmount一定执行React 则由开发者自己控制return () {}的清理逻辑。Vue 的思维是“我在卸载前要做这件事”React 的思维是“每个副作用都必须配套一个清理副作用”本质没有优劣只是写法带来的心智模型不同。如果只是切地图没有改容器不建议销毁重建 chart 实例。chart.setOption足够应付下钻场景重新 init 的成本会高不少。5. 自定义配色、标签、tooltip 和三级下钻交互5.1 地图配置项的每一块都决定了最终视觉表现省市县三级地图的“自定义”主要体现在三个方面地图自身样式、数据映射样式、交互反馈样式。地图自身样式包括边框、底色、标签颜色数据映射样式可以用visualMap把数值映射成连续渐变或分段颜色交互反馈样式则是在 hover、选中时改变区域高亮。下面这段配置被我反复使用基本满足绝大多数大屏的视觉要求const option { tooltip: { trigger: item, formatter: (params) ${params.name}br/数值${params.value ?? 暂无} }, visualMap: { min: 0, max: 200, inRange: { color: [#e0f3f8, #74add1, #4575b4] }, left: 20, bottom: 20 }, series: [ { type: map, map: currentMapName, roam: true, scaleLimit: { min: 1, max: 5 }, label: { show: true, fontSize: 11, color: #333 }, itemStyle: { areaColor: #fff, borderColor: #aaa }, emphasis: { label: { show: true, color: #fff }, itemStyle: { areaColor: rgba(255, 180, 0, 0.6) } }, data: list } ] }几个容易忽视的细节roam: true开启后用户才能滚动缩放地图但如果不限制缩放比例用户一路放大下去会把地图边界拉得很怪所以配合scaleLimit限制范围是很有必要的。label.show控制区域名称是否直接显示县级地图区域多字号压到 10 或 11 看着比较舒服。itemStyle.borderColor是区域边界线的颜色下钻到区县级后边界线会比省级地图密集得多太深的边界色会让画面显得杂乱浅灰色系更耐看。visualMap可以用来做连续颜色映射比如“哪个县产值更高哪个县颜色更深”。不过也得注意如果业务数据数值区间不够宽或者大量区域为 0视觉上会一片惨淡。这时候可以不用 visualMap直接给每个数据项一个固定的itemStyle.areaColor反而更好控制。5.2 点击下钻和返回上一级的交互实现地图的点击事件会返回一个params对象里面包含了当前点击区域在 GeoJSON 中对应的 feature 信息。我在做三级下钻时靠的是params.data.properties里的level和adcode。点省级地图进入市级点市级地图进入区县级点区县级就停在下钻表或弹层展示详情不再继续。代码逻辑非常直接const history [100000] chart.on(click, async (params) { const properties params.data?.properties if (!properties) return if (properties.level province) { drillDown(properties.adcode) } else if (properties.level city) { drillDown(properties.adcode) } else if (properties.level district) { // 到区县这级就不再继续下钻可以在这里触发详情弹窗或高亮 openDistrictDetail(properties.adcode) } }) async function drillDown(adcode) { history.push(adcode) const geoJson await loadMapJson(adcode) echarts.registerMap(String(adcode), geoJson) chart.setOption({ series: [ { type: map, map: String(adcode), roam: true, data: getDataByLevel(adcode) } ] }) } function backToParent() { if (history.length 1) return history.pop() const parentAdcode history[history.length - 1] drillDown(parentAdcode) }下钻时注意如果业务数据是针对当前层级准备的比如市级页面时数据数组是各市名称切换到区县级时就要换成区县维度否则会出现区域有数值但颜色不显示的问题。这里建议所有 mapData 都按照父级容器里的统一规范设计后端返回数据的 key 最好直接带上 adcode前端再转成{ name, value }结构。这样既能应对重名区域又能在 future 做 drillup 时准确回跳。我在很多项目里还加了一层面包屑导航。ui 上的返回按钮很好加但使用 ECharts 时别只做“返回上一级”的事件更要维护好history栈。否则用户在省级地图点 A 省又在市级地图点 B 市想回退两次时不知道当前到底在哪一级。用一个数组记录历史路径是最直观也不会出错的做法。6. 实战排错清单地图白屏、样式失配、大数据渲染卡顿6.1 白屏和空白区域的排查链路地图白屏是大屏开发里最常见的问题而原因通常是几个简单环节的失效。我在排查时会按照下面的顺序走基本不会走偏看 console 里有没有报错报错内容是不是map未注册说明series.map的名称和registerMap传入的名称不一致。确认容器高度。ECharts 的图表容器如果高度为 0 或宽度为 0canvas 会渲染成一块透明画布页面自然看不到内容。这是最容易忽略的一步。检查 GeoJSON 是否真的加载成功。在loadMapJson的 then 里打印一下返回结果如果数据为空后面所有逻辑都不会执行。确认registerMap是否发生在setOption之前。地图数据是异步加载的如果 setOption 先跑了ECharts 找不到对应 map就会默默丢弃这一层 series。检查 GeoJSON 结构。type必须是FeatureCollectionfeatures里每个 feature 的geometry.type通常是 Polygon 或 MultiPolygon。如果拿到的数据混入了点状要素或者结构不规范渲染也会异常。这个排查链路看起来像废话但十次里面至少有七次地图白屏就是这几件事之一。以前有个同事在地图组件里写好了fetch加载逻辑结果因为当时浏览器控制台网络面板没开一直怀疑是自己代码写错了最后发现是本地开发环境代理把 JSON 请求拦截了走了 404。先看网络请求是排查这类问题最快的路径。6.2 数据区域不显色、tooltip 没有值如果地图的轮廓渲染出来了但某些区域没有按 visualMap 显示颜色问题大概率不在 ECharts而在数据匹配。ECharts 的 map 系列在匹配数据时默认用数据项里的name去和 GeoJSON feature 的properties.name做对比。名字完全一致颜色就染色对不上区域就空白。排查时可以先把 GeoJSON 里的所有名称打印出来再和业务数据对照const names geoJson.features.map((item) item.properties.name) console.log(names) console.log(mapData.map((item) item.name))两边对一眼如果只是个别名称不一致可以用 ECharts 的nameMap属性做映射。如果嫌每次都要处理名称太麻烦另一种思路是直接以 adcode 为关联键。地图数据项里不写业务名称而是通过nameMap或二次处理把 adcode 映射成 feature 里的 name。还有一类情况是视觉上看着没值其实数值本身就是 0。visualMap 的min如果设置为 0那 0 值区域会落在最低色阶颜色看起来很淡容易被误认为“没渲染”。这时候要检查的就不是 ECharts而是业务数据语义。你要区分“该区域确实没有数据”和“数据请求失败导致的空数组”两者在处理策略上完全不同。6.3 大数据量 GeoJSON 的渲染卡顿与文件瘦身全国级 GeoJSON 动辄几 MB如果某些省份的边界线条复杂数据量还会更大。直接 setOption 渲染不是不行但在低端电脑上打开大屏时拖动缩放会有明显迟滞感。如果你们项目的目标终端配置不高最好提前做文件瘦身。一个可行的方案是降低边界坐标的精度。GeoJSON 里的经纬度通常保留 6 位小数如果只是为了可视化展示保留 3 位甚至 3 位的简化效果依然能满足 90% 的视觉要求文件体积却能下降不少。还有一些地理数据工具能把相邻线段合并、删除冗余点具体工具的选择可以根据团队习惯这里不多展开。渲染层也可以做权衡。ECharts 默认用 canvas 渲染数据量很大的地图场景下性能稳定如果你的地图主要展示静态样式区域数量不大改用 svg 渲染器能得到更多矢量细节。确定一种之后最好在初始化和后续 resize 的过程中保持一致切换渲染器的成本比想象中高容易引入样式抖动。另外下钻到区县级之后如果某市的数据层级有十几个区县地图文件本身不算大但动画过渡可能显得卡顿。可以通过关闭部分全局动画来换取流畅度。比如animation: false或animationDurationUpdate: 100视觉上几乎无感知交互却会顺畅很多。说到底省市县地图不只是把一张图渲染出来它更像一个完整的交互组件。GeoJSON 的层级组织、两个主流框架的生命周期管理、样式配置和事件下钻每一环都跟业务需求绑定得很紧。如果你能在项目一开始就把分片加载和清理逻辑做好后面加再多的配色方案和下钻页面都会轻松很多。我个人现在的做法是把地图加载、实例管理、下钻回退全部封装成平台无关的逻辑Vue 和 React 都只留一层薄壳。这样团队里无论是用 Vue 还是 React接到的都是同一套 api少解释很多问题。