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