简介面向需要基于ECharts搭建地理数据可视化的前端工程师与数据分析师本资料提供完整的湖南省各市、区县两级GeoJSON边界数据解决手动绘制地理边界、寻找合规JSON的痛点。压缩包采用rar格式体积仅631KB内部按市/县维度拆分文件目录结构清晰省市县层级一目了然路径层级与行政区划一致。使用者可按需选取单个区域的json放入项目配合ECharts官方地图组件即可快速渲染地图例如展示长沙市各区县时直接解压长沙对应文件即可完成接入无需额外处理。目前已有2159人学习下载内容覆盖湖南省全部下辖行政区划适合用于政务大屏、运营看板、区域数据报告等可视化场景帮助开发者将业务数据投射到地理维度直观呈现各地区分布与对比差异。 都说ECharts地图是最容易看起来简单、做起来抓瞎的可视化场景。产品丢过来一句加个湖南省地图市要能点县最好也能点你打开官方示例一看全是全国地图怎么画、中国地图的JSON怎么注册真正落到省一级、市一级、县一级的数据从哪来、怎么下钻、怎么标数量的资料反而稀碎。这篇就来把 echarts 湖南省 JSON 地图含各市、各县这条线完整捋一遍从 GeoJSON 获取校验、注册渲染、市县级联动下钻到指定城市标记数量、visualMap 分段调整最后再集中说说我在实际项目里踩过的高频坑。适合刚接触地图可视化的前端开发也适合被数据可视化需求临时抓壮丁的运维和测试同学照着做至少能少走几段弯路。1. 地图数据从哪来湖南省省、市、县三级 GeoJSON 的获取与校验1.1 为什么 echarts 地图必须先有 JSON 数据先说个很多人没意识到的点ECharts 从 5.x 开始不再内置任何地图数据。4.x 时代还能通过引入echarts/map/js/china.js直接用全国地图到了 5.x官方把地图文件彻底从包里拆了出去。你必须在setOption之前调用echarts.registerMap(地图名, GeoJSON对象)手动注册没有这步操作地图画出来就是一块空白。这里说的 GeoJSON 本质上是一个描述地理轮廓的标准 JSON 结构它用一个个坐标数组定义出某个区域的边界。湖南省要满足包含各市、县的需求至少需要准备三套数据湖南省省级边界一个完整的湖南轮廓14 个地级行政区边界长沙、株洲、湘潭等 13 个地级市加湘西土家族苗族自治州各县/区边界比如长沙市的芙蓉区、天心区、岳麓区很多 demo 里只放一个省界文件实际做出来你会发现点击某个市根本没反应就是因为市这一级的 GeoJSON 压根没注册。1.2 几套可靠的数据获取方案我试过比较靠谱的获取渠道有三类第一阿里云 DataV.GeoAtlas。这是目前最简单稳定的免费方案。它提供了全国各行政区域的 GeoJSON 下载而且 URL 规则非常规律适合程序化获取。大致规律是https://geo.datav.aliyun.com/areas_v3/bound/430000_full.json其中430000是湖南省的行政区划代码adcode。把地址里数字换成某个市的 adcode就能拿到对应市的边界比如长沙市是430100。DataV 页面打开湖南省时返回的数据里会带children字段里面就列出了每个下级区域的名称和 adcode拿到后可以继续拼接下级 URL。做省市县三级下钻时这套规律帮了大忙。第二GitHub 上的开源地理数据仓库。搜关键词 china geojson 或 hunan geojson 能找到不少整理好的数据有些甚至把全国省、市、县三级都打包好了。优点是数据集中、版本统一缺点是数据新旧程度不一有的还停留在宁乡县这类旧行政区划名称。用之前务必交叉验证一遍。第三从全国县级边界自己裁剪。如果你手上只有一份全国县级 GeoJSON可以用 Python 写个小脚本按 adcode 前 4 位过滤出湖南省范围再用 geopandas 等工具把边界合并或筛选出来。这条路最费时间一般不推荐非地理专业的人走。1.3 拿到 JSON 后别急着用先做三个校验我见过太多人栽在JSON 格式明明没错但地图就是不显示这个问题上。拿到 GeoJSON 后建议按顺序做三件事第一校验结构完整性。确认数据根节点是FeatureCollectionfeatures数组里的每个元素包含geometry和properties.name。用JSON.parse能过不代表坐标没问题但结构能过是第一步。第二校验名称规范。ECharts 地图的点击事件和数据显示都是以properties.name作为匹配主键的。同一个市业务数据里叫长沙GeoJSON 里叫长沙市两者对不上地图上这个区域就没法绑定数值点击也点不中。第三校验文件精度和体积。精确到区县级的 GeoJSON 文件可能有好几 MB浏览器解析起来有压力。如果只是做展示不做精细圈选建议用简化工具降低坐标精度保留总体轮廓即可。一个省界文件压到几百 KB 完全够用。2. 注册地图与首屏渲染把湖南省先画到画布上2.1 registerMap 的正确使用方式地图注册这一步是整个项目的地基。用 Vue 3 ECharts 5 举例最直接的方式是import * as echarts from echarts import hunanJson from /geo/hunan.json // 模块化导入 echarts.registerMap(hunan, hunanJson) const chart echarts.init(document.getElementById(mapContainer)) chart.setOption({ tooltip: { trigger: item }, visualMap: { min: 0, max: 100, left: 20, bottom: 20, text: [高, 低], inRange: { color: [#e0f3f8, #abd9e9, #74add1, #4575b4, #313695] } }, series: [ { type: map, map: hunan, roam: true, label: { show: true }, data: [ { name: 长沙市, value: 120 }, { name: 株洲市, value: 80 } // 其他城市 ] } ] })注意几个关键点。registerMap的第一个参数是地图标识第二个参数是 GeoJSON 对象。series.map的值必须和这个标识完全一致很多空白地图的问题就是这里拼错了或者引号打错。另外data数组里的name必须和 GeoJSON 里的properties.name对得上对不上时这块区域不会报错但也不会显示数值和颜色。2.2 map 系列和 geo 组件的选型差异ECharts 里画地图有两条路series-map和geo组件不少人会混着用简单说一下区别。series-map是地图系列核心能力是把数据值映射到区域颜色上适合做数据热力分布、区域统计这类需求。我们上面写的这种就是它。geo组件更像是一个地理坐标系背景板本身不关联业务数据更多是配合scatter散点图、effectScatter涟漪散点图、lines航线图等系列来展示点线数据。比如要在湖南省地图上标几个重点城市、画几条迁徙线用geo series-scatter就比单纯的series-map灵活得多。实际项目中两者经常叠加使用底层用geo画边界背景上层用series-map做数据着色再叠一层scatter标记点位。注册地图的流程是一样的都是registerMap同一个名称这点要注意。2.3 异步加载地图 JSON 的项目级写法工程化项目里很少把所有的 JSON 都在入口处一次性 import 进来更好的做法是按需异步加载。尤其是后面要做下钻市级、县级数据不能一开始就全塞进内存否则首屏加载会非常慢。async function loadMap(mapName, adcode) { const res await fetch(/geo/${adcode}.json) const geoJson await res.json() echarts.registerMap(mapName, geoJson) return mapName }这段代码的意图是每次要切换层级时只加载当前层级的 GeoJSON 并注册然后setOption切换到对应地图。这样首屏只需加载省级数据后续用户点哪个市再拉哪个市的数据结构清晰加载速度也可控。3. 省市县三级下钻点击、返回与数据动态加载3.1 下钻的核心思路维护一个层级栈省市县下钻最常见的实现是给地图绑定click事件获取被点击区域的名称然后判断当前层级再去加载下一级的地图数据。完整方案需要一个层级栈来记录用户浏览路径方便返回操作。const levelStack [{ mapName: hunan, level: province }] let currentLevel province chart.on(click, (params) { const name params.name if (currentLevel province) { // 点击某个市进入市级视图 const cityAdcode getAdcodeByCityName(name) loadMap(name, cityAdcode).then(() { levelStack.push({ mapName: name, level: city, adcode: cityAdcode }) currentLevel city chart.setOption({ series: [{ map: name }] }) }) } else if (currentLevel city) { // 点击某个县进入县级视图 const countyAdcode getAdcodeByCountyName(name) loadMap(name, countyAdcode).then(() { levelStack.push({ mapName: name, level: county, adcode: countyAdcode }) currentLevel county chart.setOption({ series: [{ map: name }] }) }) } })返回逻辑就是从levelStack里弹出当前项重新注册并渲染上一级。注意省级地图注册名我建议固定用hunan市级和县级地图直接用城市名称或拼音做标识方便在series.map里直接引用。3.2 事件绑定和数据清洗的细节这里有几个实战中一定会遇到的细节。第一chart.on(click, ...)绑定一次就够了不要放在循环里重复绑定否则一次点击会触发多次加载。第二点击事件的params.name来自 GeoJSON 的properties.name所以你拿到的可能是长沙市也可能是长沙必须统一格式化后再去匹配业务数据。我个人的习惯是在准备 GeoJSON 时就直接把name改干净统一成长沙市这种官方名称后续所有数据源都按这个标准对齐一劳永逸。第三在市级、县级地图视图下点击事件依然会触发但省份层级和市层级下钻要写不同逻辑建议用currentLevel变量做分支避免县一级点击后又去加载不存在的县下辖镇。3.3 数据动态加载时的 loading 状态处理GeoJSON 文件在服务器上用户网络状况不可控加载期间地图会短暂空白。如果什么提示都不给用户会觉得页面卡死了。合理的做法是在加载前调用chart.showLoading()加载完成后再chart.hideLoading()chart.showLoading({ text: 地图加载中... }) try { await loadMap(mapName, adcode) chart.setOption({ series: [{ map: mapName }] }) } finally { chart.hideLoading() }3.4 数据匹配不上时的兜底方案实际业务中还会遇到 GeoJSON 里有、业务数据里没有或者反过来业务数据有、GeoJSON 里没有的情况。比如 GeoJSON 叫湘西土家族苗族自治州而业务接口返回的 key 是湘西州名称对不上就显示不了数据。这种问题我建议做两层处理第一层在数据源阶段尽量统一命名第二层在代码里维护一个同义词映射表const nameAlias { 湘西州: 湘西土家族苗族自治州, 株洲: 株洲市 }setOption之前把业务数据的 name 先映射一遍能避免大量无谓的排查时间。4. 给某些市标记数量label、散点和 visualMap 分段的正确打开方式4.1 只让指定城市显示数量标签echarts 地图怎么给某些市标记数量是个高频需求。比如湖南的某个项目只关心长沙、株洲、湘潭三个城市的业务数据其他城市虽然也在地图上但不想显示数字标签。最直接的方式是利用label.formatter回调const showCities [长沙市, 株洲市, 湘潭市] series: [ { type: map, label: { show: true, fontSize: 12, formatter: (params) { if (showCities.includes(params.name)) { return ${params.name}\n${params.value ?? 0} } return } } } ]这段代码的思路是formatter对每个区域都会被调用一次判断当前区域名称是否在目标列表里如果在就返回名称数值如果不在就返回空字符串。效果就是只有关心的城市显示数字其他区域保持干净。实际项目中如果还想让这些高亮城市更显眼可以给对应区域设置不同的itemStyle.areaColor代码逻辑类似。4.2 用散点图层做点标记比标签更灵活标签显示有一个限制文字只能停留在区域中心版式设计上不够灵活。如果希望在地图上的特定位置标记数量、打点、甚至加涟漪动效更专业的做法是叠加一个series-scatter图层。series: [ { type: map, map: hunan, // 地图层 }, { type: scatter, coordinateSystem: geo, data: [ { name: 长沙市, value: [112.93, 28.23, 120] }, { name: 株洲市, value: [113.13, 27.83, 80] } ], symbolSize: (val) val[2] / 10, label: { show: true, formatter: {b}\n{c} } } ]注意scatter的data里value是[经度, 纬度, 数值]这样的结构前三项中的前两项是坐标第三项是实际要展示的数值。这样就能把数量标注在指定坐标上且不受区域边界限制。这一招用来做城市重点指标、门店位置、事件热点的标记非常实用。4.3 visualMap 分段颜色从 9 段调整成 10 段关于echarts 地图 9 段图变 10 段图本质上是对visualMap做分段控制。默认的连续型visualMap会根据min/max自动切分但分段数不一定是整数而且默认配色有时不合需求。遇到这个问题建议直接改成type: piecewise手写分段段数完全自己控制visualMap: { type: piecewise, pieces: [ { min: 0, max: 10, label: 0-10 }, { min: 11, max: 20, label: 11-20 }, { min: 21, max: 30, label: 21-30 }, { min: 31, max: 40, label: 31-40 }, { min: 41, max: 50, label: 41-50 }, { min: 51, max: 60, label: 51-60 }, { min: 61, max: 70, label: 61-70 }, { min: 71, max: 80, label: 71-80 }, { min: 81, max: 90, label: 81-90 }, { min: 91, max: 100, label: 90 } ], inRange: { color: [#d94e5d, #eac736, #50a3ba] } }这里我写了 10 段实际想要几段就写几个pieces对象。比默认连续分段更可控的地方在于你可以自由定义区间的上下限、每段的显示文字甚至可以让某些区间不连续。之前有人问我为什么默认显示出来只有 9 段十有八九是max和数据范围没有整除或者是splitNumber设置得不够明确。用手写pieces的方式这个问题的根因直接消失了。5. 项目实测中绕不开的坑跨域加载、raw异常与样式调优5.1 本地打开 HTML 时无法加载 JSON 文件怎么办这是一个前端兼容性问题但出现频率非常高甚至能卡住一个新手半天。当你直接用 Edge 或 Chrome 双击本地 HTML 文件打开时页面地址是file://协议此时用fetch请求本地 GeoJSON 文件浏览器会拦截跨域请求控制台报错类似 Access to fetch at file:///... from origin null has been blocked by CORS policy。解决办法有三条按推荐顺序排列起一个本地静态服务。在项目目录下执行npx serve或python -m http.server 8080然后通过http://localhost:8080访问页面。这是最规范的做法线上的运行方式也一致。把 JSON 转成 JS 文件。把hunan.json改成hunan.js内容写window.HUNAN_JSON { ... }然后在 HTML 里用script src./hunan.js/script引入。这种方案绕过了fetch没有任何跨域问题虽然写法不太工程化但应付本地 demo 和简单分享很方便。用import方式引入。如果你用了 Vite 或 Webpack 这类构建工具直接import hunanJson from ./hunan.json就行构建工具会自己把 JSON 嵌入到打包产物里本地开发时由 dev server 提供服务不会触发浏览器跨域。5.2 Vue 项目里地图渲染成 raw 是什么回事热搜词里出现的vue echarts图异常 raw我第一反应就是排查渲染时序。常见场景是从后端接口拉取地图数据接口还没返回组件就把setOption执行了或者返回的数据结构不是预期的 GeoJSON导致 ECharts 内部解析失败调试面板里看到一串原始 JSON也就是被标记成raw。这个问题的排查链路一般是先在接口返回处打日志确认拿到的数据真的是 GeoJSON 结构再确认registerMap是在setOption之前调用最后确认series.map的名称和registerMap注册名称一致避免因为名字不匹配导致 ECharts 使用了错误的内部数据源。如果组件在销毁后还有异步回调去setOption也会出现异常需要在onUnmounted里调用chart.dispose()并在回调里判断chart.isDisposed()。5.3 边界线粗细、标签重叠的观感调整地图渲染出来边界线太粗、标签重叠是观感问题里最常见的。边界线在itemStyle.borderColor和itemStyle.borderWidth里调一般borderWidth设1或0.8就够用了太粗会让整个地图显得很笨重series: [ { type: map, itemStyle: { areaColor: #f0f5f8, borderColor: #8ba8c8, borderWidth: 0.8 }, emphasis: { itemStyle: { areaColor: #ffd666 } } } ]标签重叠主要发生在区县密集的区域比如长沙市内几个区靠得很近字号一大就全挤在一起。优先把label.fontSize降到 10~11实在不行再用formatter截断名称比如超过 4 个字就只保留前几个字加省略号。另外开启roam: true后用户能缩放地图缩放级别高时标签会跟着放大可以考虑在formatter里根据chart.getOption()的缩放状态做动态显隐但这个属于锦上添花一般项目用固定字号就够了。5.4 地图不显示的快速排查清单最后把地图空白这类问题整理成一张排查表适合卡住时对照检查现象常见原因解决办法地图完全空白未调用registerMap或注册名不一致检查registerMap(hunan)与series.map: hunan地图轮廓有了但没有颜色data数组 name 与 GeoJSON name 不匹配统一名称字段或维护名称映射表点击区域无响应当前数据中没有这个 name或者事件绑定在错误实例上打印params.name确认与 GeoJSON 一致下钻后返回上级异常层级栈未正确弹出或上级地图已丢失每次返回时重新registerMap并setOption边缘显示不完整GeoJSON 精度太低或文件被截断更换数据源或重新下载完整边界文件地图这类需求最容易出问题的点就是数据而不是代码。GeoJSON 来源杂、名称乱、行政区域调整频繁这些都是客观存在的行业现状用一套名称标准化 按需加载 层级栈管理的固定流程去应对基本能覆盖 90% 以上的项目场景。我个人的习惯是把湖南省所有市、县的 adcode 和名称维护成一个静态配置文件前端需要下钻时直接查这个配置去拼 GeoJSON 地址避免每次都在代码里写死字符串。做到这步之后这套地图组件完全可以抽成通用模块下次换湖北省、广东省只需要换数据源和 adcode 配置代码一行不用动。本文还有配套的精品资源点击获取
简介面向需要基于ECharts搭建地理数据可视化的前端工程师与数据分析师本资料提供完整的湖南省各市、区县两级GeoJSON边界数据解决手动绘制地理边界、寻找合规JSON的痛点。压缩包采用rar格式体积仅631KB内部按市/县维度拆分文件目录结构清晰省市县层级一目了然路径层级与行政区划一致。使用者可按需选取单个区域的json放入项目配合ECharts官方地图组件即可快速渲染地图例如展示长沙市各区县时直接解压长沙对应文件即可完成接入无需额外处理。目前已有2159人学习下载内容覆盖湖南省全部下辖行政区划适合用于政务大屏、运营看板、区域数据报告等可视化场景帮助开发者将业务数据投射到地理维度直观呈现各地区分布与对比差异。 都说ECharts地图是最容易看起来简单、做起来抓瞎的可视化场景。产品丢过来一句加个湖南省地图市要能点县最好也能点你打开官方示例一看全是全国地图怎么画、中国地图的JSON怎么注册真正落到省一级、市一级、县一级的数据从哪来、怎么下钻、怎么标数量的资料反而稀碎。这篇就来把 echarts 湖南省 JSON 地图含各市、各县这条线完整捋一遍从 GeoJSON 获取校验、注册渲染、市县级联动下钻到指定城市标记数量、visualMap 分段调整最后再集中说说我在实际项目里踩过的高频坑。适合刚接触地图可视化的前端开发也适合被数据可视化需求临时抓壮丁的运维和测试同学照着做至少能少走几段弯路。1. 地图数据从哪来湖南省省、市、县三级 GeoJSON 的获取与校验1.1 为什么 echarts 地图必须先有 JSON 数据先说个很多人没意识到的点ECharts 从 5.x 开始不再内置任何地图数据。4.x 时代还能通过引入echarts/map/js/china.js直接用全国地图到了 5.x官方把地图文件彻底从包里拆了出去。你必须在setOption之前调用echarts.registerMap(地图名, GeoJSON对象)手动注册没有这步操作地图画出来就是一块空白。这里说的 GeoJSON 本质上是一个描述地理轮廓的标准 JSON 结构它用一个个坐标数组定义出某个区域的边界。湖南省要满足包含各市、县的需求至少需要准备三套数据湖南省省级边界一个完整的湖南轮廓14 个地级行政区边界长沙、株洲、湘潭等 13 个地级市加湘西土家族苗族自治州各县/区边界比如长沙市的芙蓉区、天心区、岳麓区很多 demo 里只放一个省界文件实际做出来你会发现点击某个市根本没反应就是因为市这一级的 GeoJSON 压根没注册。1.2 几套可靠的数据获取方案我试过比较靠谱的获取渠道有三类第一阿里云 DataV.GeoAtlas。这是目前最简单稳定的免费方案。它提供了全国各行政区域的 GeoJSON 下载而且 URL 规则非常规律适合程序化获取。大致规律是https://geo.datav.aliyun.com/areas_v3/bound/430000_full.json其中430000是湖南省的行政区划代码adcode。把地址里数字换成某个市的 adcode就能拿到对应市的边界比如长沙市是430100。DataV 页面打开湖南省时返回的数据里会带children字段里面就列出了每个下级区域的名称和 adcode拿到后可以继续拼接下级 URL。做省市县三级下钻时这套规律帮了大忙。第二GitHub 上的开源地理数据仓库。搜关键词 china geojson 或 hunan geojson 能找到不少整理好的数据有些甚至把全国省、市、县三级都打包好了。优点是数据集中、版本统一缺点是数据新旧程度不一有的还停留在宁乡县这类旧行政区划名称。用之前务必交叉验证一遍。第三从全国县级边界自己裁剪。如果你手上只有一份全国县级 GeoJSON可以用 Python 写个小脚本按 adcode 前 4 位过滤出湖南省范围再用 geopandas 等工具把边界合并或筛选出来。这条路最费时间一般不推荐非地理专业的人走。1.3 拿到 JSON 后别急着用先做三个校验我见过太多人栽在JSON 格式明明没错但地图就是不显示这个问题上。拿到 GeoJSON 后建议按顺序做三件事第一校验结构完整性。确认数据根节点是FeatureCollectionfeatures数组里的每个元素包含geometry和properties.name。用JSON.parse能过不代表坐标没问题但结构能过是第一步。第二校验名称规范。ECharts 地图的点击事件和数据显示都是以properties.name作为匹配主键的。同一个市业务数据里叫长沙GeoJSON 里叫长沙市两者对不上地图上这个区域就没法绑定数值点击也点不中。第三校验文件精度和体积。精确到区县级的 GeoJSON 文件可能有好几 MB浏览器解析起来有压力。如果只是做展示不做精细圈选建议用简化工具降低坐标精度保留总体轮廓即可。一个省界文件压到几百 KB 完全够用。2. 注册地图与首屏渲染把湖南省先画到画布上2.1 registerMap 的正确使用方式地图注册这一步是整个项目的地基。用 Vue 3 ECharts 5 举例最直接的方式是import * as echarts from echarts import hunanJson from /geo/hunan.json // 模块化导入 echarts.registerMap(hunan, hunanJson) const chart echarts.init(document.getElementById(mapContainer)) chart.setOption({ tooltip: { trigger: item }, visualMap: { min: 0, max: 100, left: 20, bottom: 20, text: [高, 低], inRange: { color: [#e0f3f8, #abd9e9, #74add1, #4575b4, #313695] } }, series: [ { type: map, map: hunan, roam: true, label: { show: true }, data: [ { name: 长沙市, value: 120 }, { name: 株洲市, value: 80 } // 其他城市 ] } ] })注意几个关键点。registerMap的第一个参数是地图标识第二个参数是 GeoJSON 对象。series.map的值必须和这个标识完全一致很多空白地图的问题就是这里拼错了或者引号打错。另外data数组里的name必须和 GeoJSON 里的properties.name对得上对不上时这块区域不会报错但也不会显示数值和颜色。2.2 map 系列和 geo 组件的选型差异ECharts 里画地图有两条路series-map和geo组件不少人会混着用简单说一下区别。series-map是地图系列核心能力是把数据值映射到区域颜色上适合做数据热力分布、区域统计这类需求。我们上面写的这种就是它。geo组件更像是一个地理坐标系背景板本身不关联业务数据更多是配合scatter散点图、effectScatter涟漪散点图、lines航线图等系列来展示点线数据。比如要在湖南省地图上标几个重点城市、画几条迁徙线用geo series-scatter就比单纯的series-map灵活得多。实际项目中两者经常叠加使用底层用geo画边界背景上层用series-map做数据着色再叠一层scatter标记点位。注册地图的流程是一样的都是registerMap同一个名称这点要注意。2.3 异步加载地图 JSON 的项目级写法工程化项目里很少把所有的 JSON 都在入口处一次性 import 进来更好的做法是按需异步加载。尤其是后面要做下钻市级、县级数据不能一开始就全塞进内存否则首屏加载会非常慢。async function loadMap(mapName, adcode) { const res await fetch(/geo/${adcode}.json) const geoJson await res.json() echarts.registerMap(mapName, geoJson) return mapName }这段代码的意图是每次要切换层级时只加载当前层级的 GeoJSON 并注册然后setOption切换到对应地图。这样首屏只需加载省级数据后续用户点哪个市再拉哪个市的数据结构清晰加载速度也可控。3. 省市县三级下钻点击、返回与数据动态加载3.1 下钻的核心思路维护一个层级栈省市县下钻最常见的实现是给地图绑定click事件获取被点击区域的名称然后判断当前层级再去加载下一级的地图数据。完整方案需要一个层级栈来记录用户浏览路径方便返回操作。const levelStack [{ mapName: hunan, level: province }] let currentLevel province chart.on(click, (params) { const name params.name if (currentLevel province) { // 点击某个市进入市级视图 const cityAdcode getAdcodeByCityName(name) loadMap(name, cityAdcode).then(() { levelStack.push({ mapName: name, level: city, adcode: cityAdcode }) currentLevel city chart.setOption({ series: [{ map: name }] }) }) } else if (currentLevel city) { // 点击某个县进入县级视图 const countyAdcode getAdcodeByCountyName(name) loadMap(name, countyAdcode).then(() { levelStack.push({ mapName: name, level: county, adcode: countyAdcode }) currentLevel county chart.setOption({ series: [{ map: name }] }) }) } })返回逻辑就是从levelStack里弹出当前项重新注册并渲染上一级。注意省级地图注册名我建议固定用hunan市级和县级地图直接用城市名称或拼音做标识方便在series.map里直接引用。3.2 事件绑定和数据清洗的细节这里有几个实战中一定会遇到的细节。第一chart.on(click, ...)绑定一次就够了不要放在循环里重复绑定否则一次点击会触发多次加载。第二点击事件的params.name来自 GeoJSON 的properties.name所以你拿到的可能是长沙市也可能是长沙必须统一格式化后再去匹配业务数据。我个人的习惯是在准备 GeoJSON 时就直接把name改干净统一成长沙市这种官方名称后续所有数据源都按这个标准对齐一劳永逸。第三在市级、县级地图视图下点击事件依然会触发但省份层级和市层级下钻要写不同逻辑建议用currentLevel变量做分支避免县一级点击后又去加载不存在的县下辖镇。3.3 数据动态加载时的 loading 状态处理GeoJSON 文件在服务器上用户网络状况不可控加载期间地图会短暂空白。如果什么提示都不给用户会觉得页面卡死了。合理的做法是在加载前调用chart.showLoading()加载完成后再chart.hideLoading()chart.showLoading({ text: 地图加载中... }) try { await loadMap(mapName, adcode) chart.setOption({ series: [{ map: mapName }] }) } finally { chart.hideLoading() }3.4 数据匹配不上时的兜底方案实际业务中还会遇到 GeoJSON 里有、业务数据里没有或者反过来业务数据有、GeoJSON 里没有的情况。比如 GeoJSON 叫湘西土家族苗族自治州而业务接口返回的 key 是湘西州名称对不上就显示不了数据。这种问题我建议做两层处理第一层在数据源阶段尽量统一命名第二层在代码里维护一个同义词映射表const nameAlias { 湘西州: 湘西土家族苗族自治州, 株洲: 株洲市 }setOption之前把业务数据的 name 先映射一遍能避免大量无谓的排查时间。4. 给某些市标记数量label、散点和 visualMap 分段的正确打开方式4.1 只让指定城市显示数量标签echarts 地图怎么给某些市标记数量是个高频需求。比如湖南的某个项目只关心长沙、株洲、湘潭三个城市的业务数据其他城市虽然也在地图上但不想显示数字标签。最直接的方式是利用label.formatter回调const showCities [长沙市, 株洲市, 湘潭市] series: [ { type: map, label: { show: true, fontSize: 12, formatter: (params) { if (showCities.includes(params.name)) { return ${params.name}\n${params.value ?? 0} } return } } } ]这段代码的思路是formatter对每个区域都会被调用一次判断当前区域名称是否在目标列表里如果在就返回名称数值如果不在就返回空字符串。效果就是只有关心的城市显示数字其他区域保持干净。实际项目中如果还想让这些高亮城市更显眼可以给对应区域设置不同的itemStyle.areaColor代码逻辑类似。4.2 用散点图层做点标记比标签更灵活标签显示有一个限制文字只能停留在区域中心版式设计上不够灵活。如果希望在地图上的特定位置标记数量、打点、甚至加涟漪动效更专业的做法是叠加一个series-scatter图层。series: [ { type: map, map: hunan, // 地图层 }, { type: scatter, coordinateSystem: geo, data: [ { name: 长沙市, value: [112.93, 28.23, 120] }, { name: 株洲市, value: [113.13, 27.83, 80] } ], symbolSize: (val) val[2] / 10, label: { show: true, formatter: {b}\n{c} } } ]注意scatter的data里value是[经度, 纬度, 数值]这样的结构前三项中的前两项是坐标第三项是实际要展示的数值。这样就能把数量标注在指定坐标上且不受区域边界限制。这一招用来做城市重点指标、门店位置、事件热点的标记非常实用。4.3 visualMap 分段颜色从 9 段调整成 10 段关于echarts 地图 9 段图变 10 段图本质上是对visualMap做分段控制。默认的连续型visualMap会根据min/max自动切分但分段数不一定是整数而且默认配色有时不合需求。遇到这个问题建议直接改成type: piecewise手写分段段数完全自己控制visualMap: { type: piecewise, pieces: [ { min: 0, max: 10, label: 0-10 }, { min: 11, max: 20, label: 11-20 }, { min: 21, max: 30, label: 21-30 }, { min: 31, max: 40, label: 31-40 }, { min: 41, max: 50, label: 41-50 }, { min: 51, max: 60, label: 51-60 }, { min: 61, max: 70, label: 61-70 }, { min: 71, max: 80, label: 71-80 }, { min: 81, max: 90, label: 81-90 }, { min: 91, max: 100, label: 90 } ], inRange: { color: [#d94e5d, #eac736, #50a3ba] } }这里我写了 10 段实际想要几段就写几个pieces对象。比默认连续分段更可控的地方在于你可以自由定义区间的上下限、每段的显示文字甚至可以让某些区间不连续。之前有人问我为什么默认显示出来只有 9 段十有八九是max和数据范围没有整除或者是splitNumber设置得不够明确。用手写pieces的方式这个问题的根因直接消失了。5. 项目实测中绕不开的坑跨域加载、raw异常与样式调优5.1 本地打开 HTML 时无法加载 JSON 文件怎么办这是一个前端兼容性问题但出现频率非常高甚至能卡住一个新手半天。当你直接用 Edge 或 Chrome 双击本地 HTML 文件打开时页面地址是file://协议此时用fetch请求本地 GeoJSON 文件浏览器会拦截跨域请求控制台报错类似 Access to fetch at file:///... from origin null has been blocked by CORS policy。解决办法有三条按推荐顺序排列起一个本地静态服务。在项目目录下执行npx serve或python -m http.server 8080然后通过http://localhost:8080访问页面。这是最规范的做法线上的运行方式也一致。把 JSON 转成 JS 文件。把hunan.json改成hunan.js内容写window.HUNAN_JSON { ... }然后在 HTML 里用script src./hunan.js/script引入。这种方案绕过了fetch没有任何跨域问题虽然写法不太工程化但应付本地 demo 和简单分享很方便。用import方式引入。如果你用了 Vite 或 Webpack 这类构建工具直接import hunanJson from ./hunan.json就行构建工具会自己把 JSON 嵌入到打包产物里本地开发时由 dev server 提供服务不会触发浏览器跨域。5.2 Vue 项目里地图渲染成 raw 是什么回事热搜词里出现的vue echarts图异常 raw我第一反应就是排查渲染时序。常见场景是从后端接口拉取地图数据接口还没返回组件就把setOption执行了或者返回的数据结构不是预期的 GeoJSON导致 ECharts 内部解析失败调试面板里看到一串原始 JSON也就是被标记成raw。这个问题的排查链路一般是先在接口返回处打日志确认拿到的数据真的是 GeoJSON 结构再确认registerMap是在setOption之前调用最后确认series.map的名称和registerMap注册名称一致避免因为名字不匹配导致 ECharts 使用了错误的内部数据源。如果组件在销毁后还有异步回调去setOption也会出现异常需要在onUnmounted里调用chart.dispose()并在回调里判断chart.isDisposed()。5.3 边界线粗细、标签重叠的观感调整地图渲染出来边界线太粗、标签重叠是观感问题里最常见的。边界线在itemStyle.borderColor和itemStyle.borderWidth里调一般borderWidth设1或0.8就够用了太粗会让整个地图显得很笨重series: [ { type: map, itemStyle: { areaColor: #f0f5f8, borderColor: #8ba8c8, borderWidth: 0.8 }, emphasis: { itemStyle: { areaColor: #ffd666 } } } ]标签重叠主要发生在区县密集的区域比如长沙市内几个区靠得很近字号一大就全挤在一起。优先把label.fontSize降到 10~11实在不行再用formatter截断名称比如超过 4 个字就只保留前几个字加省略号。另外开启roam: true后用户能缩放地图缩放级别高时标签会跟着放大可以考虑在formatter里根据chart.getOption()的缩放状态做动态显隐但这个属于锦上添花一般项目用固定字号就够了。5.4 地图不显示的快速排查清单最后把地图空白这类问题整理成一张排查表适合卡住时对照检查现象常见原因解决办法地图完全空白未调用registerMap或注册名不一致检查registerMap(hunan)与series.map: hunan地图轮廓有了但没有颜色data数组 name 与 GeoJSON name 不匹配统一名称字段或维护名称映射表点击区域无响应当前数据中没有这个 name或者事件绑定在错误实例上打印params.name确认与 GeoJSON 一致下钻后返回上级异常层级栈未正确弹出或上级地图已丢失每次返回时重新registerMap并setOption边缘显示不完整GeoJSON 精度太低或文件被截断更换数据源或重新下载完整边界文件地图这类需求最容易出问题的点就是数据而不是代码。GeoJSON 来源杂、名称乱、行政区域调整频繁这些都是客观存在的行业现状用一套名称标准化 按需加载 层级栈管理的固定流程去应对基本能覆盖 90% 以上的项目场景。我个人的习惯是把湖南省所有市、县的 adcode 和名称维护成一个静态配置文件前端需要下钻时直接查这个配置去拼 GeoJSON 地址避免每次都在代码里写死字符串。做到这步之后这套地图组件完全可以抽成通用模块下次换湖北省、广东省只需要换数据源和 adcode 配置代码一行不用动。本文还有配套的精品资源点击获取
