簡介「echarts 世界地圖js」是一套面向前端開發(fā)者與數(shù)據(jù)可視化學(xué)習(xí)者的世界地圖示例資源重點(diǎn)解決在網(wǎng)頁中快速搭建可交互全球數(shù)據(jù)地圖的問題適合展示人口、GDP等跨國指標(biāo)或做區(qū)域數(shù)據(jù)對比的場景。壓縮包共77個(gè)文件以39個(gè)js腳本和38個(gè)json地圖/配置數(shù)據(jù)為主整體約3.42MB便于查看地圖初始化、配置項(xiàng)組織與數(shù)據(jù)接入方式。已有1639人學(xué)習(xí)下載說明其在實(shí)際項(xiàng)目與入門練習(xí)中具有一定參考價(jià)值。讀者可從中獲得世界地圖渲染的完整素材與代碼線索包括地圖數(shù)據(jù)、主題樣式、ECharts實(shí)例配置及交互效果參考能幫助理解tooltip、visualMap、縮放平移等常見能力的落地寫法資源中的腳本與數(shù)據(jù)文件可配合復(fù)現(xiàn)地圖加載、數(shù)值映射和視覺編碼流程并據(jù)此改造成自己的可視化頁面。1. 先別急著 setOptionecharts 世界地圖js 到底替你做了哪一步這份 echarts 世界地圖js 資源最常見的形態(tài)不是一張圖片而是一段把 GeoJSON 注冊進(jìn) ECharts 的腳本它提供區(qū)域邊界、區(qū)域名稱以及一個(gè)能被series.map引用的底圖。很多人以為拿到 js 就能直接出圖真正卡住的地方往往是注冊名、腳本順序和名稱匹配。它適合做離線大屏、內(nèi)部報(bào)表和區(qū)域指標(biāo)分布圖不適合街道級細(xì)節(jié)或?qū)崟r(shí)軌跡。先把它當(dāng)成一份“地圖字典”再談樣式和數(shù)據(jù)。2. 把 world.js 接進(jìn)頁面三種加載路徑與一份最小可運(yùn)行配置地圖資源接不進(jìn)去后面調(diào)色、加 tooltip、做鉆取都是空談。我一般先把問題拆成兩層world.js到底是“已經(jīng)幫你注冊好的腳本”還是“只暴露了一份 GeoJSON 的數(shù)據(jù)文件”。這兩種東西文件名可能都叫world.js但接法完全不同。先判斷結(jié)構(gòu)再選加載方式能少走很多彎路。2.1 先判斷 world.js 是“注冊腳本”還是“純數(shù)據(jù)”拿到文件后不要急著改代碼先用文本搜索看幾個(gè)關(guān)鍵詞registerMap、features、export default、window.。如果文件里出現(xiàn)echarts.registerMap(world, ...)說明它是注冊腳本頁面里只要保證echarts先加載、它后加載即可。如果只看到features數(shù)組和properties.name那它更像純 GeoJSON 包裝需要你自己調(diào)registerMap。如果是export default說明它走模塊導(dǎo)出script標(biāo)簽直接引入不一定能用。# 在資源目錄里快速看結(jié)構(gòu)不要全文件打印 grep -n registerMap\|features\|export default\|window\. world.js | head -20這段命令只做一件事把可能影響接入方式的關(guān)鍵詞找出來。registerMap出現(xiàn)優(yōu)先按注冊腳本處理features出現(xiàn)但沒有registerMap按純數(shù)據(jù)處理export default出現(xiàn)優(yōu)先走打包器。注意壓縮后的文件可能只有一行g(shù)rep的輸出會很長看到關(guān)鍵詞即可不要直接拿壓縮文件手改。注意world.js里的注冊名不一定是world以文件里registerMap的第一個(gè)參數(shù)為準(zhǔn)。后面所有map: world都要和它一致。2.2 瀏覽器直連script 順序與最小初始化最常見的落地方式是靜態(tài)頁面直接引。順序必須是 ECharts 在前、world.js在后否則world.js內(nèi)部調(diào)echarts.registerMap時(shí)會直接報(bào)錯(cuò)。容器必須有明確高度地圖不是文本父級高度為 0 時(shí)它不會自己撐開。下面這份最小示例只畫底圖不接業(yè)務(wù)數(shù)據(jù)用來確認(rèn)資源本身可用。div idworldMap stylewidth: 100%; height: 600px;/div script src./echarts.min.js/script script src./vendor/world.js/script script // 1. 先確認(rèn) world.js 是否已經(jīng)完成注冊 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. 最小配置先只畫底圖確認(rèn)資源可用 chart.setOption({ series: [{ type: map, map: world, // 必須和 registerMap 的第一個(gè)參數(shù)一致 roam: true }] }); // 4. 容器尺寸變化時(shí)重算避免大屏縮放后留白 window.addEventListener(resize, () chart.resize()); /script這段代碼的關(guān)鍵參數(shù)只有三個(gè)map是注冊名不是文件名roam控制拖拽和縮放先設(shè)true方便檢查地圖是否完整容器高度必須落在 CSS 上height: 600px只是示例實(shí)際按大屏格子給。echarts.getMap(world)用來判斷是否已經(jīng)注冊能避免重復(fù)注冊也能在控制臺快速確認(rèn)資源有沒有被加載。如果頁面用file://直接打開而world.js內(nèi)部又用fetch拉 JSON就會被瀏覽器的本地文件限制攔住。常見做法是起一個(gè)靜態(tài)服務(wù)# 在項(xiàng)目根目錄啟動靜態(tài)服務(wù)避免 fetch/JSON 被 file:// 限制 python3 -m http.server 8080 # 瀏覽器訪問 http://localhost:8080/index.html這不是地圖資源本身的要求而是前端加載本地 JSON 的通用習(xí)慣。world.js如果是純腳本注冊直接雙擊 HTML 有時(shí)也能出圖但只要涉及fetch、模塊導(dǎo)入或跨文件路徑靜態(tài)服務(wù)更穩(wěn)。2.3 打包器接入副作用導(dǎo)入與全局 shim項(xiàng)目走構(gòu)建工具時(shí)最容易翻車的不是地圖本身而是world.js里的執(zhí)行時(shí)機(jī)。很多世界地圖腳本默認(rèn)頁面里有一個(gè)全局echarts內(nèi)部直接寫echarts.registerMap(...)。打包后模塊作用域變了全局變量不一定存在地圖就會靜默消失。我的處理方式是先掛全局再副作用導(dǎo)入讓腳本按它原本的假設(shè)執(zhí)行。import * as echarts from echarts; // 有些 world.js 內(nèi)部直接調(diào)用全局 echarts.registerMap需要先掛到 window window.echarts echarts; // 副作用導(dǎo)入只執(zhí)行 world.js不接收返回值 await import(./vendor/world.js); // 如果 world.js 是純數(shù)據(jù)模塊走這一條 // 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是兼容層不是必須長期保留的寫法等確認(rèn)world.js是純數(shù)據(jù)模塊后應(yīng)該改成顯式registerMap減少全局污染。await import()適合在模塊頂層或異步初始化函數(shù)里用注意它要求運(yùn)行環(huán)境支持頂層 await如果不支持就把導(dǎo)入放到async function boot()里。另一個(gè)坑是構(gòu)建工具的 tree-shaking只在代碼里import ./vendor/world.js但不使用返回值時(shí)某些配置會把它當(dāng)成無副作用模塊搖掉。常見做法是在構(gòu)建配置里把該文件標(biāo)記為有副作用或者改成顯式導(dǎo)入 GeoJSON 后手動注冊。{ sideEffects: [ ./src/vendor/world.js ] }這段配置的意思是不要對這個(gè)文件做副作用裁剪。路徑按項(xiàng)目實(shí)際結(jié)構(gòu)調(diào)整不要照抄文件名。做完這一步再用echarts.getMap(world)在控制臺確認(rèn)一次能返回對象就說明注冊成功返回undefined繼續(xù)回到腳本順序和導(dǎo)入方式上查。3. 讓顏色說話visualMap、tooltip 與 nameMap 的聯(lián)動參數(shù)底圖能出來之后下一步才是業(yè)務(wù)表達(dá)。世界地圖的區(qū)域多、名稱長顏色映射和懸浮提示如果不克制很容易變成“能看但讀不懂”。我一般先把visualMap的范圍從數(shù)據(jù)里算出來再用tooltip補(bǔ)原始名稱和數(shù)值最后才調(diào)roam和布局。順序反過來調(diào)半天也不知道是數(shù)據(jù)沒對上還是樣式覆蓋了。3.1 visualMapmin/max 不是拍腦袋分段與連續(xù)怎么選visualMap最容易犯的錯(cuò)是手寫min: 0, max: 100。業(yè)務(wù)數(shù)據(jù)可能集中在 20 到 40 之間也可能有一個(gè)極端值把色帶拉滿手寫范圍會讓大部分區(qū)域顏色幾乎一樣。連續(xù)型適合看整體高低分布分段型適合匯報(bào)時(shí)明確分檔。區(qū)域數(shù)量多時(shí)色帶控制在 3 到 5 段不要做彩虹色。參數(shù)作用常見設(shè)置type連續(xù)或分段指標(biāo)跨度大用continuous匯報(bào)分檔用piecewisemin/max色彩映射范圍從數(shù)據(jù)算不要固定寫 0 到 100inRange.color區(qū)間內(nèi)顏色3 到 5 個(gè)顏色足夠outOfRange.color無數(shù)據(jù)或越界用淺灰避免和最低值同色seriesIndex綁定哪個(gè)系列多系列時(shí)必填單系列也建議寫calculable可拖拽手柄連續(xù)型可開分段型一般不開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); // 所有值相同時(shí)給一個(gè)最小跨度避免色帶退化 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 })) }] });這段代碼先過濾出有效數(shù)值再向下取整、向上取整避免色帶邊界出現(xiàn)小數(shù)。seriesIndex: 0把visualMap明確綁到第一個(gè)系列后面加折線圖或散點(diǎn)圖時(shí)不會誤傷。outOfRange給無數(shù)據(jù)區(qū)域一個(gè)淺灰和最低值顏色拉開如果兩者太接近讀者會誤以為“沒有數(shù)據(jù)”也是低值。null值不要直接轉(zhuǎn)成0否則缺數(shù)據(jù)區(qū)域會被染成最低檔。3.2 tooltip 與 nameMap顯示名和原始名分離世界地圖的區(qū)域名通常是英文或拼音直接懸浮出來對業(yè)務(wù)方不友好。nameMap可以做顯示名映射但它不是數(shù)據(jù)清洗工具它不會自動幫你把業(yè)務(wù)表里的簡稱、別名、大小寫差異全部對齊。穩(wěn)妥做法是數(shù)據(jù)側(cè)保留一套標(biāo)準(zhǔn)名顯示側(cè)用formatter或nameMap轉(zhuǎn)成可讀名稱兩邊不要混著改。const displayName new Map([ [Region-A, 區(qū)域 A], [Region-B, 區(qū)域 B] ]); chart.setOption({ tooltip: { trigger: item, confine: true, formatter: (p) { const label displayName.get(p.name) || p.name || 未知區(qū)域; const value p.value null || Number.isNaN(Number(p.value)) ? 無數(shù)據(jù) : Number(p.value).toFixed(1); return ${label}br/指標(biāo)值${value}; } }, series: [{ type: map, map: world, nameMap: { Region-A: 區(qū)域 A, Region-B: 區(qū)域 B }, data: rawData }] });confine: true讓提示框限制在圖表容器內(nèi)移動端和大屏邊緣區(qū)域不容易溢出。formatter里先取p.name再用displayName轉(zhuǎn)一次轉(zhuǎn)不到就回退原名稱p.value可能是null、空字符串或字符串?dāng)?shù)字所以用Number.isNaN(Number(p.value))兜底。nameMap只影響顯示層數(shù)據(jù)到底用原始名還是映射名建議先拿一個(gè)區(qū)域做單點(diǎn)驗(yàn)證數(shù)據(jù)里只放一條記錄能點(diǎn)亮再批量。不要一半用原始名、一半用顯示名最后排查起來非常費(fèi)勁。3.3 roam、layoutCenter 與 layoutSize視口和自適應(yīng)世界地圖的長寬比和容器不一定匹配默認(rèn)鋪滿時(shí)容易出現(xiàn)上下留白或左右裁切。layoutCenter和layoutSize控制地圖在容器里的布局中心與大小roam控制用戶交互zoom控制初始縮放。大屏項(xiàng)目里我一般把layoutSize設(shè)成95%左右留一點(diǎn)邊給圖例和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是拖拽和縮放的快捷寫法需要限制縮放范圍時(shí)改成對象或者單獨(dú)加scaleLimit。layoutCenter用百分比時(shí)相對于容器layoutSize可以寫百分比或像素aspectScale會改變地圖的縱向拉伸比例不要為了“填滿”把區(qū)域拉變形。center: [0, 0]只是初始中心點(diǎn)示例實(shí)際按業(yè)務(wù)關(guān)注區(qū)域調(diào)整。容器尺寸變化后必須調(diào)chart.resize()否則layoutSize還是按舊容器算的。提示先確認(rèn)echarts.getMap(world)有返回值再調(diào)樣式底圖沒注冊時(shí)調(diào)色和 tooltip 都不會生效。4. 數(shù)據(jù)落到區(qū)域上從名稱對賬到 series.data 對齊地圖資源接好、樣式調(diào)完真正決定圖表能不能用的是series.data里的name能不能和 GeoJSON 里的區(qū)域名對上。世界地圖尤其容易在這里翻車業(yè)務(wù)表用簡稱地圖數(shù)據(jù)用全稱業(yè)務(wù)表有空格地圖數(shù)據(jù)有連字符業(yè)務(wù)表是字符串?dāng)?shù)字地圖側(cè)按數(shù)值排序。我的習(xí)慣是先導(dǎo)出一份“標(biāo)準(zhǔn)名稱清單”再做別名映射最后統(tǒng)計(jì)未覆蓋區(qū)域和多余數(shù)據(jù)。4.1 從注冊數(shù)據(jù)里導(dǎo)出名稱清單不要靠猜。地圖注冊成功后直接通過echarts.getMap(world)拿到 GeoJSON把features里的properties.name全部列出來。這份清單就是后續(xù)數(shù)據(jù)對齊的基準(zhǔn)。不同資源的屬性名可能不叫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(區(qū)域數(shù)量:, regionNames.length); console.table(regionNames.slice(0, 20));geoJSON和geoJson做了一次兼容避免不同構(gòu)建產(chǎn)物屬性名不一致。features是區(qū)域數(shù)組properties.name是常見名稱字段如果樣本里沒有name而是NAME、name_en之類的字段就要在map里換字段名不要繼續(xù)硬套。regionNames既是排查工具也是后面生成對照表的源數(shù)據(jù)。4.2 數(shù)據(jù)清洗別名、空值、字符串?dāng)?shù)值業(yè)務(wù)數(shù)據(jù)進(jìn)來后先做一輪標(biāo)準(zhǔn)化去空格、別名映射、數(shù)值轉(zhuǎn)換、重復(fù)名稱處理。別名表不要寫得太寬寧可少映射也不要讓兩個(gè)不同區(qū)域誤合并。重復(fù)名稱要看業(yè)務(wù)含義如果是同一區(qū)域的多條記錄應(yīng)該先聚合如果只是重復(fù)導(dǎo)入保留一條并打日志。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; // 不在地圖標(biāo)準(zhǔn)名稱里的記錄先丟棄后面單獨(dú)統(tǒng)計(jì) if (!canonicalSet.has(name)) continue; // 同名記錄只保留第一條真實(shí)業(yè)務(wù)里應(yīng)先聚合再進(jìn)來 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只處理明確的別名比如空格、下劃線、縮寫不要用模糊匹配否則容易把相似名稱合并錯(cuò)。row.name ?? 兼容null和undefinedNumber(row.value)把字符串?dāng)?shù)字轉(zhuǎn)成數(shù)值Number.isFinite過濾掉空值和非法字符。重復(fù)名稱這里簡單保留第一條真實(shí)業(yè)務(wù)里更常見的是按名稱求和或取最新值策略要寫在數(shù)據(jù)清洗層不要留到圖表配置里。4.3 series.data 對齊與缺失值排查清洗完的數(shù)據(jù)不要直接塞進(jìn)series.data先做一次對賬哪些區(qū)域有數(shù)據(jù)、哪些區(qū)域缺失、哪些數(shù)據(jù)多余。缺失不一定是錯(cuò)誤可能業(yè)務(wù)上就沒有多余數(shù)據(jù)則通常意味著別名表漏了或者名稱格式不一致。把這兩個(gè)數(shù)字打出來排查效率會高很多。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(未覆蓋區(qū)域數(shù):, missing.length); console.log(多余數(shù)據(jù)數(shù):, extra.length); console.table(extra.slice(0, 10)); chart.setOption({ series: [{ type: map, map: world, data: cleanData, emphasis: { label: { show: true } } }] });missing用來決定無數(shù)據(jù)區(qū)域怎么顯示通常交給visualMap.outOfRange的淺灰extra用來反查別名表如果extra不為空但canonicalSet里沒有說明這些名稱根本不在底圖里。cleanData里只保留能匹配上的記錄避免無效數(shù)據(jù)干擾 tooltip。最后把cleanData傳給series.data不要再在setOption里做二次名稱轉(zhuǎn)換轉(zhuǎn)換邏輯越靠前越容易復(fù)用。5. 空白、不上色、縮放漂移五個(gè)高頻翻車點(diǎn)的排查順序地圖類問題最怕“看起來沒報(bào)錯(cuò)”?？刂婆_干凈頁面空白底圖出來了區(qū)域全灰拖拽兩下地圖跑偏。下面這五類是我在項(xiàng)目里反復(fù)遇到的按“先資源、再數(shù)據(jù)、后交互”的順序排查基本能覆蓋大多數(shù)場景。每條都按現(xiàn)象、原因、解決寫方便對照。5.1 地圖整塊空白先查腳本順序再查容器高度現(xiàn)象頁面有容器控制臺沒有明顯報(bào)錯(cuò)地圖不出現(xiàn)。原因通常有三個(gè)world.js在echarts.min.js之前加載內(nèi)部調(diào)registerMap時(shí)echarts還不存在容器高度是 0地圖畫布沒有尺寸注冊名和series.map不一致。解決順序是先看echarts.getMap(world)有沒有返回值再看容器getBoundingClientRect()的高度最后核對注冊名。console.log(地圖注冊信息:, echarts.getMap(world)); console.log(容器尺寸:, document.getElementById(worldMap).getBoundingClientRect());如果第一行是undefined問題在資源加載或注冊如果第一行有對象、第二行高度是 0問題在 CSS。父級用了height: 100%但祖先沒有高度也會導(dǎo)致容器高度為 0。大屏項(xiàng)目里常見的是格子用了絕對定位內(nèi)部圖表容器沒有顯式高度初始化時(shí)還是 0。5.2 只有底圖沒有顏色名稱和數(shù)值兩頭對不上現(xiàn)象地圖輪廓正常所有區(qū)域都是默認(rèn)色visualMap也顯示了但顏色不生效。原因多半是series.data的name和 GeoJSON 的區(qū)域名不一致或者value是字符串、空值、重復(fù)名稱導(dǎo)致匹配失敗。另一個(gè)常見原因是visualMap的min/max被手寫死數(shù)據(jù)全落在范圍外。解決方式是先打印第一條匹配記錄再打印未匹配數(shù)量。console.log(第一條數(shù)據(jù):, chart.getOption().series[0].data[0]); console.log(未匹配區(qū)域數(shù):, missing.length); console.log(數(shù)據(jù)值樣本:, cleanData.slice(0, 5));chart.getOption()拿到的是合并后的配置能確認(rèn)數(shù)據(jù)有沒有真正進(jìn)入系列。missing.length很大先查別名和大小寫missing.length很小但顏色仍不對查visualMap.min/max和outOfRange。如果所有值都是0min和max相等色帶會退化需要給一個(gè)最小跨度。5.3 縮放后漂移或重復(fù)渲染init 被調(diào)用兩次現(xiàn)象拖拽或縮放后地圖跳到左上角或者每次切換頁面回來地圖多一層、提示框重復(fù)出現(xiàn)。原因通常是同一個(gè) DOM 上重復(fù)echarts.init或者resize監(jiān)聽器重復(fù)綁定。單頁應(yīng)用里組件本文還有配套的精品資源點(diǎn)擊獲取