简介这是一份面向网页前端开发者与数据可视化初学者的ECharts世界地图资源包内含可直接运行的JS脚本与JSON地图数据能够快速搭建支持缩放、提示框、颜色映射的交互式世界地图。压缩包共77个文件其中39个JS文件涵盖ECharts核心库、macarons等主题配置38个JSON文件提供各国家与地区的GeoJSON地理边界数据整体仅3.42MB轻量易部署直接引入即可使用。已有1639人学习下载特别适合需要实现全球数据分布展示、人口统计或业务看板的场景也适合作为课程演示素材。资源整合了地图初始化、series地图系列配置、visualMap分段标色等关键实现逻辑并保留完整的js与json分类目录便于开发者直接嵌入项目或按需二次定制例如可调整颜色范围、开启缩放平移、绑定点击事件等。配合内置世界地图数据可大幅减少从零整理地理信息的成本适合数据新闻、国际业务可视化及教学演示等场景。1. echarts 世界地图 js 这件事先解决一个真问题很多做数据可视化的人第一次接触 echarts 世界地图 js 时拿到的是一堆 js 文件和数据但打开页面看到的却是空白 canvas。这不是 echarts 本身的问题而是世界地图这种特殊图表和普通折线图、柱状图有本质区别它依赖外部地图数据注册缺少注册这一步配置再花哨也渲染不出来。这个资源解决的正是从拿到文件到跑通「世界地图能显示、能缩放、能下钻」这段路。适合正在做全球业务看板、海外运营数据展示、或者想把销售数据落到世界地图上的前端开发者和数据分析师。本篇按实际拆包顺序讲清楚每个文件是干什么的、参数怎么调、以及我踩过的几个坑。2. 地图数据从哪来GeoJSON 格式和几个常见来源2.1 先搞懂 echarts 地图渲染的底层机制echarts 本身不内置任何地图数据。它只提供 geo 组件和 map 系列这两种渲染入口真正决定地图边界、区域形状、经纬度坐标的是外部传入的 GeoJSON 数据。GeoJSON 是一种基于 JSON 的地理数据交换格式里面用Polygon或MultiPolygon类型描述每个国家的边界坐标点集合用properties下的name字段标识这个区域叫什么名字。注册时 echarts 会把这个 GeoJSON 解析成内部可用的地理坐标系然后根据你传入的name和value对应关系去匹配data中的数据项。所以整条链路是得到 GeoJSON → 用echarts.registerMap()注册 → 在geo或map组件里指定这个注册名称 → 数据 series 按地区名关联渲染。任何一环断了地图都出不来。2.2 这份资源包含的常见文件形态拆开这类 echarts 世界地图 js 资源包通常会看到三种格式直接返回 js 变量的world.js、以 JSON 格式存储的world.json、以及附带properties字段的增强版 GeoJSON。大部分资源里的数据是基于公开地理数据源做了简化处理删掉了南极洲等不影响业务展示的区域边界精度在 110m 级别适合在 web 端展示放大到省级精度时会略显粗糙但那是数据精度问题不是代码问题。实际使用中以 JSON 文件方式引入最灵活// 以 fetch 方式拉取本地 JSON推荐放在静态资源目录 fetch(./map-data/world.json) .then(res res.json()) .then(worldJson { echarts.registerMap(world, worldJson); // 注册完成后续初始化图表时就能用 initWorldChart(); });fetch 方式适合现代浏览器和构建工具环境如果项目用了 webpack 或 vite可以直接把 JSON 作为模块导入做静态注册。JSON 文件比 js 变量文件更清晰数据类型一目了然后续做地图下钻替换数据也方便。2.3 registerMap 和 setOption 的顺序关系这是新手最容易翻车的地方。registerMap必须在setOption之前完成因为setOption解析 geo 配置时要立即读取已注册的地图数据。如果顺序反了echarts 会抛出一个Component geo: Map geo has not been imported之类的警告或者干脆不渲染。const chart echarts.init(document.getElementById(map-container)); // 先注册地图数据 fetch(./map-data/world.json) .then(res res.json()) .then(worldJson { echarts.registerMap(world, worldJson); // 再设置配置项 chart.setOption({ geo: { map: world, roam: true } }); });有的老项目里封装了统一的initChart方法会把setOption放在公共逻辑中。这时候地图数据可能还没加载完就被执行了所以要么把初始化 promise 化要么在数据加载完毕后再触发图表渲染。我一般会在加载地图数据这个环节加一层 promise 封装让整个初始化流程可控。2.4 地图数据源选择可以参考的几个点数据源的选取直接决定地图轮廓准确度和文件体积。完整版世界地图 GeoJSON 大约在 800KB 到 1.2MB 之间如果去掉 Antarctica、小型岛国仅保留主要国家文件可以压缩到 400KB 以下。加载速度和体积是取舍关系内网系统不必过分追求压缩公网页面建议做一次精简。这类 echarts 世界地图 js 资源大多会自带一份精简版直接用精简版文件做起跑点后续再根据业务需要切换完整版。提示拿到资源后先验证 JSON 格式合法性确认顶层是FeatureCollection结构并且每个 feature 的properties.name字段是你期望的中英文名称。3. 从零搭一个能跑的世界地图配置项逐行拆解3.1 geo 组件和 map 系列怎么选世界地图渲染有两种入口geo组件和map系列。geo 更适合做纯地图底图在上面叠加散点图、飞线图map 系列是完整图表类型自带 data 映射直接通过 series 传递数据就能上色。两者的视觉差异不大但联动机制不同。做地图色块展示时直接用 map 系列最省事option { tooltip: { trigger: item, formatter: function(params) { return params.name : (params.value || 暂无数据); } }, series: [{ type: map, map: world, roam: true, data: [ { name: China, value: 100 }, { name: United States, value: 80 }, { name: Russia, value: 60 } ] }] }; chart.setOption(option);type: mapmap: world是核心告诉图表用注册好的世界地图渲染。data数组里的name必须和 GeoJSON 里properties.name对应大小写敏感。roam: true允许用户缩放和拖拽这是世界地图和国内地图最大的交互差异点因为用户往往需要看某个小区域的细节。3.2 visualMap 让数据有颜色层级只显示地图边界没有意义要让数据呈现明暗或色阶差异就得配 visualMap。世界地图一般是分布散的数据用分段型piecewise比连续型continuous更直观。visualMap: { type: piecewise, pieces: [ { min: 100, label: 100 以上 }, { min: 50, max: 99, label: 50-99 }, { min: 10, max: 49, label: 10-49 }, { min: 0, max: 9, label: 0-9 } ], left: 20, bottom: 20, textStyle: { color: #333 } }分段的关键是pieces数组的顺序和边界值。echarts 的分段算法是逐个匹配所以要把数值范围从大到小排列否则可能前面的大区间把后面的小区间数据全部吞掉。之前遇到过一个问题{ min: 50, max: 99 }写在{ min: 100 }前面导致数值 120 的国家匹配到第一段而不是第二段颜色层级全乱。其实 echarts 会按数组顺序取第一个命中的区间所以顺序错了颜色就错了。3.3 label 和 tooltip 的细节处理世界地图上国家密度高、小国家多label 如果全部显示视觉上会糊成一团。我的处理方式是只显示有数据的国家标注。series: [{ type: map, map: world, label: { show: false, // 默认不显示 emphasis: { show: true, formatter: function(params) { return params.name; } } } }]鼠标悬停时显示国家名这是交互上的基本礼仪。tooltip 的 formatter 里可以拿到params.name和params.value拼成一句可读的话。注意有的数据里value为空时 tooltip 不要显示undefined用params.value || 暂无数据兜底。3.4 缩放和平移的边界设定地图上投放数据时不同的业务视角对缩放精度要求不同。默认roam: true可以自由缩放但如果没有设置scaleLimit用户能把地图放到失真。建议加上geo: { map: world, roam: true, scaleLimit: { min: 1, max: 5 }, center: [15, 10], // 初始中心点大概在欧洲非洲交界 zoom: 1.2 // 初始缩放级别 }center控制初始视野中心zoom控制初始缩放比例。如果业务主视角在亚洲可以把center调到亚洲经度范围附近比如[105, 35]。这是我平时做世界地图配置时最先调整的两个参数因为默认视野往往不符合具体业务场景用户第一眼看到的地图区域直接影响体验。3.5 map 和 geo 同时使用时的联动一个常见需求是既要世界地图作为底图背景又要在地图上叠加飞线或散点。这时候map系列和geo组件同时出场需要用geoIndex建立关联不然散点层级会错乱。option { geo: { map: world, roam: true, label: { show: false } }, series: [ { type: map, map: world, geoIndex: 0, // 关联 geo 组件 data: mapData }, { type: effectScatter, coordinateSystem: geo, // 散点基于 geo 坐标系统 data: pointData } ] };geoIndex: 0表示该 map 系列和第一个 geo 组件共用同一套地图数据和坐标系这样散点才能正确叠加在地图区域上。每次改这个我都觉得 echarts 的地图联动做得实在不算顺手这里是最容易出诡异 bug 的点。4. 让世界地图会说话数据格式、颜色映射和交互参数4.1 从接口数据到地图 data 的转换后端返回的数据多半是英文国家代码比如CN、US、RU而 GeoJSON 里的name字段通常是完整国家名。这就需要一个映射层。const codeMap { CN: China, US: United States, RU: Russia, // 更多映射... }; function formatMapData(rawList) { return rawList.map(item ({ name: codeMap[item.countryCode] || item.countryCode, value: item.totalValue })); }这个映射表是个烦人的体力活但绕不开。如果资源包里提供了带国家编码的 GeoJSON可以直接用编码做匹配。实际项目中我见过有人把映射表写 200 多个国家的也有只维护业务相关十几个国家的。建议按业务范围取舍别硬写全量维护成本不低。4.2 颜色分段和极端值处理世界地图上不同国家数据差异极大比如某个国家是 10000另一个是 1如果不做归一化极值会把其他国家的颜色都压到最低档。我的常见做法是用对数或者手动分段。visualMap: { type: piecewise, pieces: [ { min: 1000, color: #B71C1C }, { min: 100, max: 999, color: #E53935 }, { min: 10, max: 99, color: #EF9A9A }, { min: 0, max: 9, color: #FFEBEE } ] }手动分段的好处是颜色分布可控坏处是边界值需要根据数据分布来定不像 continuous 类型那样自动分。还有一招是在数据处理时取Math.log(value 1)再让 visualMap 自动分配这样能大幅压缩极值跨度视觉上更平衡。4.3 无数据国家的默认颜色业务里往往只有部分国家有数据。没有数据的时候地图默认用背景色itemStyle.areaColor默认也是这个色。很多时候我们要明确区分「有数据但值为 0」和「没数据」两种情况。itemStyle: { areaColor: #F5F5F5, // 无数据国家 borderColor: #AAA }, data: [ { name: China, value: 100 }, { name: United States, value: 80 } // 其他没列出的国家默认用 areaColor ]如果怕用户误解无数据国家是数据为 0可以在 visualMap 里加一段pieces: [ { value: 0, label: 数据为 0, color: #E0E0E0 }, // 其他分段... ]用value: 0显式标出数据为 0 的颜色这样没数据的国家不匹配这个条件用的还是areaColor。不过要注意series 的 data 里如果没写这个国家value就不存在value: 0的分段匹配不到它。4.4 世界地图上的点击交互与下钻点击国家后跳转到对应的国家详情页这是最常见的需求。世界地图的点击事件核心是监听chart.on(click)并拿到国家名。chart.on(click, function(params) { const countryName params.name; // 做跳转或联动 if (params.componentType series) { window.open(/detail?country encodeURIComponent(countryName)); } });注意params.componentType判断是必须的。如果 geo 组件和散点系列同时存在点击散点也会触发 click 事件但params.componentType是series可能干扰。我踩过这个坑后习惯性地加上判断避免同一个国家名因为点击在不同元素上触发两次操作。4.5 高亮选中国家保持选中态点击国家后要让这个国家保持高亮状态便于用户知道当前选中了哪里。用select状态相关配置selectedMode: single, itemStyle: { selected: { areaColor: #FFCC80 } }, select: { itemStyle: { areaColor: #FFCC80 }, label: { show: true } }selectedMode: single一次只能选中一个国家multiple允许点选多个。美中不足的地方是 echarts 的选中态在某些版本里点击空白区域不容易取消需要手动调用dispatchAction清空选中。chart.dispatchAction({ type: unselect, name: currentSelectedName });5. 世界地图避坑指南五个最常见的翻车现场5.1 地图一片灰或空白控制台没报错现象页面正常加载容器有宽高但地图区域就是空白或显示一片底色控制台也没有明显的 JS 报错。 原因registerMap没有执行成功或者执行时机晚于setOption。最简单的排查方式是在registerMap之后 console 一下注册名称。 解决确保 fetch 数据回来后再调用registerMap再执行setOption。如果用构建工具直接在模块顶部 import JSON再同步注册也可以。我一般会用一行代码验证console.log(echarts.getMap(world)); // 有值就是注册成功undefined 就是没注册5.2 全部国家名显示不出来现象tooltip 里显示undefinedlabel 也显示undefined。 原因GeoJSON 里的properties.name字段和 series 里data.name不一致或者根本没有 name 字段。 解决先打印 GeoJSON 前几个 feature 的 properties 字段看看name到底叫什么。这个资源如果 name 是中文字段那 data 就必须用中文名匹配。这是一个常见坑尤其是换了数据源之后经常发生数据名称不匹配的问题。// 验证 GeoJSON 里的国家名 fetch(./map-data/world.json) .then(res res.json()) .then(data { const names data.features.map(f f.properties.name); console.log(names.slice(0, 20)); });5.3 label 显示在海上位置漂移现象小国家的名称显示在海洋区域不在国家范围内。 原因GeoJSON 的properties里没有cp中心点字段或者中心点计算方式不正确。echarts 默认取多边形重心作为 label 位置但狭长或多岛国家重心会偏。 解决在 GeoJSON 的 properties 里手动补充cp坐标label 就会放在你指定的位置。这个工作量大通常只给业务重点国家加。5.4 地图看起来模糊尤其是放大后现象地图边界线发虚放大地图后轮廓不清晰。 原因GeoJSON 精度不足坐标点太少缩放后多边形边缘出现明显锯齿。 解决换高精度数据源或者接受当前精度。web 端展示时 110m 精度足够但如果要做大屏投屏或高清导出最好准备一份 50m 或 10m 精度的数据备用渲染时间会稍微增加。5.5 地图容器大小变化后地图变形现象页面窗口缩放时地图被拉伸变形或者跑到容器外面。 原因容器尺寸变化后图表没有自动 resize或者容器本身设置了固定宽高没有响应式。 解决在 window resize 事件里调用chart.resize()但这个方案性能一般建议用 ResizeObserver 监听容器变化。const resizeObserver new ResizeObserver(() { chart.resize(); }); resizeObserver.observe(document.getElementById(map-container));之前遇到过一个很隐蔽的问题容器宽度变成 0 或隐藏时chart.resize()会把地图的坐标系搞乱。后来我加了判断只有offsetWidth大于 0 才执行 resize世界地图投影才不会变形。6. 再进一步世界地图上叠加飞线效果世界地图做出来的效果不应只是色块填色叠加飞线是很多大屏项目的刚需。这个进阶效果依赖series里的lines类型配合effectScatter做起点终点闪烁。// 飞线数据格式[起点经度, 起点纬度, 终点经度, 终点纬度] const flyLines [ { coords: [[-122.4194, 37.7749], [121.4737, 31.2304]] }, { coords: [[-0.1276, 51.5072], [116.4074, 39.9042]] } ]; option { geo: { map: world, roam: true, itemStyle: { areaColor: #1a2a6c, borderColor: #fff } }, series: [ { type: lines, coordinateSystem: geo, data: flyLines, effect: { show: true, period: 4, trailLength: 0.4, symbol: arrow, symbolSize: 6 }, lineStyle: { color: #ffd700, width: 2, opacity: 0.6, curveness: 0.3 } }, { type: effectScatter, coordinateSystem: geo, data: [ { name: San Francisco, value: [-122.4194, 37.7749] }, { name: Shanghai, value: [121.4737, 31.2304] } ], symbolSize: 8 } ] }; chart.setOption(option);curveness: 0.3控制飞线弧度太大会显得诡异太小看起来像直线。trailLength是拖尾长度这个值调得越大会让飞线拖尾越明显视觉效果越炫。若想要发光效果可以再加一层普通 lines 系列做底宽一点、透明度低一点配合发光感就出来了。做一个稍微复杂一点的步骤先把目标城市经纬度整理成数组动态生成飞线数据不要硬编码。比如从后端拿到业务路径表map成这种 coords 格式这样整个效果就是数据驱动的。另外注意effectScatter的数据用的是[经度, 纬度]坐标而不是[name, value]的方式。这里踩过一个坑以为和 map 系列一样传国家名结果散点全部飞到地图中心。仔细看文档才发现 effectScatter 在 geo 坐标系下必须用经纬度数组。从那以后我每次做世界地图相关项目都会强制检查一遍数据格式飞线系列用经纬度、map 系列用国家名、tooltip 判断空值、resize 之前看容器宽度。这套已经成为我的习惯动作。希望对你有帮助也少踩几个我当年踩过的坑。本文还有配套的精品资源点击获取