★ FEATURED ARTICLE 简介「echarts 世界地图js」是一套面向前端开发者与数据可视化学习者的世界地图示例资源重点解决在网页中快速搭建可交互全球数据地图的问题适合展示人口、GDP等跨国指标或做区域数据对比的场景。压缩包共77个文件以39个js脚本和38个json地图/配置数据为主整体约3.42MB便于查看地图初始化、配置项组织与数据接入方式。已有1639人学习下载说明其在实际项目与入门练习中具有一定参考价值。读者可从中获得世界地图渲染的完整素材与代码线索包括地图数据、主题样式、ECharts实例配置及交互效果参考能帮助理解tooltip、visualMap、缩放平移等常见能力的落地写法资源中的脚本与数据文件可配合复现地图加载、数值映射和视觉编码流程并据此改造成自己的可视化页面。1. 先别急着 setOptionecharts 世界地图js 到底替你做了哪一步这份 echarts 世界地图js 资源最常见的形态不是一张图片而是一段把 GeoJSON 注册进 ECharts 的脚本它提供区域边界、区域名称以及一个能被series.map引用的底图。很多人以为拿到 js 就能直接出图真正卡住的地方往往是注册名、脚本顺序和名称匹配。它适合做离线大屏、内部报表和区域指标分布图不适合街道级细节或实时轨迹。先把它当成一份“地图字典”再谈样式和数据。2. 把 world.js 接进页面三种加载路径与一份最小可运行配置地图资源接不进去后面调色、加 tooltip、做钻取都是空谈。我一般先把问题拆成两层world.js到底是“已经帮你注册好的脚本”还是“只暴露了一份 GeoJSON 的数据文件”。这两种东西文件名可能都叫world.js但接法完全不同。先判断结构再选加载方式能少走很多弯路。2.1 先判断 world.js 是“注册脚本”还是“纯数据”拿到文件后不要急着改代码先用文本搜索看几个关键词registerMap、features、export default、window.。如果文件里出现echarts.registerMap(world, ...)说明它是注册脚本页面里只要保证echarts先加载、它后加载即可。如果只看到features数组和properties.name那它更像纯 GeoJSON 包装需要你自己调registerMap。如果是export default说明它走模块导出script标签直接引入不一定能用。# 在资源目录里快速看结构不要全文件打印 grep -n registerMap\|features\|export default\|window\. world.js | head -20这段命令只做一件事把可能影响接入方式的关键词找出来。registerMap出现优先按注册脚本处理features出现但没有registerMap按纯数据处理export default出现优先走打包器。注意压缩后的文件可能只有一行grep的输出会很长看到关键词即可不要直接拿压缩文件手改。注意world.js里的注册名不一定是world以文件里registerMap的第一个参数为准。后面所有map: world都要和它一致。2.2 浏览器直连script 顺序与最小初始化最常见的落地方式是静态页面直接引。顺序必须是 ECharts 在前、world.js在后否则world.js内部调echarts.registerMap时会直接报错。容器必须有明确高度地图不是文本父级高度为 0 时它不会自己撑开。下面这份最小示例只画底图不接业务数据用来确认资源本身可用。div idworldMap stylewidth: 100%; height: 600px;/div script src./echarts.min.js/script script src./vendor/world.js/script script // 1. 先确认 world.js 是否已经完成注册 if (!echarts.getMap(world)) { const geo window.world || window.WORLD_GEOJSON || window.worldGeoJson; if (!geo) { throw new Error(world.js 未注册地图也未暴露 GeoJSON 全局变量); } echarts.registerMap(world, geo); } // 2. 容器必须有明确高度否则地图高度为 0 const dom document.getElementById(worldMap); const chart echarts.init(dom); // 3. 最小配置先只画底图确认资源可用 chart.setOption({ series: [{ type: map, map: world, // 必须和 registerMap 的第一个参数一致 roam: true }] }); // 4. 容器尺寸变化时重算避免大屏缩放后留白 window.addEventListener(resize, () chart.resize()); /script这段代码的关键参数只有三个map是注册名不是文件名roam控制拖拽和缩放先设true方便检查地图是否完整容器高度必须落在 CSS 上height: 600px只是示例实际按大屏格子给。echarts.getMap(world)用来判断是否已经注册能避免重复注册也能在控制台快速确认资源有没有被加载。如果页面用file://直接打开而world.js内部又用fetch拉 JSON就会被浏览器的本地文件限制拦住。常见做法是起一个静态服务# 在项目根目录启动静态服务避免 fetch/JSON 被 file:// 限制 python3 -m http.server 8080 # 浏览器访问 http://localhost:8080/index.html这不是地图资源本身的要求而是前端加载本地 JSON 的通用习惯。world.js如果是纯脚本注册直接双击 HTML 有时也能出图但只要涉及fetch、模块导入或跨文件路径静态服务更稳。2.3 打包器接入副作用导入与全局 shim项目走构建工具时最容易翻车的不是地图本身而是world.js里的执行时机。很多世界地图脚本默认页面里有一个全局echarts内部直接写echarts.registerMap(...)。打包后模块作用域变了全局变量不一定存在地图就会静默消失。我的处理方式是先挂全局再副作用导入让脚本按它原本的假设执行。import * as echarts from echarts; // 有些 world.js 内部直接调用全局 echarts.registerMap需要先挂到 window window.echarts echarts; // 副作用导入只执行 world.js不接收返回值 await import(./vendor/world.js); // 如果 world.js 是纯数据模块走这一条 // import worldGeo from ./vendor/world.js; // echarts.registerMap(world, worldGeo); const chart echarts.init(document.getElementById(worldMap)); chart.setOption({ series: [{ type: map, map: world, roam: true }] });window.echarts echarts是兼容层不是必须长期保留的写法等确认world.js是纯数据模块后应该改成显式registerMap减少全局污染。await import()适合在模块顶层或异步初始化函数里用注意它要求运行环境支持顶层 await如果不支持就把导入放到async function boot()里。另一个坑是构建工具的 tree-shaking只在代码里import ./vendor/world.js但不使用返回值时某些配置会把它当成无副作用模块摇掉。常见做法是在构建配置里把该文件标记为有副作用或者改成显式导入 GeoJSON 后手动注册。{ sideEffects: [ ./src/vendor/world.js ] }这段配置的意思是不要对这个文件做副作用裁剪。路径按项目实际结构调整不要照抄文件名。做完这一步再用echarts.getMap(world)在控制台确认一次能返回对象就说明注册成功返回undefined继续回到脚本顺序和导入方式上查。3. 让颜色说话visualMap、tooltip 与 nameMap 的联动参数底图能出来之后下一步才是业务表达。世界地图的区域多、名称长颜色映射和悬浮提示如果不克制很容易变成“能看但读不懂”。我一般先把visualMap的范围从数据里算出来再用tooltip补原始名称和数值最后才调roam和布局。顺序反过来调半天也不知道是数据没对上还是样式覆盖了。3.1 visualMapmin/max 不是拍脑袋分段与连续怎么选visualMap最容易犯的错是手写min: 0, max: 100。业务数据可能集中在 20 到 40 之间也可能有一个极端值把色带拉满手写范围会让大部分区域颜色几乎一样。连续型适合看整体高低分布分段型适合汇报时明确分档。区域数量多时色带控制在 3 到 5 段不要做彩虹色。参数作用常见设置type连续或分段指标跨度大用continuous汇报分档用piecewisemin/max色彩映射范围从数据算不要固定写 0 到 100inRange.color区间内颜色3 到 5 个颜色足够outOfRange.color无数据或越界用浅灰避免和最低值同色seriesIndex绑定哪个系列多系列时必填单系列也建议写calculable可拖拽手柄连续型可开分段型一般不开const rawData [ { name: Region-A, value: 12 }, { name: Region-B, value: 87 }, { name: Region-C, value: null } ]; const nums rawData .map(d Number(d.value)) .filter(Number.isFinite); let min Math.min(...nums); let max Math.max(...nums); // 所有值相同时给一个最小跨度避免色带退化 if (min max) max min 1; chart.setOption({ tooltip: { trigger: item }, visualMap: { type: continuous, min: Math.floor(min), max: Math.ceil(max), calculable: true, seriesIndex: 0, inRange: { color: [#dbeafe, #60a5fa, #1e3a8a] }, outOfRange: { color: #e5e7eb }, text: [高, 低], left: 16, bottom: 16 }, series: [{ type: map, map: world, data: rawData.map(d ({ name: d.name, value: Number.isFinite(Number(d.value)) ? Number(d.value) : null })) }] });这段代码先过滤出有效数值再向下取整、向上取整避免色带边界出现小数。seriesIndex: 0把visualMap明确绑到第一个系列后面加折线图或散点图时不会误伤。outOfRange给无数据区域一个浅灰和最低值颜色拉开如果两者太接近读者会误以为“没有数据”也是低值。null值不要直接转成0否则缺数据区域会被染成最低档。3.2 tooltip 与 nameMap显示名和原始名分离世界地图的区域名通常是英文或拼音直接悬浮出来对业务方不友好。nameMap可以做显示名映射但它不是数据清洗工具它不会自动帮你把业务表里的简称、别名、大小写差异全部对齐。稳妥做法是数据侧保留一套标准名显示侧用formatter或nameMap转成可读名称两边不要混着改。const displayName new Map([ [Region-A, 区域 A], [Region-B, 区域 B] ]); chart.setOption({ tooltip: { trigger: item, confine: true, formatter: (p) { const label displayName.get(p.name) || p.name || 未知区域; const value p.value null || Number.isNaN(Number(p.value)) ? 无数据 : Number(p.value).toFixed(1); return ${label}br/指标值${value}; } }, series: [{ type: map, map: world, nameMap: { Region-A: 区域 A, Region-B: 区域 B }, data: rawData }] });confine: true让提示框限制在图表容器内移动端和大屏边缘区域不容易溢出。formatter里先取p.name再用displayName转一次转不到就回退原名称p.value可能是null、空字符串或字符串数字所以用Number.isNaN(Number(p.value))兜底。nameMap只影响显示层数据到底用原始名还是映射名建议先拿一个区域做单点验证数据里只放一条记录能点亮再批量。不要一半用原始名、一半用显示名最后排查起来非常费劲。3.3 roam、layoutCenter 与 layoutSize视口和自适应世界地图的长宽比和容器不一定匹配默认铺满时容易出现上下留白或左右裁切。layoutCenter和layoutSize控制地图在容器里的布局中心与大小roam控制用户交互zoom控制初始缩放。大屏项目里我一般把layoutSize设成95%左右留一点边给图例和visualMap不要顶满。chart.setOption({ series: [{ type: map, map: world, roam: true, zoom: 1.15, center: [0, 0], layoutCenter: [50%, 50%], layoutSize: 95%, aspectScale: 0.85, scaleLimit: { min: 1, max: 8 }, emphasis: { label: { show: true } } }] });roam: true是拖拽和缩放的快捷写法需要限制缩放范围时改成对象或者单独加scaleLimit。layoutCenter用百分比时相对于容器layoutSize可以写百分比或像素aspectScale会改变地图的纵向拉伸比例不要为了“填满”把区域拉变形。center: [0, 0]只是初始中心点示例实际按业务关注区域调整。容器尺寸变化后必须调chart.resize()否则layoutSize还是按旧容器算的。提示先确认echarts.getMap(world)有返回值再调样式底图没注册时调色和 tooltip 都不会生效。4. 数据落到区域上从名称对账到 series.data 对齐地图资源接好、样式调完真正决定图表能不能用的是series.data里的name能不能和 GeoJSON 里的区域名对上。世界地图尤其容易在这里翻车业务表用简称地图数据用全称业务表有空格地图数据有连字符业务表是字符串数字地图侧按数值排序。我的习惯是先导出一份“标准名称清单”再做别名映射最后统计未覆盖区域和多余数据。4.1 从注册数据里导出名称清单不要靠猜。地图注册成功后直接通过echarts.getMap(world)拿到 GeoJSON把features里的properties.name全部列出来。这份清单就是后续数据对齐的基准。不同资源的属性名可能不叫name所以先打印一条样本看看。const mapInfo echarts.getMap(world); if (!mapInfo) throw new Error(地图未注册); const geo mapInfo.geoJSON || mapInfo.geoJson; const firstFeature geo.features[0]; console.log(第一条属性样本:, firstFeature.properties); const regionNames geo.features.map(f f.properties.name); console.log(区域数量:, regionNames.length); console.table(regionNames.slice(0, 20));geoJSON和geoJson做了一次兼容避免不同构建产物属性名不一致。features是区域数组properties.name是常见名称字段如果样本里没有name而是NAME、name_en之类的字段就要在map里换字段名不要继续硬套。regionNames既是排查工具也是后面生成对照表的源数据。4.2 数据清洗别名、空值、字符串数值业务数据进来后先做一轮标准化去空格、别名映射、数值转换、重复名称处理。别名表不要写得太宽宁可少映射也不要让两个不同区域误合并。重复名称要看业务含义如果是同一区域的多条记录应该先聚合如果只是重复导入保留一条并打日志。function buildCanonicalSet(names) { return new Set(names.map(n String(n).trim())); } function normalizeRows(rows, canonicalSet) { const alias new Map([ [Region A, Region-A], [Region_B, Region-B] ]); const seen new Set(); const clean []; for (const row of rows) { let name String(row.name ?? ).trim(); name alias.get(name) || name; // 不在地图标准名称里的记录先丢弃后面单独统计 if (!canonicalSet.has(name)) continue; // 同名记录只保留第一条真实业务里应先聚合再进来 if (seen.has(name)) continue; const value Number(row.value); if (!Number.isFinite(value)) continue; seen.add(name); clean.push({ name, value }); } return clean; }buildCanonicalSet把地图名称做成集合查询成本低。alias只处理明确的别名比如空格、下划线、缩写不要用模糊匹配否则容易把相似名称合并错。row.name ?? 兼容null和undefinedNumber(row.value)把字符串数字转成数值Number.isFinite过滤掉空值和非法字符。重复名称这里简单保留第一条真实业务里更常见的是按名称求和或取最新值策略要写在数据清洗层不要留到图表配置里。4.3 series.data 对齐与缺失值排查清洗完的数据不要直接塞进series.data先做一次对账哪些区域有数据、哪些区域缺失、哪些数据多余。缺失不一定是错误可能业务上就没有多余数据则通常意味着别名表漏了或者名称格式不一致。把这两个数字打出来排查效率会高很多。const canonicalSet buildCanonicalSet(regionNames); const cleanData normalizeRows(rawRows, canonicalSet); const cleanSet new Set(cleanData.map(d d.name)); const missing regionNames.filter(n !cleanSet.has(n)); const extra cleanData.filter(d !canonicalSet.has(d.name)); console.log(未覆盖区域数:, missing.length); console.log(多余数据数:, extra.length); console.table(extra.slice(0, 10)); chart.setOption({ series: [{ type: map, map: world, data: cleanData, emphasis: { label: { show: true } } }] });missing用来决定无数据区域怎么显示通常交给visualMap.outOfRange的浅灰extra用来反查别名表如果extra不为空但canonicalSet里没有说明这些名称根本不在底图里。cleanData里只保留能匹配上的记录避免无效数据干扰 tooltip。最后把cleanData传给series.data不要再在setOption里做二次名称转换转换逻辑越靠前越容易复用。5. 空白、不上色、缩放漂移五个高频翻车点的排查顺序地图类问题最怕“看起来没报错”。控制台干净页面空白底图出来了区域全灰拖拽两下地图跑偏。下面这五类是我在项目里反复遇到的按“先资源、再数据、后交互”的顺序排查基本能覆盖大多数场景。每条都按现象、原因、解决写方便对照。5.1 地图整块空白先查脚本顺序再查容器高度现象页面有容器控制台没有明显报错地图不出现。原因通常有三个world.js在echarts.min.js之前加载内部调registerMap时echarts还不存在容器高度是 0地图画布没有尺寸注册名和series.map不一致。解决顺序是先看echarts.getMap(world)有没有返回值再看容器getBoundingClientRect()的高度最后核对注册名。console.log(地图注册信息:, echarts.getMap(world)); console.log(容器尺寸:, document.getElementById(worldMap).getBoundingClientRect());如果第一行是undefined问题在资源加载或注册如果第一行有对象、第二行高度是 0问题在 CSS。父级用了height: 100%但祖先没有高度也会导致容器高度为 0。大屏项目里常见的是格子用了绝对定位内部图表容器没有显式高度初始化时还是 0。5.2 只有底图没有颜色名称和数值两头对不上现象地图轮廓正常所有区域都是默认色visualMap也显示了但颜色不生效。原因多半是series.data的name和 GeoJSON 的区域名不一致或者value是字符串、空值、重复名称导致匹配失败。另一个常见原因是visualMap的min/max被手写死数据全落在范围外。解决方式是先打印第一条匹配记录再打印未匹配数量。console.log(第一条数据:, chart.getOption().series[0].data[0]); console.log(未匹配区域数:, missing.length); console.log(数据值样本:, cleanData.slice(0, 5));chart.getOption()拿到的是合并后的配置能确认数据有没有真正进入系列。missing.length很大先查别名和大小写missing.length很小但颜色仍不对查visualMap.min/max和outOfRange。如果所有值都是0min和max相等色带会退化需要给一个最小跨度。5.3 缩放后漂移或重复渲染init 被调用两次现象拖拽或缩放后地图跳到左上角或者每次切换页面回来地图多一层、提示框重复出现。原因通常是同一个 DOM 上重复echarts.init或者resize监听器重复绑定。单页应用里组件本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
