简介这份面向 ECharts 地图可视化开发者的 china.js 资源包聚焦中国地图及省级行政区地图的数据接入与展示适合需要在网页中呈现区域数据分布的前端开发者、数据可视化学习者使用。压缩包为 rar 格式共 35 个 js 文件整体约 841KB核心包括中国地图脚本与各省份地图脚本可直接配合 ECharts 完成全国或省级地图的初始化、区域着色与交互配置。目前已有 5705 人学习下载说明其在同类地图资源中具有一定参考价值。包内文件按全国与省级维度组织便于按目标区域取用减少自行整理地理数据的时间借助 ECharts 的 geo 与 series 配置还能实现悬浮提示、区域高亮、数据动态更新等效果适合区域统计看板、业务分布展示等场景帮助读者快速搭建中国地图可视化页面并验证数据呈现效果。1. 从一份 china.js 压缩包说起ECharts 地图资源到底怎么落地第一次把 ECharts 的地图从在线示例搬到本地时很多人会卡在同一个地方图表容器有了option 也写了页面却只剩一个空框。china.js 中国及各地 js 文件压缩包解决的正是这类落地问题——它把全国图和省级、地市级地图脚本按文件拆开配合 ECharts 的 registerMap 使用不依赖外部地图服务。适合需要在内网、离线演示、后台报表里快速接入地图的开发者也适合已经用过 echarts china.js 但被路径、注册顺序和名称匹配折腾过的人。它不是什么万能地图引擎本质是一组可被浏览器直接加载的地图脚本资源价值在于省掉从地理数据到 ECharts 注册这段重复劳动。2. 拆开压缩包看结构china.js、省级文件与 ECharts 注册顺序拿到压缩包后先别急着往项目里丢。地图资源最容易翻车的地方不是样式而是文件粒度和注册链路全国图、省级图、地市级图各自对应不同的脚本加载顺序错了页面可能不报错但地图就是不出来。下面按文件结构、注册原理、最小示例三步拆开。2.1 压缩包里通常有什么文件命名与地图粒度这类资源包一般会按行政层级拆成多个 js 文件常见形态是china.js作为全国图入口省级文件以区域标识命名部分包还会带地市级文件。文件名本身往往就是地图注册名的一部分所以不要随意改文件名除非你同步维护一张映射表。一个合格的地图脚本通常做两件事把地理边界数据挂到全局变量或模块导出上再调用echarts.registerMap(地图名, geoJson)完成注册。不同压缩包的导出方式不一样有的直接执行注册有的只暴露数据对象需要你手动注册。先看清这一点后面的加载方式才不会写反。文件类型常见作用推荐加载方式注意点china.js全国图注册或全国地理数据首屏需要时同步引入或动态加载确认是否已自动 registerMap省级 js单区域地图注册下钻时按需加载注册名要和数据 name 对齐地市级 js更细粒度地图二级下钻或独立页面加载体积和请求数要控制说明文件/示例文件清单与用法只读不参与构建不要当成运行时依赖我一般会先建一个maps/静态目录把压缩包里的 js 按原文件名放进去再写一个mapRegistry记录“文件路径、注册名、父级地图、是否已加载”。这张表看起来笨但后面做下钻、返回全国图、按需加载时它能省掉大量靠记忆猜名字的时间。文件名和注册名不一致是常见坑尤其是压缩包经过二次整理后文件名被改成拼音或编号而脚本内部的registerMap还是旧名字。判断方法很简单打开 js 文件搜索registerMap看第一个参数是什么如果没有就看导出的变量名和数据结构。2.2 为什么不能直接 import 就完事registerMap 的注册链路ECharts 画地图不是靠series.type map自动识别地理数据的它需要先有一个已注册的地图名。registerMap就是把地理边界数据和地图名绑定起来。很多示例页面能跑是因为示例在 HTML 里直接引入了已经执行注册的china.js你把它改成模块化引入后脚本可能只导出了数据没有执行注册于是series.map写对了也白搭。这个链路可以拆成四步加载脚本、拿到地理数据、调用registerMap、在 option 里引用同名地图。任何一步缺失表现都可能是空白或控制台警告。还有一种情况是重复注册。单页应用里多个组件都引入同一个地图文件每次引入都执行一次registerMap多数情况下不会立刻报错但地图实例多了以后会出现样式错乱、下钻返回异常排查起来像玄学。稳妥做法是把注册动作收口到一个模块里用Map记录已注册的地图名重复调用直接返回。注册名不要用文件路径也不要用显示标题固定成短标识例如country、region-01然后在业务数据里维护显示名和注册名的映射。2.3 最小可跑示例从本地 js 到第一个地图实例先写一个不依赖构建工具的最小页面把“加载、注册、初始化”跑通再谈工程化。下面的示例假设china.js已经放在./maps/china.js并且脚本执行后会暴露window.__CHINA_GEO__或直接完成注册。实际压缩包如果只暴露数据就把注册那一步打开。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / title地图最小示例/title script src./echarts.min.js/script !-- 先加载地图脚本确保注册动作在初始化之前完成 -- script src./maps/china.js/script /head body div idmap stylewidth: 900px; height: 600px;/div script // 兼容两种资源包已自动注册或只暴露地理数据 if (!echarts.getMap(country) window.__CHINA_GEO__) { echarts.registerMap(country, window.__CHINA_GEO__); } const chart echarts.init(document.getElementById(map)); const option { tooltip: { trigger: item }, series: [ { type: map, map: country, // 必须和 registerMap 的第一个参数一致 roam: true, label: { show: false }, itemStyle: { areaColor: #e8eef7, borderColor: #8fa3bf }, emphasis: { itemStyle: { areaColor: #f2c94c } }, data: [ // name 必须匹配地图数据里的区域名称这里用占位符 { name: REGION_NAME, value: 120 } ] } ] }; chart.setOption(option); window.addEventListener(resize, () chart.resize()); /script /body /html代码里的关键点有三个echarts.getMap(country)用来判断是否已经注册避免重复执行registerMap的第二个参数必须是地理数据对象不能传文件路径series.map的值必须和注册名完全一致。roam控制缩放和平移报表场景里建议打开但移动端要配合scaleLimit限制缩放范围。data里的name不是随便写的显示名它要和地理数据中的区域名称逐字匹配后缀、空格、编码差异都会导致数据落不到地图上。先用一条占位数据把地图画出来再替换成真实数据排查范围会小很多。3. 把 china.js 接进 ECharts数据绑定、视觉映射与交互配置地图能显示只是第一步真正影响可用性的是数据怎么绑、颜色怎么分、下钻怎么回来。ECharts 的 map 系列看起来配置项很多核心其实就三件事名称对齐、数值映射、状态管理。下面按数据格式、visualMap 分段、省市级下钻展开。3.1 数据格式对齐name、value 与 geoJSON 的对应关系地图数据绑定最常见的失败不是代码写错而是name对不上。ECharts 用名称去地理数据里找区域找不到就留空。很多压缩包里的地图脚本使用完整名称而业务接口返回的是简称、拼音、编码或带后缀的名称直接塞进去就会出现“有数据但地图全灰”。我一般先写一个覆盖率检查把地图数据里的名称集合取出来再和业务数据的name集合做交集覆盖率低于预期就先做映射不要急着调颜色。// 从已注册地图中读取地理数据检查业务数据名称覆盖率 function checkNameCoverage(mapName, rows) { const geo echarts.getMap(mapName); if (!geo || !geo.geoJSON) { console.warn(地图尚未注册或数据结构不兼容:, mapName); return { total: rows.length, matched: 0, missing: rows.map(r r.name) }; } const geoFeatures geo.geoJSON.features || []; const geoNames new Set( geoFeatures.map(f f.properties f.properties.name).filter(Boolean) ); const matched []; const missing []; rows.forEach(row { if (geoNames.has(row.name)) matched.push(row.name); else missing.push(row.name); }); return { total: rows.length, matched: matched.length, coverage: rows.length ? matched.length / rows.length : 0, missing }; } // 用法先注册地图再检查 const report checkNameCoverage(country, [ { name: REGION_NAME, value: 120 } ]); console.log(report);这段代码不依赖具体地名只依赖地图数据里的properties.name。echarts.getMap返回的对象结构在不同版本里可能有差异常见是geoJSON字段如果拿不到就退回读取原始地理数据变量。coverage低于 0.8 时不要硬上先做名称映射表。映射表不要写在业务组件里放到独立配置中字段至少包含rawName、mapName、note后面接口字段变化时只改一处。数值字段统一成value不要在 map 系列里塞自定义字段指望它自动识别需要额外信息就放extra在 tooltip 里取。3.2 视觉映射分段visualMap 参数怎么设才不糊visualMap负责把数值映射成颜色配置不好会出现两种极端所有区域一个色或者颜色跳变太硬看不出层次。连续型适合展示密度、总量分段型适合等级、区间。地图场景里我更常用分段型因为业务方看的是“高/中/低”而不是精确色阶。关键参数是min、max、pieces、inRange。min和max不要直接取数据最大值先用分位数或业务阈值定边界否则一个极端值会把其他区域压成同一颜色。const values [12, 35, 80, 120, 260, 410]; const sorted [...values].sort((a, b) a - b); const p50 sorted[Math.floor(sorted.length * 0.5)]; const p80 sorted[Math.floor(sorted.length * 0.8)]; const visualMap { type: piecewise, min: 0, max: sorted[sorted.length - 1], left: 20, bottom: 20, pieces: [ { lte: p50, label: 低 }, { gt: p50, lte: p80, label: 中 }, { gt: p80, label: 高 } ], inRange: { color: [#dbeafe, #60a5fa, #1d4ed8] }, outOfRange: { color: #f3f4f6 } }; const option { visualMap, series: [{ type: map, map: country, roam: true, data: [ { name: REGION_NAME, value: 120 } ] }] };pieces里的lte、gt是闭开区间边界值落在哪一段要提前确认避免两个分段都包含同一个值。inRange.color数量不要求和分段数完全一致ECharts 会插值但分段型最好用相近色系不要红绿蓝乱跳。outOfRange用来处理没有数据的区域给一个低饱和灰色比留白更清楚。left、bottom控制图例位置地图本身有缩放和平移时visualMap 不要放在容器边缘太近移动端容易挡住手势区域。数值为空时不要传0传null或直接不传该条数据否则“无数据”会被画成最低档。3.3 省市级下钻切换地图与事件监听的常见写法下钻的本质是换一张已注册的地图不是在一个地图实例上改数据。常见写法是监听click拿到区域名后加载对应省级脚本注册新地图名再setOption切换series.map。返回全国图时要注意两件事旧地图的 option 可能残留数据过滤条件也要复位。比较稳的做法是把“当前地图名、父级地图名、数据缓存”放在一个状态对象里切换时统一走一个函数不要在各个点击回调里散着写。const mapState { current: country, parent: null, registered: new Set([country]) }; async function loadMapScript(mapKey, scriptUrl) { if (mapState.registered.has(mapKey)) return; await new Promise((resolve, reject) { const script document.createElement(script); script.src scriptUrl; script.onload () { // 如果脚本没有自动注册这里需要手动 registerMap mapState.registered.add(mapKey); resolve(); }; script.onerror () reject(new Error(地图脚本加载失败: scriptUrl)); document.head.appendChild(script); }); } async function switchMap(chart, nextMapKey, scriptUrl) { await loadMapScript(nextMapKey, scriptUrl); mapState.parent mapState.current; mapState.current nextMapKey; chart.setOption({ series: [{ type: map, map: nextMapKey, roam: true, data: [] // 切换地图时先清空旧数据避免名称错配 }] }, { replaceMerge: [series] }); } // 点击下钻示例regionName 仅作占位实际从事件参数取 chart.on(click, async params { if (params.componentType ! series) return; const regionName params.name; const nextMapKey region-01; const scriptUrl ./maps/region-01.js; await switchMap(chart, nextMapKey, scriptUrl); }); // 返回全国图 function backToCountry(chart) { mapState.current country; mapState.parent null; chart.setOption({ series: [{ type: map, map: country, roam: true, data: [] }] }, { replaceMerge: [series] }); }replaceMerge: [series]很关键它能把旧 series 替换掉减少 option 合并带来的残留。loadMapScript里用Set记录已注册地图避免重复插入 script 标签。script.onload只能保证脚本执行完不能保证注册名就是你以为的那个所以加载后最好用echarts.getMap(nextMapKey)验一次拿不到就说明注册名或导出方式不匹配。下钻时先清空 data 再设新地图不要带着全国数据直接切省级图名称不匹配会产生一堆无意义警告。返回上级时同理数据要按当前层级重新取不要复用上一层的缓存。4. 资源包落地工程化按需加载、缓存与构建工具适配把地图放进真实项目后问题会从“能不能显示”变成“首屏会不会太重、打包后路径对不对、重复进入页面会不会越来越卡”。这类 js 地图文件通常体积不小全国图加多个省级图全量同步引入首屏很容易被拖慢。工程化处理的核心是只加载当前视图需要的地图加载过的做缓存离开页面时把实例和监听清理干净。4.1 只加载用到的地图文件动态 script 与模块化封装如果压缩包提供的是可直接执行的 js 文件动态script是最低成本的按需加载方式。把地图文件放静态目录用统一函数拼接路径加载成功后注册状态失败时给出可排查的错误信息。不要在每个组件里手写document.createElement(script)否则重复加载和错误处理会失控。封装时把“路径解析、去重、超时、失败重试”放在一层业务层只传地图标识。const mapLoader (() { const cache new Map(); // key: mapKey, value: Promise const base /static/maps/; function load(mapKey, fileName) { if (cache.has(mapKey)) return cache.get(mapKey); const promise new Promise((resolve, reject) { const script document.createElement(script); const timer setTimeout(() { script.remove(); reject(new Error(地图加载超时: mapKey)); }, 10000); script.src base fileName; script.async true; script.onload () { clearTimeout(timer); // 加载后验一次注册结果避免脚本执行了但注册名不对 if (!echarts.getMap(mapKey)) { reject(new Error(脚本已加载但地图未注册: mapKey)); return; } resolve(mapKey); }; script.onerror () { clearTimeout(timer); reject(new Error(地图脚本请求失败: script.src)); }; document.head.appendChild(script); }); cache.set(mapKey, promise); return promise; } return { load }; })(); // 业务侧只关心地图标识和文件名 mapLoader.load(region-01, region-01.js).then(() { // 这里再初始化或切换地图 });base要跟构建工具的静态资源目录一致不要写死成开发环境路径。cache存的是 Promise不是布尔值这样并发调用同一个地图时只会插入一个 script。超时时间按资源体积和网络环境调内网可以短一些公网静态资源可以放宽到 15 秒。加载后必须用echarts.getMap(mapKey)验证因为onload只代表文件执行完不代表注册成功。失败信息里带上mapKey和src线上排查时不用靠猜。4.2 构建工具里的静态资源处理public 目录与打包产物体积地图 js 不适合全部走模块打包。原因有两个一是很多压缩包里的脚本是立即执行式不是 ES module打包工具处理后会改变执行时机二是全量打进 bundle 会让首屏体积不可控。常见做法是把地图文件放public或静态资源目录运行时不经过打包器转换只通过 URL 加载。构建配置里要确认base和输出目录部署到子路径时尤其容易 404。// 以常见构建配置为例关键是静态目录和基础路径 export default { // 部署在子路径时这里要和网关前缀一致 base: /dashboard/, build: { outDir: dist, assetsDir: assets }, // public 下的文件会原样复制到输出目录 publicDir: public };假设地图文件放在public/static/maps/运行时路径就是/dashboard/static/maps/china.js不是/static/maps/china.js。开发环境往往没有子路径直接写/static/maps/能跑上线后 404这类坑很常见。判断方法打开浏览器网络面板看请求 URL 和实际部署路径差在哪一段。publicDir下的文件不要再 import否则可能被打包两次。地图文件命名不要带 hash因为动态加载的 URL 是手写的如果必须带 hash就用构建工具的资源清单生成映射不要靠字符串拼。4.3 多地图复用的缓存与销毁避免重复注册和内存泄漏单页应用里反复进入地图页面最容易出现的问题是实例没销毁、事件没解绑、地图脚本重复插入。ECharts 实例本身不会自动回收chart.dispose()要在组件卸载时调用window.addEventListener(resize)也要用同一个函数引用解绑。地图注册是全局的重复注册不一定报错但会让注册表越来越乱。我的习惯是把地图注册和图表实例分开管理注册只做一次实例按页面生命周期创建和销毁。function createMapChart(dom, mapKey) { const chart echarts.init(dom); const onResize () chart.resize(); window.addEventListener(resize, onResize); chart.setOption({ series: [{ type: map, map: mapKey, roam: true, data: [] }] }); return { chart, destroy() { window.removeEventListener(resize, onResize); chart.dispose(); } }; } // 页面卸载时调用 destroy不要只把 dom 清空 const holder createMapChart(document.getElementById(map), country); // holder.destroy();destroy里先解绑 resize再dispose顺序反了也不会立刻报错但习惯上先清外部监听。echarts.init的 dom 要有明确宽高容器隐藏时初始化会得到 0 尺寸后面再显示就可能是空白。地图脚本的缓存可以长期保留但图表实例不要缓存除非你确定多个页面共享同一个实例且能处理状态污染。重复注册的检查放在加载函数里用getMap判断不要用文件是否加载过来判断。5. 避坑与排查china.js 地图不显示的六类现场地图问题最难受的地方是“页面不报错”。控制台干净容器也在但地图就是不出来。下面这些现场是我在后台报表和离线演示里反复遇到的按“现象、原因、解决”拆开写。每条都尽量给出可验证的动作不要靠重启和清缓存碰运气。5.1 地图空白但控制台无报错先查 registerMap 时机现象series.map写了容器有宽高页面没有任何报错地图区域一片空白。原因通常是初始化早于地图注册。尤其是动态加载脚本时echarts.init已经执行registerMap还没完成ECharts 找不到地图名部分版本只给警告甚至不报错。解决把初始化放到地图加载 Promise 之后或者在setOption前强制检查echarts.getMap(mapKey)拿不到就等待并重试。不要用setTimeout猜时间用加载完成的回调。async function safeInit(dom, mapKey) { if (!echarts.getMap(mapKey)) { throw new Error(地图未注册检查脚本加载顺序: mapKey); } const chart echarts.init(dom); chart.setOption({ series: [{ type: map, map: mapKey, data: [] }] }); return chart; }这段检查放在业务初始化入口错误信息直接指出地图名。如果是脚本只导出数据没有注册就在加载后手动registerMap并确认第二个参数是地理数据对象。getMap返回空不一定是脚本没加载也可能是注册名写错先把注册名打印出来对照。5.2 名称对不上导致数据全灰编码与后缀的坑现象地图边界能显示但所有区域都是默认色tooltip 也没有数值。原因多数是数据name和地理数据名称不一致常见差异包括空格、全半角括号、后缀“市/省/区”、编码不一致。解决用 3.1 的覆盖率检查先定位缺失名称再做映射表。不要直接在原数据上replace掉后缀因为有些名称本身包含后缀差异粗暴替换会把本来能匹配的也改坏。映射表按“原始名到地图名”单向维护缺一条补一条。如果接口返回的是编码而不是名称就在前端维护编码到地图名的字典字典放独立文件别散在组件里。检查时把missing打印出来先人工看前十条通常能发现规律。覆盖率低但地图有颜色说明部分数据匹配上了问题在个别名称不要重写整个数据层。5.3 下钻后返回全国图错乱实例复用与 option 污染现象从全国图点进省级图正常返回全国图后数据错位、颜色不对或者上一次的 tooltip 还挂着。原因是setOption默认合并旧配置旧 series 的 data 和 visualMap 残留。解决切换地图时用replaceMerge: [series]并在切换前清空当前层数据如果 visualMap 也要按层级变化把它一起纳入替换或重新赋值。不要只改series.map就以为换了地图。返回上级时父级地图名要从状态对象取不要从当前点击参数反推。实例可以复用但状态要重置当前地图名、父级地图名、数据缓存键、缩放层级。roam打开的图表切换地图后缩放状态可能保留用户会看到上一层的缩放位置必要时调用chart.dispatchAction({ type: restore })或重新设置zoom。这类问题不报错但体验很差最好在切换函数里统一处理。5.4 打包后地图文件 404路径与 base 配置现象开发环境地图正常构建部署后空白网络面板里地图 js 请求 404。原因通常是动态加载路径写成了绝对根路径而应用部署在子路径下或者地图文件放在src里被当成模块处理构建后文件名带 hash手写 URL 对不上。解决地图文件放public静态目录加载路径基于构建工具的base拼接不要手写带 hash 的文件名。部署到子路径时base和网关前缀要一致。排查时先看请求 URL再看构建输出目录里文件实际位置。public/static/maps/china.js构建后应在dist/static/maps/china.js如果不在说明publicDir配错或被清理插件删了。CDN 场景还要确认跨域头和缓存策略地图脚本是普通 script 请求跨域配置不对会直接加载失败。不要用import引入立即执行式地图脚本执行时机和路径都容易出问题。5.5 移动端 tooltip 抖动与缩放卡顿参数与容器尺寸现象移动端手指缩放地图时卡顿tooltip 跟随抖动或者地图被图例挡住。原因通常是roam打开但没有限制缩放范围容器尺寸随布局变化但没有resizetooltip 在触摸事件里频繁重绘。解决设置scaleLimit限制最小和最大缩放容器用固定比例或 ResizeObserver 监听尺寸变化tooltip 在移动端减少formatter里的复杂计算。地图的label默认关闭移动端不要为了好看全量打开。const option { tooltip: { trigger: item, confine: true, // 限制在容器内减少溢出抖动 formatter: params { const value params.value null ? 无数据 : params.value; return params.name : value; } }, series: [{ type: map, map: country, roam: true, scaleLimit: { min: 0.8, max: 4 }, label: { show: false }, emphasis: { label: { show: true } } }] };confine: true能减少 tooltip 跑出容器但不是万能容器本身溢出隐藏也要配合。scaleLimit的min不要小于 0.5否则地图缩得太小点击区域难命中。formatter里不要做异步请求tooltip 触发频率高异步返回时鼠标可能已经移走。容器尺寸变化后调用chart.resize()不要只依赖窗口resize侧边栏展开收起也会改变容器宽度。5.6 重复进入页面后越来越卡注册表与监听器没清现象第一次进入地图页面正常来回切换几次后越来越卡甚至出现旧图表还响应点击。原因是图表实例没有disposeresize监听没有解绑地图脚本重复插入。解决组件卸载时统一销毁实例和解绑监听地图脚本用加载缓存去重不要在每次进入页面时重新registerMap。如果地图注册表已经乱了刷新页面能恢复但根因还在代码里。把创建和销毁成对写在一个模块里业务组件只调用create和destroy不要在外面零散echarts.init。检查方式在销毁函数里打印实例数量或者用浏览器内存面板看 detached DOM 是否持续增长。地图脚本的script标签加载成功后可以保留不需要移除但重复插入要避免。监听器用同一个函数引用解绑匿名函数解绑不掉这是血泪经验。6. 进阶技巧用一张校验表把地图资源管起来地图资源真正难的不是第一次跑通而是后续加文件、换数据、改部署路径时不出回归。我后来把上线前的检查做成一张表每次新增一个地图文件都按表过一遍。表里不写具体区域名只记录文件标识、注册名、数据名称覆盖率、加载方式和缓存键这样下钻和返回全国图时不用靠记忆。检查项判断方法不通过的处理注册名一致对比registerMap第一参数与series.map统一改成短标识业务层只引用标识数据覆盖率用checkNameCoverage跑一遍低于阈值先补映射表不调样式加载路径网络面板看实际请求 URL按base拼接放静态目录重复注册echarts.getMap预检查加载缓存去重注册收口销毁完整切页后看监听和实例dispose加解绑 resize// 上线前的最小校验注册、覆盖率、重复加载 async function validateMapResource(mapKey, rows) { if (!echarts.getMap(mapKey)) { throw new Error(地图未注册: mapKey); } const report checkNameCoverage(mapKey, rows); if (report.coverage 0.8) { console.warn(名称覆盖率偏低:, report); } return report; }这段校验不替代业务测试但能把最容易翻车的三类问题提前暴露地图没注册、名称大面积不匹配、覆盖率低到颜色失真。coverage阈值按业务容忍度调报表场景 0.8 起步下钻场景最好到 0.95。校验通过后再看 visualMap 和交互顺序不要反。从那以后我每次新增地图文件都先跑一遍覆盖率检查再谈样式和动效。希望帮到你。本文还有配套的精品资源点击获取
简介这份面向 ECharts 地图可视化开发者的 china.js 资源包聚焦中国地图及省级行政区地图的数据接入与展示适合需要在网页中呈现区域数据分布的前端开发者、数据可视化学习者使用。压缩包为 rar 格式共 35 个 js 文件整体约 841KB核心包括中国地图脚本与各省份地图脚本可直接配合 ECharts 完成全国或省级地图的初始化、区域着色与交互配置。目前已有 5705 人学习下载说明其在同类地图资源中具有一定参考价值。包内文件按全国与省级维度组织便于按目标区域取用减少自行整理地理数据的时间借助 ECharts 的 geo 与 series 配置还能实现悬浮提示、区域高亮、数据动态更新等效果适合区域统计看板、业务分布展示等场景帮助读者快速搭建中国地图可视化页面并验证数据呈现效果。1. 从一份 china.js 压缩包说起ECharts 地图资源到底怎么落地第一次把 ECharts 的地图从在线示例搬到本地时很多人会卡在同一个地方图表容器有了option 也写了页面却只剩一个空框。china.js 中国及各地 js 文件压缩包解决的正是这类落地问题——它把全国图和省级、地市级地图脚本按文件拆开配合 ECharts 的 registerMap 使用不依赖外部地图服务。适合需要在内网、离线演示、后台报表里快速接入地图的开发者也适合已经用过 echarts china.js 但被路径、注册顺序和名称匹配折腾过的人。它不是什么万能地图引擎本质是一组可被浏览器直接加载的地图脚本资源价值在于省掉从地理数据到 ECharts 注册这段重复劳动。2. 拆开压缩包看结构china.js、省级文件与 ECharts 注册顺序拿到压缩包后先别急着往项目里丢。地图资源最容易翻车的地方不是样式而是文件粒度和注册链路全国图、省级图、地市级图各自对应不同的脚本加载顺序错了页面可能不报错但地图就是不出来。下面按文件结构、注册原理、最小示例三步拆开。2.1 压缩包里通常有什么文件命名与地图粒度这类资源包一般会按行政层级拆成多个 js 文件常见形态是china.js作为全国图入口省级文件以区域标识命名部分包还会带地市级文件。文件名本身往往就是地图注册名的一部分所以不要随意改文件名除非你同步维护一张映射表。一个合格的地图脚本通常做两件事把地理边界数据挂到全局变量或模块导出上再调用echarts.registerMap(地图名, geoJson)完成注册。不同压缩包的导出方式不一样有的直接执行注册有的只暴露数据对象需要你手动注册。先看清这一点后面的加载方式才不会写反。文件类型常见作用推荐加载方式注意点china.js全国图注册或全国地理数据首屏需要时同步引入或动态加载确认是否已自动 registerMap省级 js单区域地图注册下钻时按需加载注册名要和数据 name 对齐地市级 js更细粒度地图二级下钻或独立页面加载体积和请求数要控制说明文件/示例文件清单与用法只读不参与构建不要当成运行时依赖我一般会先建一个maps/静态目录把压缩包里的 js 按原文件名放进去再写一个mapRegistry记录“文件路径、注册名、父级地图、是否已加载”。这张表看起来笨但后面做下钻、返回全国图、按需加载时它能省掉大量靠记忆猜名字的时间。文件名和注册名不一致是常见坑尤其是压缩包经过二次整理后文件名被改成拼音或编号而脚本内部的registerMap还是旧名字。判断方法很简单打开 js 文件搜索registerMap看第一个参数是什么如果没有就看导出的变量名和数据结构。2.2 为什么不能直接 import 就完事registerMap 的注册链路ECharts 画地图不是靠series.type map自动识别地理数据的它需要先有一个已注册的地图名。registerMap就是把地理边界数据和地图名绑定起来。很多示例页面能跑是因为示例在 HTML 里直接引入了已经执行注册的china.js你把它改成模块化引入后脚本可能只导出了数据没有执行注册于是series.map写对了也白搭。这个链路可以拆成四步加载脚本、拿到地理数据、调用registerMap、在 option 里引用同名地图。任何一步缺失表现都可能是空白或控制台警告。还有一种情况是重复注册。单页应用里多个组件都引入同一个地图文件每次引入都执行一次registerMap多数情况下不会立刻报错但地图实例多了以后会出现样式错乱、下钻返回异常排查起来像玄学。稳妥做法是把注册动作收口到一个模块里用Map记录已注册的地图名重复调用直接返回。注册名不要用文件路径也不要用显示标题固定成短标识例如country、region-01然后在业务数据里维护显示名和注册名的映射。2.3 最小可跑示例从本地 js 到第一个地图实例先写一个不依赖构建工具的最小页面把“加载、注册、初始化”跑通再谈工程化。下面的示例假设china.js已经放在./maps/china.js并且脚本执行后会暴露window.__CHINA_GEO__或直接完成注册。实际压缩包如果只暴露数据就把注册那一步打开。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / title地图最小示例/title script src./echarts.min.js/script !-- 先加载地图脚本确保注册动作在初始化之前完成 -- script src./maps/china.js/script /head body div idmap stylewidth: 900px; height: 600px;/div script // 兼容两种资源包已自动注册或只暴露地理数据 if (!echarts.getMap(country) window.__CHINA_GEO__) { echarts.registerMap(country, window.__CHINA_GEO__); } const chart echarts.init(document.getElementById(map)); const option { tooltip: { trigger: item }, series: [ { type: map, map: country, // 必须和 registerMap 的第一个参数一致 roam: true, label: { show: false }, itemStyle: { areaColor: #e8eef7, borderColor: #8fa3bf }, emphasis: { itemStyle: { areaColor: #f2c94c } }, data: [ // name 必须匹配地图数据里的区域名称这里用占位符 { name: REGION_NAME, value: 120 } ] } ] }; chart.setOption(option); window.addEventListener(resize, () chart.resize()); /script /body /html代码里的关键点有三个echarts.getMap(country)用来判断是否已经注册避免重复执行registerMap的第二个参数必须是地理数据对象不能传文件路径series.map的值必须和注册名完全一致。roam控制缩放和平移报表场景里建议打开但移动端要配合scaleLimit限制缩放范围。data里的name不是随便写的显示名它要和地理数据中的区域名称逐字匹配后缀、空格、编码差异都会导致数据落不到地图上。先用一条占位数据把地图画出来再替换成真实数据排查范围会小很多。3. 把 china.js 接进 ECharts数据绑定、视觉映射与交互配置地图能显示只是第一步真正影响可用性的是数据怎么绑、颜色怎么分、下钻怎么回来。ECharts 的 map 系列看起来配置项很多核心其实就三件事名称对齐、数值映射、状态管理。下面按数据格式、visualMap 分段、省市级下钻展开。3.1 数据格式对齐name、value 与 geoJSON 的对应关系地图数据绑定最常见的失败不是代码写错而是name对不上。ECharts 用名称去地理数据里找区域找不到就留空。很多压缩包里的地图脚本使用完整名称而业务接口返回的是简称、拼音、编码或带后缀的名称直接塞进去就会出现“有数据但地图全灰”。我一般先写一个覆盖率检查把地图数据里的名称集合取出来再和业务数据的name集合做交集覆盖率低于预期就先做映射不要急着调颜色。// 从已注册地图中读取地理数据检查业务数据名称覆盖率 function checkNameCoverage(mapName, rows) { const geo echarts.getMap(mapName); if (!geo || !geo.geoJSON) { console.warn(地图尚未注册或数据结构不兼容:, mapName); return { total: rows.length, matched: 0, missing: rows.map(r r.name) }; } const geoFeatures geo.geoJSON.features || []; const geoNames new Set( geoFeatures.map(f f.properties f.properties.name).filter(Boolean) ); const matched []; const missing []; rows.forEach(row { if (geoNames.has(row.name)) matched.push(row.name); else missing.push(row.name); }); return { total: rows.length, matched: matched.length, coverage: rows.length ? matched.length / rows.length : 0, missing }; } // 用法先注册地图再检查 const report checkNameCoverage(country, [ { name: REGION_NAME, value: 120 } ]); console.log(report);这段代码不依赖具体地名只依赖地图数据里的properties.name。echarts.getMap返回的对象结构在不同版本里可能有差异常见是geoJSON字段如果拿不到就退回读取原始地理数据变量。coverage低于 0.8 时不要硬上先做名称映射表。映射表不要写在业务组件里放到独立配置中字段至少包含rawName、mapName、note后面接口字段变化时只改一处。数值字段统一成value不要在 map 系列里塞自定义字段指望它自动识别需要额外信息就放extra在 tooltip 里取。3.2 视觉映射分段visualMap 参数怎么设才不糊visualMap负责把数值映射成颜色配置不好会出现两种极端所有区域一个色或者颜色跳变太硬看不出层次。连续型适合展示密度、总量分段型适合等级、区间。地图场景里我更常用分段型因为业务方看的是“高/中/低”而不是精确色阶。关键参数是min、max、pieces、inRange。min和max不要直接取数据最大值先用分位数或业务阈值定边界否则一个极端值会把其他区域压成同一颜色。const values [12, 35, 80, 120, 260, 410]; const sorted [...values].sort((a, b) a - b); const p50 sorted[Math.floor(sorted.length * 0.5)]; const p80 sorted[Math.floor(sorted.length * 0.8)]; const visualMap { type: piecewise, min: 0, max: sorted[sorted.length - 1], left: 20, bottom: 20, pieces: [ { lte: p50, label: 低 }, { gt: p50, lte: p80, label: 中 }, { gt: p80, label: 高 } ], inRange: { color: [#dbeafe, #60a5fa, #1d4ed8] }, outOfRange: { color: #f3f4f6 } }; const option { visualMap, series: [{ type: map, map: country, roam: true, data: [ { name: REGION_NAME, value: 120 } ] }] };pieces里的lte、gt是闭开区间边界值落在哪一段要提前确认避免两个分段都包含同一个值。inRange.color数量不要求和分段数完全一致ECharts 会插值但分段型最好用相近色系不要红绿蓝乱跳。outOfRange用来处理没有数据的区域给一个低饱和灰色比留白更清楚。left、bottom控制图例位置地图本身有缩放和平移时visualMap 不要放在容器边缘太近移动端容易挡住手势区域。数值为空时不要传0传null或直接不传该条数据否则“无数据”会被画成最低档。3.3 省市级下钻切换地图与事件监听的常见写法下钻的本质是换一张已注册的地图不是在一个地图实例上改数据。常见写法是监听click拿到区域名后加载对应省级脚本注册新地图名再setOption切换series.map。返回全国图时要注意两件事旧地图的 option 可能残留数据过滤条件也要复位。比较稳的做法是把“当前地图名、父级地图名、数据缓存”放在一个状态对象里切换时统一走一个函数不要在各个点击回调里散着写。const mapState { current: country, parent: null, registered: new Set([country]) }; async function loadMapScript(mapKey, scriptUrl) { if (mapState.registered.has(mapKey)) return; await new Promise((resolve, reject) { const script document.createElement(script); script.src scriptUrl; script.onload () { // 如果脚本没有自动注册这里需要手动 registerMap mapState.registered.add(mapKey); resolve(); }; script.onerror () reject(new Error(地图脚本加载失败: scriptUrl)); document.head.appendChild(script); }); } async function switchMap(chart, nextMapKey, scriptUrl) { await loadMapScript(nextMapKey, scriptUrl); mapState.parent mapState.current; mapState.current nextMapKey; chart.setOption({ series: [{ type: map, map: nextMapKey, roam: true, data: [] // 切换地图时先清空旧数据避免名称错配 }] }, { replaceMerge: [series] }); } // 点击下钻示例regionName 仅作占位实际从事件参数取 chart.on(click, async params { if (params.componentType ! series) return; const regionName params.name; const nextMapKey region-01; const scriptUrl ./maps/region-01.js; await switchMap(chart, nextMapKey, scriptUrl); }); // 返回全国图 function backToCountry(chart) { mapState.current country; mapState.parent null; chart.setOption({ series: [{ type: map, map: country, roam: true, data: [] }] }, { replaceMerge: [series] }); }replaceMerge: [series]很关键它能把旧 series 替换掉减少 option 合并带来的残留。loadMapScript里用Set记录已注册地图避免重复插入 script 标签。script.onload只能保证脚本执行完不能保证注册名就是你以为的那个所以加载后最好用echarts.getMap(nextMapKey)验一次拿不到就说明注册名或导出方式不匹配。下钻时先清空 data 再设新地图不要带着全国数据直接切省级图名称不匹配会产生一堆无意义警告。返回上级时同理数据要按当前层级重新取不要复用上一层的缓存。4. 资源包落地工程化按需加载、缓存与构建工具适配把地图放进真实项目后问题会从“能不能显示”变成“首屏会不会太重、打包后路径对不对、重复进入页面会不会越来越卡”。这类 js 地图文件通常体积不小全国图加多个省级图全量同步引入首屏很容易被拖慢。工程化处理的核心是只加载当前视图需要的地图加载过的做缓存离开页面时把实例和监听清理干净。4.1 只加载用到的地图文件动态 script 与模块化封装如果压缩包提供的是可直接执行的 js 文件动态script是最低成本的按需加载方式。把地图文件放静态目录用统一函数拼接路径加载成功后注册状态失败时给出可排查的错误信息。不要在每个组件里手写document.createElement(script)否则重复加载和错误处理会失控。封装时把“路径解析、去重、超时、失败重试”放在一层业务层只传地图标识。const mapLoader (() { const cache new Map(); // key: mapKey, value: Promise const base /static/maps/; function load(mapKey, fileName) { if (cache.has(mapKey)) return cache.get(mapKey); const promise new Promise((resolve, reject) { const script document.createElement(script); const timer setTimeout(() { script.remove(); reject(new Error(地图加载超时: mapKey)); }, 10000); script.src base fileName; script.async true; script.onload () { clearTimeout(timer); // 加载后验一次注册结果避免脚本执行了但注册名不对 if (!echarts.getMap(mapKey)) { reject(new Error(脚本已加载但地图未注册: mapKey)); return; } resolve(mapKey); }; script.onerror () { clearTimeout(timer); reject(new Error(地图脚本请求失败: script.src)); }; document.head.appendChild(script); }); cache.set(mapKey, promise); return promise; } return { load }; })(); // 业务侧只关心地图标识和文件名 mapLoader.load(region-01, region-01.js).then(() { // 这里再初始化或切换地图 });base要跟构建工具的静态资源目录一致不要写死成开发环境路径。cache存的是 Promise不是布尔值这样并发调用同一个地图时只会插入一个 script。超时时间按资源体积和网络环境调内网可以短一些公网静态资源可以放宽到 15 秒。加载后必须用echarts.getMap(mapKey)验证因为onload只代表文件执行完不代表注册成功。失败信息里带上mapKey和src线上排查时不用靠猜。4.2 构建工具里的静态资源处理public 目录与打包产物体积地图 js 不适合全部走模块打包。原因有两个一是很多压缩包里的脚本是立即执行式不是 ES module打包工具处理后会改变执行时机二是全量打进 bundle 会让首屏体积不可控。常见做法是把地图文件放public或静态资源目录运行时不经过打包器转换只通过 URL 加载。构建配置里要确认base和输出目录部署到子路径时尤其容易 404。// 以常见构建配置为例关键是静态目录和基础路径 export default { // 部署在子路径时这里要和网关前缀一致 base: /dashboard/, build: { outDir: dist, assetsDir: assets }, // public 下的文件会原样复制到输出目录 publicDir: public };假设地图文件放在public/static/maps/运行时路径就是/dashboard/static/maps/china.js不是/static/maps/china.js。开发环境往往没有子路径直接写/static/maps/能跑上线后 404这类坑很常见。判断方法打开浏览器网络面板看请求 URL 和实际部署路径差在哪一段。publicDir下的文件不要再 import否则可能被打包两次。地图文件命名不要带 hash因为动态加载的 URL 是手写的如果必须带 hash就用构建工具的资源清单生成映射不要靠字符串拼。4.3 多地图复用的缓存与销毁避免重复注册和内存泄漏单页应用里反复进入地图页面最容易出现的问题是实例没销毁、事件没解绑、地图脚本重复插入。ECharts 实例本身不会自动回收chart.dispose()要在组件卸载时调用window.addEventListener(resize)也要用同一个函数引用解绑。地图注册是全局的重复注册不一定报错但会让注册表越来越乱。我的习惯是把地图注册和图表实例分开管理注册只做一次实例按页面生命周期创建和销毁。function createMapChart(dom, mapKey) { const chart echarts.init(dom); const onResize () chart.resize(); window.addEventListener(resize, onResize); chart.setOption({ series: [{ type: map, map: mapKey, roam: true, data: [] }] }); return { chart, destroy() { window.removeEventListener(resize, onResize); chart.dispose(); } }; } // 页面卸载时调用 destroy不要只把 dom 清空 const holder createMapChart(document.getElementById(map), country); // holder.destroy();destroy里先解绑 resize再dispose顺序反了也不会立刻报错但习惯上先清外部监听。echarts.init的 dom 要有明确宽高容器隐藏时初始化会得到 0 尺寸后面再显示就可能是空白。地图脚本的缓存可以长期保留但图表实例不要缓存除非你确定多个页面共享同一个实例且能处理状态污染。重复注册的检查放在加载函数里用getMap判断不要用文件是否加载过来判断。5. 避坑与排查china.js 地图不显示的六类现场地图问题最难受的地方是“页面不报错”。控制台干净容器也在但地图就是不出来。下面这些现场是我在后台报表和离线演示里反复遇到的按“现象、原因、解决”拆开写。每条都尽量给出可验证的动作不要靠重启和清缓存碰运气。5.1 地图空白但控制台无报错先查 registerMap 时机现象series.map写了容器有宽高页面没有任何报错地图区域一片空白。原因通常是初始化早于地图注册。尤其是动态加载脚本时echarts.init已经执行registerMap还没完成ECharts 找不到地图名部分版本只给警告甚至不报错。解决把初始化放到地图加载 Promise 之后或者在setOption前强制检查echarts.getMap(mapKey)拿不到就等待并重试。不要用setTimeout猜时间用加载完成的回调。async function safeInit(dom, mapKey) { if (!echarts.getMap(mapKey)) { throw new Error(地图未注册检查脚本加载顺序: mapKey); } const chart echarts.init(dom); chart.setOption({ series: [{ type: map, map: mapKey, data: [] }] }); return chart; }这段检查放在业务初始化入口错误信息直接指出地图名。如果是脚本只导出数据没有注册就在加载后手动registerMap并确认第二个参数是地理数据对象。getMap返回空不一定是脚本没加载也可能是注册名写错先把注册名打印出来对照。5.2 名称对不上导致数据全灰编码与后缀的坑现象地图边界能显示但所有区域都是默认色tooltip 也没有数值。原因多数是数据name和地理数据名称不一致常见差异包括空格、全半角括号、后缀“市/省/区”、编码不一致。解决用 3.1 的覆盖率检查先定位缺失名称再做映射表。不要直接在原数据上replace掉后缀因为有些名称本身包含后缀差异粗暴替换会把本来能匹配的也改坏。映射表按“原始名到地图名”单向维护缺一条补一条。如果接口返回的是编码而不是名称就在前端维护编码到地图名的字典字典放独立文件别散在组件里。检查时把missing打印出来先人工看前十条通常能发现规律。覆盖率低但地图有颜色说明部分数据匹配上了问题在个别名称不要重写整个数据层。5.3 下钻后返回全国图错乱实例复用与 option 污染现象从全国图点进省级图正常返回全国图后数据错位、颜色不对或者上一次的 tooltip 还挂着。原因是setOption默认合并旧配置旧 series 的 data 和 visualMap 残留。解决切换地图时用replaceMerge: [series]并在切换前清空当前层数据如果 visualMap 也要按层级变化把它一起纳入替换或重新赋值。不要只改series.map就以为换了地图。返回上级时父级地图名要从状态对象取不要从当前点击参数反推。实例可以复用但状态要重置当前地图名、父级地图名、数据缓存键、缩放层级。roam打开的图表切换地图后缩放状态可能保留用户会看到上一层的缩放位置必要时调用chart.dispatchAction({ type: restore })或重新设置zoom。这类问题不报错但体验很差最好在切换函数里统一处理。5.4 打包后地图文件 404路径与 base 配置现象开发环境地图正常构建部署后空白网络面板里地图 js 请求 404。原因通常是动态加载路径写成了绝对根路径而应用部署在子路径下或者地图文件放在src里被当成模块处理构建后文件名带 hash手写 URL 对不上。解决地图文件放public静态目录加载路径基于构建工具的base拼接不要手写带 hash 的文件名。部署到子路径时base和网关前缀要一致。排查时先看请求 URL再看构建输出目录里文件实际位置。public/static/maps/china.js构建后应在dist/static/maps/china.js如果不在说明publicDir配错或被清理插件删了。CDN 场景还要确认跨域头和缓存策略地图脚本是普通 script 请求跨域配置不对会直接加载失败。不要用import引入立即执行式地图脚本执行时机和路径都容易出问题。5.5 移动端 tooltip 抖动与缩放卡顿参数与容器尺寸现象移动端手指缩放地图时卡顿tooltip 跟随抖动或者地图被图例挡住。原因通常是roam打开但没有限制缩放范围容器尺寸随布局变化但没有resizetooltip 在触摸事件里频繁重绘。解决设置scaleLimit限制最小和最大缩放容器用固定比例或 ResizeObserver 监听尺寸变化tooltip 在移动端减少formatter里的复杂计算。地图的label默认关闭移动端不要为了好看全量打开。const option { tooltip: { trigger: item, confine: true, // 限制在容器内减少溢出抖动 formatter: params { const value params.value null ? 无数据 : params.value; return params.name : value; } }, series: [{ type: map, map: country, roam: true, scaleLimit: { min: 0.8, max: 4 }, label: { show: false }, emphasis: { label: { show: true } } }] };confine: true能减少 tooltip 跑出容器但不是万能容器本身溢出隐藏也要配合。scaleLimit的min不要小于 0.5否则地图缩得太小点击区域难命中。formatter里不要做异步请求tooltip 触发频率高异步返回时鼠标可能已经移走。容器尺寸变化后调用chart.resize()不要只依赖窗口resize侧边栏展开收起也会改变容器宽度。5.6 重复进入页面后越来越卡注册表与监听器没清现象第一次进入地图页面正常来回切换几次后越来越卡甚至出现旧图表还响应点击。原因是图表实例没有disposeresize监听没有解绑地图脚本重复插入。解决组件卸载时统一销毁实例和解绑监听地图脚本用加载缓存去重不要在每次进入页面时重新registerMap。如果地图注册表已经乱了刷新页面能恢复但根因还在代码里。把创建和销毁成对写在一个模块里业务组件只调用create和destroy不要在外面零散echarts.init。检查方式在销毁函数里打印实例数量或者用浏览器内存面板看 detached DOM 是否持续增长。地图脚本的script标签加载成功后可以保留不需要移除但重复插入要避免。监听器用同一个函数引用解绑匿名函数解绑不掉这是血泪经验。6. 进阶技巧用一张校验表把地图资源管起来地图资源真正难的不是第一次跑通而是后续加文件、换数据、改部署路径时不出回归。我后来把上线前的检查做成一张表每次新增一个地图文件都按表过一遍。表里不写具体区域名只记录文件标识、注册名、数据名称覆盖率、加载方式和缓存键这样下钻和返回全国图时不用靠记忆。检查项判断方法不通过的处理注册名一致对比registerMap第一参数与series.map统一改成短标识业务层只引用标识数据覆盖率用checkNameCoverage跑一遍低于阈值先补映射表不调样式加载路径网络面板看实际请求 URL按base拼接放静态目录重复注册echarts.getMap预检查加载缓存去重注册收口销毁完整切页后看监听和实例dispose加解绑 resize// 上线前的最小校验注册、覆盖率、重复加载 async function validateMapResource(mapKey, rows) { if (!echarts.getMap(mapKey)) { throw new Error(地图未注册: mapKey); } const report checkNameCoverage(mapKey, rows); if (report.coverage 0.8) { console.warn(名称覆盖率偏低:, report); } return report; }这段校验不替代业务测试但能把最容易翻车的三类问题提前暴露地图没注册、名称大面积不匹配、覆盖率低到颜色失真。coverage阈值按业务容忍度调报表场景 0.8 起步下钻场景最好到 0.95。校验通过后再看 visualMap 和交互顺序不要反。从那以后我每次新增地图文件都先跑一遍覆盖率检查再谈样式和动效。希望帮到你。本文还有配套的精品资源点击获取
