簡介這是一套基于 Vue 與 ECharts 的可視化地圖實戰(zhàn)源碼面向需要在大屏或后臺系統(tǒng)中實現(xiàn)地理數(shù)據(jù)展示的前端開發(fā)者覆蓋從入門到進(jìn)階的常見地圖需求。資源圍繞中國地圖展開支持 3D 地圖渲染、省—市—縣三級下鉆與回鉆、南海諸島小窗化顯示并附帶點位飛線圖與點位名稱彈窗輪播效果同時整理了開發(fā)中容易遇到的常見問題解壓后即可直接運行調(diào)試。壓縮包共 28 個文件約 494KB以 9 個 vue 組件、7 個 js 邏輯文件、3 個 json 配置為主另含 png、jpg 圖片素材、ttf 字體、css 樣式與 html 入口目錄按 components、views、router、util 等模塊劃分結(jié)構(gòu)清晰便于二次開發(fā)。目前已有 5554 人學(xué)習(xí)下載適合希望快速掌握 ECharts 地圖下鉆、飛線動畫與 3D 效果實現(xiàn)思路的前端工程師參考借鑒。1. 從一張“點不動”的地圖說起這套 Vue ECharts 方案到底能扛什么活去年幫一個做園區(qū)管理的朋友看大屏需求很樸素一張中國地圖點省份進(jìn)去看城市點城市進(jìn)去看區(qū)縣再點一下能退回來順便把幾個重點項目的點位用飛線連起來鼠標(biāo)懸停彈個名字最好還能自動輪播。他找的外包第一版交付后地圖是畫出來了但點進(jìn)去就回不來南海諸島那塊要么缺一塊要么糊成一團(tuán)飛線一動整個頁面卡成幻燈片。這不是 ECharts 不行是下鉆和回鉆的狀態(tài)管理沒做對3D 和 2D 混用的時候坐標(biāo)系沒統(tǒng)一。這套資源解決的就是這類“看著簡單、做起來全是細(xì)節(jié)”的地圖可視化需求。核心是 Vue 做組件化封裝ECharts 負(fù)責(zé)渲染覆蓋中國地圖、3D 地圖、省/市/縣三級下鉆與回鉆、南海諸島小窗化顯示、點位飛線圖、點位名稱彈窗輪播這幾個高頻場景。適合誰適合手里有大屏項目、需要快速搭出可交互地圖、又不想從零啃 GeoJSON 和坐標(biāo)系轉(zhuǎn)換的前端。下面我按“能跑起來 → 能改參數(shù) → 能避坑”的順序拆一遍。2. 環(huán)境搭起來Vue 項目里把 ECharts 和地圖數(shù)據(jù)接上2.1 依賴選型echarts 5 與 vue-echarts 的取舍ECharts 5 對地圖系列的支持比 4 穩(wěn)定不少尤其是geo組件和series-map的聯(lián)動。Vue 這邊有兩種接法直接用echarts.init手動管理實例或者用vue-echarts封裝組件。我一般推薦手動管理原因很實際——下鉆場景里地圖實例需要頻繁setOption和dispose封裝組件反而多一層響應(yīng)式干擾容易出現(xiàn)“數(shù)據(jù)變了圖沒變”的玄學(xué)問題。安裝依賴就三條命令注意echarts和地圖數(shù)據(jù)是分開的地圖 JSON 不打包進(jìn)庫npm install echarts5 --save npm install vue3 --save # 地圖 GeoJSON 數(shù)據(jù)單獨放 public 或 assets不要塞進(jìn) node_modules邏輯說明ECharts 本體只提供渲染引擎中國及各省市的邊界數(shù)據(jù)需要單獨引入。參數(shù)上echarts5是當(dāng)前下鉆方案兼容性最好的大版本4.x 在registerMap重復(fù)注冊時會有內(nèi)存泄漏。地圖數(shù)據(jù)建議放public/map/下按china.json、province_110000.json這種命名方便按 adcode 動態(tài)加載。2.2 地圖數(shù)據(jù)注冊registerMap 的正確調(diào)用姿勢很多人第一次做下鉆卡在“點了省份沒反應(yīng)”八成是registerMap沒調(diào)對。ECharts 注冊地圖是全局的同名地圖重復(fù)注冊會覆蓋但如果你在組件銷毀時沒清理切換路由后再進(jìn)來就會拿到舊數(shù)據(jù)。import * as echarts from echarts import chinaJson from /assets/map/china.json // 注冊中國地圖china 是后續(xù) series.map 引用的名字 echarts.registerMap(china, chinaJson) // 下鉆時動態(tài)注冊省份adcode 用國家行政區(qū)劃代碼 async function registerProvinceMap(adcode) { const res await fetch(/map/province_${adcode}.json) const geoJson await res.json() // 關(guān)鍵注冊名用 adcode避免和 china 沖突 echarts.registerMap(province_${adcode}, geoJson) return province_${adcode} }邏輯說明registerMap第一個參數(shù)是地圖名第二個是 GeoJSON 對象。參數(shù)上adcode用六位行政區(qū)劃代碼比如北京是 110000這樣省市縣三級可以統(tǒng)一用代碼做 key回鉆時只需把地圖名切回上一級。注意 fetch 路徑要和你實際存放目錄一致Vue CLI 項目放public下用絕對路徑Vite 項目放public同樣用/開頭。2.3 初始化一個最小可用的中國地圖先把最基礎(chǔ)的渲染跑通再疊加下鉆和飛線。下面這段是mounted里的初始化骨架const chart echarts.init(document.getElementById(map-container)) const option { geo: { map: china, roam: true, // 允許縮放拖拽 zoom: 1.2, // 初始縮放1.2 能看清南海小窗 label: { show: false }, itemStyle: { areaColor: #0b1c3a, borderColor: #2a5caa } }, series: [] } chart.setOption(option)邏輯說明geo組件負(fù)責(zé)底圖series后續(xù)掛飛線和散點。參數(shù)上roam: true開啟交互zoom控制初始視野做南海小窗時這個值要配合layoutCenter和layoutSize調(diào)。注意容器必須有明確寬高否則init出來是 0×0 的白板這是新手最常見的翻車點。3. 三級下鉆與回鉆狀態(tài)機(jī)比遞歸更靠譜3.1 下鉆的本質(zhì)換地圖 換數(shù)據(jù) 記路徑下鉆不是“把地圖放大”而是把當(dāng)前地圖替換成下一級地圖同時把 series 里的數(shù)據(jù)換成下一級的點位。很多人寫成遞歸調(diào)用結(jié)果回鉆時找不到上一級。正確做法是維護(hù)一個levelStack數(shù)組每次下鉆 push 當(dāng)前層級回鉆 pop。const levelStack [] // 記錄路徑[china, province_110000, ...] async function drillDown(adcode, level) { // 記錄當(dāng)前層級回鉆時用 levelStack.push({ map: currentMap, adcode: currentAdcode }) const mapName await registerProvinceMap(adcode) currentMap mapName currentAdcode adcode chart.setOption({ geo: { map: mapName, zoom: 1.1 }, series: buildSeries(level, adcode) // 按層級重建飛線和散點 }) } function drillUp() { if (levelStack.length 0) return // 已經(jīng)在頂層不回 const prev levelStack.pop() currentMap prev.map currentAdcode prev.adcode chart.setOption({ geo: { map: prev.map, zoom: prev.map china ? 1.2 : 1.1 }, series: buildSeries(prev.level, prev.adcode) }) }邏輯說明levelStack是回鉆的“后悔藥”每次下鉆前把當(dāng)前狀態(tài)存進(jìn)去。參數(shù)上level用來區(qū)分省、市、縣決定 series 里散點用哪套坐標(biāo)。注意drillUp里要判斷?？辗駝t在頂層點回鉆會報錯。常見做法是給地圖容器綁chart.on(click, params ...)從params.name反查 adcode 再觸發(fā)下鉆。3.2 回鉆的觸發(fā)方式雙擊、按鈕還是右鍵回鉆交互有三種常見設(shè)計雙擊地圖空白處、右上角放返回按鈕、右鍵菜單。大屏項目我建議用返回按鈕因為雙擊在觸屏上容易誤觸右鍵在 kiosk 模式可能被禁用。按鈕方案最簡單button classback-btn clickdrillUp v-showlevelStack.length 0 返回上一級 /button邏輯說明v-show比v-if好因為按鈕頻繁切換v-show只改 display 不銷毀 DOM。參數(shù)上levelStack.length 0控制顯隱頂層不顯示。注意按鈕要絕對定位在地圖容器上層z-index 給夠否則被 canvas 蓋住點不到。3.3 南海諸島小窗化layoutCenter 與 boundingCoords 的配合南海諸島默認(rèn)在中國地圖右下角但 ECharts 的geo組件不會自動把它做成獨立小窗。常見做法是用layoutCenter和layoutSize把主圖縮小再單獨放一個geo實例渲染南海區(qū)域。更省事的方案是直接用帶南海小窗的 GeoJSON然后在 option 里調(diào)boundingCoords。geo: { map: china, layoutCenter: [50%, 50%], layoutSize: 95%, // 南海小窗通過 GeoJSON 自帶的多邊形實現(xiàn)這里控制主圖不遮擋 boundingCoords: [ [73, 54], // 左上角經(jīng)緯度 [135, 18] // 右下角經(jīng)緯度 ] }邏輯說明boundingCoords定義地圖顯示的經(jīng)緯度范圍把南海區(qū)域包含進(jìn)來但又不讓它撐大主圖。參數(shù)上左上角取中國最西北右下角取最東南這樣南海自然落在右下角。注意如果你的 GeoJSON 不含南海諸島需要換一份完整數(shù)據(jù)這是數(shù)據(jù)層面的問題調(diào)參數(shù)解決不了。4. 飛線圖與彈窗輪播讓點位“活”起來4.1 飛線圖的 lines 系列起點終點與動效參數(shù)飛線本質(zhì)是series-lines每條線給起點和終點的經(jīng)緯度。動效靠effect配置symbol用箭頭或圓點trailLength控制拖尾長度。{ type: lines, coordinateSystem: geo, data: [ { coords: [[116.4, 39.9], [121.47, 31.23]] }, // 北京到上海 { coords: [[116.4, 39.9], [113.26, 23.13]] } // 北京到廣州 ], effect: { show: true, period: 4, // 動畫周期秒數(shù)越小越快 trailLength: 0.3, // 拖尾長度 0~1 symbol: arrow, symbolSize: 6 }, lineStyle: { color: #4fc3f7, width: 1.5, curveness: 0.2 // 彎曲度0 是直線 } }邏輯說明coords是[起點經(jīng)緯度, 終點經(jīng)緯度]順序不能反。參數(shù)上period控制飛線速度大屏一般 3~5 秒curveness給 0.2 左右能避免多條線重疊。注意飛線數(shù)據(jù)要跟著下鉆層級變省級下鉆后起點終點應(yīng)該換成省內(nèi)城市坐標(biāo)否則線會飛到地圖外面。4.2 點位名稱彈窗輪播dispatchAction 的 showTip輪播彈窗不是 CSS 動畫而是 ECharts 的dispatchAction定時觸發(fā)showTip。這樣彈窗位置會自動跟隨點位不用自己算坐標(biāo)。let tipIndex 0 const points [ { name: 項目A, value: [116.4, 39.9] }, { name: 項目B, value: [121.47, 31.23] } ] setInterval(() { chart.dispatchAction({ type: showTip, seriesIndex: 0, // 對應(yīng)散點系列的索引 dataIndex: tipIndex }) tipIndex (tipIndex 1) % points.length }, 3000)邏輯說明showTip需要指定seriesIndex和dataIndex所以散點系列必須排在 series 數(shù)組的固定位置。參數(shù)上 3000 是輪播間隔毫秒和飛線period錯開能避免視覺打架。注意組件銷毀時要clearInterval否則切路由后定時器還在跑控制臺會報實例已銷毀的錯。4.3 3D 地圖的接入geo3D 與 map3D 的差異ECharts 本身不直接支持 3D 地圖需要echarts-gl擴(kuò)展。geo3D和map3D兩個組件容易混geo3D是三維地理坐標(biāo)系可以疊加scatter3D和lines3Dmap3D是三維地圖本身適合做區(qū)域高度映射。import echarts-gl option { geo3D: { map: china, boxWidth: 100, boxDepth: 80, regionHeight: 3, // 區(qū)域擠出高度 viewControl: { alpha: 40, // 俯仰角 beta: 0, // 旋轉(zhuǎn)角 distance: 120 // 視距 }, itemStyle: { color: #1a3a6b, opacity: 0.9 } } }邏輯說明echarts-gl必須單獨 import否則geo3D不生效。參數(shù)上regionHeight控制地圖厚度viewControl.alpha調(diào)俯仰distance調(diào)遠(yuǎn)近。注意 3D 模式下roam行為不同下鉆時setOption要重新指定geo3D.map且 3D 和 2D 的 series 不能混用切換時要清空 series。5. 避坑排查那些讓我加班到凌晨的地圖問題5.1 地圖空白或只顯示一個方塊現(xiàn)象init后容器里只有背景色地圖輪廓不出現(xiàn)。原因通常是 GeoJSON 沒注冊成功或者series.map引用的名字和registerMap不一致。解決在setOption前打印echarts.getMap(china)返回 undefined 就是沒注冊上檢查 import 路徑是否被 tree-shaking 干掉改用require或把 JSON 放 public 用 fetch。5.2 下鉆后回鉆地圖數(shù)據(jù)錯亂現(xiàn)象點進(jìn)省份再返回中國地圖上出現(xiàn)了省份的點位。原因是setOption默認(rèn)合并舊的 series 沒被清掉。解決setOption(option, true)第二個參數(shù)傳true表示不合并或者每次下鉆前chart.clear()。我一般用notMerge: true但要注意geo的 roam 狀態(tài)會重置需要手動恢復(fù)縮放級別。5.3 飛線動畫卡頓幀率掉到個位數(shù)現(xiàn)象飛線一多整個大屏拖動都卡。原因是effect的trailLength太大或者線數(shù)量超過 50 條canvas 每幀重繪壓力大。解決trailLength降到 0.2 以下線數(shù)量控制在 30 條以內(nèi)或者改用lines的polyline: false減少路徑計算。如果還卡把effect.period調(diào)大犧牲流暢度換幀率。5.4 南海小窗被主圖蓋住或錯位現(xiàn)象南海諸島顯示在主圖右下角但被省份色塊遮擋。原因是geo的zlevel層級沒設(shè)對或者layoutCenter把主圖偏移了。解決給南海單獨一個geo實例設(shè)zlevel: 2高于主圖layoutCenter定位到右下角layoutSize給 15% 左右。注意兩個 geo 實例的map不能同名南海用單獨的 GeoJSON。5.5 彈窗輪播和鼠標(biāo)懸停沖突現(xiàn)象輪播到某個點位時鼠標(biāo)正好移上去彈窗閃爍或卡住。原因是showTip和mouseover同時觸發(fā)。解決監(jiān)聽mouseover時暫停輪播定時器mouseout后重啟。用一個isHovering標(biāo)志位控制簡單有效。6. 進(jìn)階技巧把下鉆做成可配置的組件6.1 用 props 驅(qū)動層級和點位數(shù)據(jù)把地圖封裝成 Vue 組件props接收level、adcode、points、lines組件內(nèi)部只負(fù)責(zé)渲染和事件派發(fā)。這樣換一個項目只需改數(shù)據(jù)不用動渲染邏輯。props: { level: { type: String, default: country }, // country/province/city adcode: { type: String, default: 100000 }, points: { type: Array, default: () [] }, lines: { type: Array, default: () [] }, autoPlay: { type: Boolean, default: true } }邏輯說明level決定加載哪一級地圖數(shù)據(jù)adcode是當(dāng)前區(qū)域代碼points和lines是業(yè)務(wù)數(shù)據(jù)。參數(shù)上autoPlay控制彈窗輪播開關(guān)。注意points的value必須是[lng, lat]格式否則散點會飛到 (0,0)。6.2 用 watch 監(jiān)聽 adcode 變化觸發(fā)重繪下鉆和回鉆本質(zhì)是adcode變化用watch監(jiān)聽比手動調(diào)方法更符合 Vue 的數(shù)據(jù)驅(qū)動。watch: { adcode: { immediate: true, async handler(newVal) { await this.loadMap(newVal) this.renderChart() } } }邏輯說明immediate: true讓組件初始化時就加載一次。參數(shù)上loadMap負(fù)責(zé)注冊地圖renderChart負(fù)責(zé)setOption。注意watch里要處理異步競態(tài)快速連點下鉆時后發(fā)的請求可能先返回加一個requestId比對。6.3 驗證清單上線前必過的五項檢查檢查項驗證方法通過標(biāo)準(zhǔn)地圖注冊控制臺echarts.getMap(china)返回對象非 undefined下鉆回鉆連點三級再連回三級地圖和數(shù)據(jù)同步切換無殘留南海顯示縮放到最小看右下角南海諸島完整不被遮擋飛線動效觀察 10 秒無卡頓線不飛出地圖彈窗輪播掛 5 分鐘彈窗循環(huán)無內(nèi)存增長這張表我每次交付前都跑一遍尤其是內(nèi)存增長用 Performance 面板錄一段就能看出來。從那以后我每次做地圖大屏都強制走一遍這個清單寧可多花十分鐘也不想半夜被電話叫起來改 bug。希望幫到你。本文還有配套的精品資源點擊獲取