簡(jiǎn)介這份資源面向需要在 Web 頁(yè)面中展示重慶區(qū)域地理數(shù)據(jù)的開發(fā)者提供基于 ECharts 實(shí)現(xiàn)重慶地圖可視化的基礎(chǔ)素材適合數(shù)據(jù)可視化入門與地圖交互開發(fā)場(chǎng)景。壓縮包共 2 個(gè)文件包含 1 個(gè) JSON 與 1 個(gè) HTML整體約 18KBJSON 文件承載重慶各行政區(qū)劃的名稱與經(jīng)緯度坐標(biāo)是繪制地圖邊界與形狀的數(shù)據(jù)基礎(chǔ)HTML 文件則給出引入 ECharts、創(chuàng)建容器、初始化實(shí)例并通過 setOption 加載地圖配置的完整頁(yè)面模板兩者配合即可快速跑通地圖渲染流程。目前已有 2425 人學(xué)習(xí)下載說明該素材在同類需求中具備一定參考價(jià)值。讀者可據(jù)此掌握 map 類型 series 的配置方式并在此基礎(chǔ)上擴(kuò)展區(qū)域著色、懸浮提示、點(diǎn)擊事件與縮放平移等交互或替換數(shù)據(jù)源實(shí)現(xiàn)自定義熱點(diǎn)展示為后續(xù)地理信息可視化項(xiàng)目提供可復(fù)用的起點(diǎn)。1. Echarts重慶地圖從行政區(qū)劃到可視化的落地路徑做過數(shù)據(jù)大屏的工程師大概率都遇到過這個(gè)需求業(yè)務(wù)方甩過來一份帶區(qū)縣字段的表格要求在地圖上按區(qū)域著色最好還能下鉆到街道。Echarts 本身不內(nèi)置重慶的行政區(qū)劃邊界官方地圖倉(cāng)庫(kù)里也沒有現(xiàn)成的重慶 GeoJSON所以“Echarts重慶地圖”這件事的核心不是寫配置項(xiàng)而是先把地理數(shù)據(jù)這條鏈路打通。它適合三類人做大屏前端但沒碰過地理數(shù)據(jù)的、需要按區(qū)縣做業(yè)務(wù)指標(biāo)可視化的、以及想給現(xiàn)有系統(tǒng)加一張區(qū)域熱力圖的后端轉(zhuǎn)全棧。整條鏈路拆開就是四步拿到合規(guī)的邊界數(shù)據(jù)、轉(zhuǎn)成 Echarts 認(rèn)的 GeoJSON、注冊(cè)地圖并配置 series、最后處理下鉆和性能。下面按這個(gè)順序講透每一步都給可復(fù)現(xiàn)的命令和代碼。2. 重慶地圖數(shù)據(jù)從哪來邊界獲取與格式轉(zhuǎn)換2.1 為什么不能直接用官方地圖包Echarts 5 之后官方不再隨包提供地圖 JSONecharts/map目錄已經(jīng)移除。很多人第一反應(yīng)是去翻舊版本或者找第三方 CDN 上的chongqing.js這條路有兩個(gè)坑一是舊數(shù)據(jù)邊界可能還是幾年前的行政區(qū)劃重慶這些年有過區(qū)縣調(diào)整二是第三方 CDN 的文件來源不可控生產(chǎn)環(huán)境引外鏈有可用性風(fēng)險(xiǎn)。常見做法是從公開的行政區(qū)劃數(shù)據(jù)源獲取自己轉(zhuǎn)成 GeoJSON 后本地托管。我一般會(huì)優(yōu)先用帶adcode字段的數(shù)據(jù)源因?yàn)橹貞c的區(qū)縣代碼是穩(wěn)定的后續(xù)做數(shù)據(jù)匹配時(shí)比中文名可靠得多。獲取渠道上公開的地理數(shù)據(jù)平臺(tái)會(huì)提供按省下載的 GeoJSON下載時(shí)注意選“區(qū)縣級(jí)”精度而不是“市級(jí)”否則整個(gè)重慶只有一個(gè)外輪廓沒法按區(qū)著色。文件下來之后先別急著用用命令行看一眼結(jié)構(gòu)確認(rèn)features數(shù)組里每個(gè)元素的properties有沒有name和adcode。# 查看下載的 GeoJSON 里有多少個(gè)區(qū)縣要素 python -c import json with open(chongqing_raw.geojson, r, encodingutf-8) as f: data json.load(f) print(要素?cái)?shù)量:, len(data[features])) # 打印前三個(gè)要素的屬性確認(rèn)字段名 for feat in data[features][:3]: print(feat[properties]) 這段腳本的作用是快速體檢數(shù)據(jù)。features的數(shù)量應(yīng)該接近重慶的區(qū)縣總數(shù)38 個(gè)左右含自治縣如果只有 1 個(gè)說明下錯(cuò)了精度層級(jí)。properties里如果字段名是NAME或fullname而不是name后面注冊(cè)地圖時(shí) Echarts 匹配不上需要先做字段重命名。參數(shù)上沒什么可調(diào)的重點(diǎn)是看輸出字段名不對(duì)就在轉(zhuǎn)換腳本里統(tǒng)一改掉。2.2 用 Python 把邊界數(shù)據(jù)轉(zhuǎn)成 Echarts 認(rèn)的 GeoJSONEcharts 的registerMap接受標(biāo)準(zhǔn) GeoJSON但有幾個(gè)隱性要求坐標(biāo)系必須是 WGS84 或 GCJ02 且全圖統(tǒng)一geometry.type支持Polygon和MultiPolygonproperties.name必須存在且和 series 里的name完全一致。公開數(shù)據(jù)源有時(shí)會(huì)帶一堆用不上的屬性字段文件體積大加載慢轉(zhuǎn)換時(shí)順手精簡(jiǎn)掉。import json def convert_to_echarts_geojson(src_path, dst_path): with open(src_path, r, encodingutf-8) as f: data json.load(f) features [] for feat in data[features]: props feat[properties] # 統(tǒng)一取 name 字段兼容不同數(shù)據(jù)源的命名 name props.get(name) or props.get(NAME) or props.get(fullname) adcode props.get(adcode) or props.get(ADCODE) if not name: continue # 沒有名稱的要素直接丟棄否則地圖上會(huì)出現(xiàn)無(wú)名區(qū)域 features.append({ type: Feature, properties: { name: name, adcode: str(adcode) if adcode else }, geometry: feat[geometry] }) out {type: FeatureCollection, features: features} with open(dst_path, w, encodingutf-8) as f: # ensure_asciiFalse 保證中文名不被轉(zhuǎn)義成 \uXXXX json.dump(out, f, ensure_asciiFalse) convert_to_echarts_geojson(chongqing_raw.geojson, chongqing.json)邏輯說明遍歷原始要素把可能叫name/NAME/fullname的字段統(tǒng)一成name這是 Echarts 匹配區(qū)域的關(guān)鍵。adcode保留成字符串方便后續(xù)和業(yè)務(wù)數(shù)據(jù)里的區(qū)縣代碼對(duì)齊。ensure_asciiFalse這個(gè)參數(shù)很容易被忽略不加的話中文區(qū)縣名會(huì)變成 Unicode 轉(zhuǎn)義雖然 Echarts 也能解析但調(diào)試時(shí)肉眼沒法看。轉(zhuǎn)換完檢查一下輸出文件大小精簡(jiǎn)后通常在幾百 KB 到 1MB 之間如果超過 2MB 說明屬性沒清干凈或者精度過高可以考慮用工具做坐標(biāo)抽稀。2.3 注冊(cè)地圖與最小可運(yùn)行配置數(shù)據(jù)準(zhǔn)備好之后前端側(cè)的核心就兩個(gè) APIecharts.registerMap注冊(cè)地圖然后在geo或series-map里引用。很多人卡在注冊(cè)了地圖但頁(yè)面空白八成是registerMap的第二個(gè)參數(shù)傳的是文件路徑字符串而不是解析后的對(duì)象或者注冊(cè)名和map配置項(xiàng)不一致。import * as echarts from echarts; import chongqingJson from ./chongqing.json; // 打包工具會(huì)解析成對(duì)象 // 注冊(cè)地圖第一個(gè)參數(shù)是自定義地圖名后續(xù)配置項(xiàng)要用同一個(gè)名字 echarts.registerMap(chongqing, chongqingJson); const chart echarts.init(document.getElementById(map)); chart.setOption({ tooltip: { trigger: item, formatter:  }, series: [{ type: map, map: chongqing, // 必須和 registerMap 的第一個(gè)參數(shù)一致 roam: true, // 允許縮放和拖拽 label: { show: true, fontSize: 10 }, itemStyle: { areaColor: #f0f2f5, borderColor: #999 }, emphasis: { itemStyle: { areaColor: #ffd666 } } }] });參數(shù)說明map的值是注冊(cè)時(shí)的名字不是文件名這里最容易翻車。roam: true開啟縮放拖拽大屏場(chǎng)景建議開但要注意和頁(yè)面滾動(dòng)的沖突移動(dòng)端可能需要關(guān)掉。label.show在區(qū)縣數(shù)量多的時(shí)候會(huì)顯得擁擠重慶 38 個(gè)區(qū)縣全顯示標(biāo)簽會(huì)糊成一片建議只在emphasis里顯示或者按縮放級(jí)別動(dòng)態(tài)控制。到這一步一張能交互的重慶地圖就跑起來了接下來才是把業(yè)務(wù)數(shù)據(jù)接進(jìn)去。3. 把業(yè)務(wù)數(shù)據(jù)映射到區(qū)縣series 配置與視覺編碼3.1 數(shù)據(jù)匹配的三種方式與踩坑地圖畫出來只是殼真正有價(jià)值的是把指標(biāo)數(shù)據(jù)映射到區(qū)域顏色上。Echarts 的series-map通過data數(shù)組里的name和 GeoJSON 的properties.name做匹配匹配不上就是灰色。實(shí)際項(xiàng)目里數(shù)據(jù)來源五花八門區(qū)縣名可能有“渝北區(qū)”和“渝北”兩種寫法或者帶空格直接匹配必然有一部分區(qū)域是灰的。常見做法有三種一是數(shù)據(jù)側(cè)統(tǒng)一清洗成和 GeoJSON 完全一致的名稱二是用nameMap做映射三是改用adcode匹配。我一般推薦第一種加第三種組合名稱用于展示adcode 用于匹配。如果數(shù)據(jù)里只有名稱那就老老實(shí)實(shí)做一次名稱對(duì)齊把“XX自治縣”簡(jiǎn)寫成“XX縣”這類差異在 ETL 階段處理掉別指望前端兜底。// 假設(shè)后端返回的數(shù)據(jù)里區(qū)縣名可能帶“區(qū)”字差異 const rawData [ { region: 渝北, value: 320 }, { region: 沙坪壩區(qū), value: 280 }, { region: 九龍坡, value: 260 } ]; // 名稱歸一化統(tǒng)一補(bǔ)全或去掉后綴和 GeoJSON 對(duì)齊 function normalizeName(name) { // 這里以 GeoJSON 里是“渝北區(qū)”這種全稱為例 if (!name.endsWith(區(qū)) !name.endsWith(縣)) { return name 區(qū); } return name; } const seriesData rawData.map(item ({ name: normalizeName(item.region), value: item.value }));邏輯說明normalizeName是個(gè)兜底函數(shù)真實(shí)項(xiàng)目里名稱差異遠(yuǎn)不止補(bǔ)個(gè)“區(qū)”字還有“兩江新區(qū)”這種不屬于標(biāo)準(zhǔn)行政區(qū)劃但業(yè)務(wù)上要單獨(dú)統(tǒng)計(jì)的情況。遇到這種要么在 GeoJSON 里手動(dòng)補(bǔ)一個(gè)虛擬區(qū)域要么在業(yè)務(wù)側(cè)歸并到所屬區(qū)縣。參數(shù)上value決定顏色深淺如果數(shù)據(jù)里有 0 和 null 的區(qū)別null 的區(qū)域會(huì)顯示為默認(rèn)色0 會(huì)顯示為最小值色視覺上要區(qū)分開。3.2 visualMap 分段與連續(xù)兩種模式的選型顏色映射靠visualMap控制分連續(xù)型和分段型。連續(xù)型適合展示趨勢(shì)顏色漸變平滑分段型適合做等級(jí)劃分比如把指標(biāo)分成“高/中/低”三檔業(yè)務(wù)方一眼能看懂。選哪個(gè)取決于數(shù)據(jù)分布如果數(shù)據(jù)是長(zhǎng)尾分布連續(xù)型會(huì)導(dǎo)致大部分區(qū)域顏色接近看不出差異這時(shí)候分段型更實(shí)用。visualMap: { type: piecewise, // 分段型改成 continuous 就是連續(xù)型 pieces: [ { min: 300, label: 高 (≥300), color: #d73027 }, { min: 150, max: 299, label: 中 (150-299), color: #fee08b }, { max: 149, label: 低 (150), color: #1a9850 } ], left: 20, bottom: 20, textStyle: { color: #333 } }參數(shù)說明pieces數(shù)組的順序會(huì)影響圖例展示一般從高到低排。min/max的邊界要覆蓋數(shù)據(jù)全集否則超出范圍的區(qū)域會(huì)沒有顏色。分段型的一個(gè)坑是max: 149這種寫法如果數(shù)據(jù)里有小數(shù)比如 149.5會(huì)落到?jīng)]有匹配的區(qū)間建議用min: 0, max: 149明確閉合。連續(xù)型則要注意min和max不設(shè)的話 Echarts 會(huì)自動(dòng)取數(shù)據(jù)極值但如果有 null 值可能算錯(cuò)手動(dòng)指定更穩(wěn)。3.3 區(qū)縣下鉆點(diǎn)擊事件與地圖切換大屏需求里十有八九要做下鉆點(diǎn)某個(gè)區(qū)縣切換到該區(qū)縣的街道級(jí)地圖。實(shí)現(xiàn)思路是監(jiān)聽click事件拿到區(qū)縣名或 adcode動(dòng)態(tài)registerMap新的地圖數(shù)據(jù)再setOption。這里的關(guān)鍵是街道級(jí)數(shù)據(jù)要提前準(zhǔn)備好按 adcode 命名文件點(diǎn)擊時(shí)按需加載。chart.on(click, async (params) { if (params.componentType ! series) return; const adcode params.data?.adcode; // 需要 GeoJSON 里帶 adcode 并透?jìng)鞯?data if (!adcode) return; // 動(dòng)態(tài)加載對(duì)應(yīng)區(qū)縣的街道級(jí) GeoJSON const res await fetch(/maps/${adcode}.json); const townJson await res.json(); echarts.registerMap(town_${adcode}, townJson); chart.setOption({ series: [{ type: map, map: town_${adcode}, data: [] // 街道級(jí)數(shù)據(jù)按需再請(qǐng)求 }] }); });邏輯說明params.data.adcode能拿到值的前提是 series 的 data 里帶了 adcode 字段而 data 又來自業(yè)務(wù)數(shù)據(jù)所以業(yè)務(wù)數(shù)據(jù)里必須包含 adcode。如果只有名稱就得在點(diǎn)擊時(shí)反查一張名稱到 adcode 的映射表。動(dòng)態(tài)registerMap會(huì)不斷往內(nèi)存里加地圖下鉆層級(jí)多了要注意清理Echarts 沒有提供反注冊(cè) API常見做法是控制下鉆深度或者用 iframe 隔離。返回上一級(jí)時(shí)重新注冊(cè)父級(jí)地圖即可但要注意setOption的合并策略地圖類型切換建議用notMerge: true避免殘留配置。4. 避坑與排查重慶地圖最常見的五類問題4.1 地圖顯示空白或只有背景色現(xiàn)象頁(yè)面初始化后容器有大小但地圖區(qū)域一片空白控制臺(tái)無(wú)報(bào)錯(cuò)。原因通常是registerMap沒執(zhí)行成功或者map配置項(xiàng)的名字和注冊(cè)名不一致。排查時(shí)先在registerMap后面打印一下echarts.getMap(chongqing)如果返回 undefined 說明注冊(cè)失敗多半是 GeoJSON 對(duì)象結(jié)構(gòu)不對(duì)比如傳了字符串路徑或者 JSON 解析失敗。另一個(gè)隱蔽原因是容器高度為 0Echarts 初始化時(shí)讀不到尺寸給容器加個(gè)明確的height就能解決。4.2 部分區(qū)縣顯示為灰色現(xiàn)象地圖出來了但有幾個(gè)區(qū)縣是默認(rèn)灰色tooltip 也顯示不出數(shù)據(jù)。原因是數(shù)據(jù)里的名稱和 GeoJSON 的properties.name對(duì)不上。解決方法是把 GeoJSON 里所有name打印出來和業(yè)務(wù)數(shù)據(jù)的區(qū)縣字段做一次 diff差異項(xiàng)在數(shù)據(jù)側(cè)修正。重慶有幾個(gè)容易出問題的名稱“兩江新區(qū)”不是標(biāo)準(zhǔn)行政區(qū)劃“萬(wàn)盛經(jīng)開區(qū)”在部分?jǐn)?shù)據(jù)源里歸在綦江這些要在需求階段就和業(yè)務(wù)方確認(rèn)歸屬。4.3 地圖變形或位置偏移現(xiàn)象地圖形狀看起來被壓扁或者拉伸。原因是 Echarts 默認(rèn)按容器寬高比渲染如果容器寬高比和地圖實(shí)際比例差太多就會(huì)變形。解決方法是給geo或series-map設(shè)置aspectScale默認(rèn) 0.75重慶的地圖可以調(diào)到 0.85 左右更接近真實(shí)比例。另外如果數(shù)據(jù)源坐標(biāo)系不統(tǒng)一比如部分要素是 GCJ02 部分是 WGS84會(huì)出現(xiàn)區(qū)域錯(cuò)位這種只能回到數(shù)據(jù)源層面統(tǒng)一。4.4 大數(shù)據(jù)量下渲染卡頓現(xiàn)象區(qū)縣數(shù)量多或者疊加了散點(diǎn)、飛線后縮放拖拽明顯掉幀。原因是roam開啟后每次交互都觸發(fā)重繪加上label.show全開渲染壓力大。優(yōu)化手段關(guān)閉非必要的label用emphasis按需顯示散點(diǎn)用large: true開啟大數(shù)據(jù)模式如果還卡把地圖渲染成靜態(tài)圖片作為底圖交互層用 canvas 單獨(dú)畫。重慶主城區(qū)縣面積小、數(shù)量密標(biāo)簽重疊嚴(yán)重建議默認(rèn)不顯示標(biāo)簽。4.5 下鉆后返回上一級(jí)數(shù)據(jù)錯(cuò)亂現(xiàn)象下鉆到區(qū)縣再返回地圖數(shù)據(jù)沒變或者顏色映射錯(cuò)亂。原因是setOption默認(rèn)是合并模式上一次的visualMap和series配置殘留。解決方法是切換地圖時(shí)用chart.setOption(option, true)強(qiáng)制不合并或者每次切換前chart.clear()。但clear會(huì)清掉事件監(jiān)聽需要重新綁定所以更推薦notMerge參數(shù)。另外下鉆時(shí)visualMap的min/max要按新地圖的數(shù)據(jù)范圍重新計(jì)算否則顏色全擠在一檔。5. 進(jìn)階技巧讓重慶地圖在大屏里真正好用前面四章把從數(shù)據(jù)到渲染的主鏈路走通了這一章講幾個(gè)讓地圖從“能用”到“好用”的技巧。第一個(gè)是坐標(biāo)系的統(tǒng)一。如果地圖上要疊加散點(diǎn)表示門店位置散點(diǎn)的經(jīng)緯度必須和 GeoJSON 同一坐標(biāo)系。公開數(shù)據(jù)源多為 WGS84而業(yè)務(wù)系統(tǒng)里的地址解析結(jié)果可能是 GCJ02兩者直接混用會(huì)有幾百米偏移在區(qū)縣級(jí)別看不出來放大到街道就露餡。常見做法是統(tǒng)一轉(zhuǎn)成 GCJ02轉(zhuǎn)換算法網(wǎng)上有成熟實(shí)現(xiàn)但要注意轉(zhuǎn)換是非線性的不能簡(jiǎn)單加偏移量。第二個(gè)是性能兜底。大屏通常 7x24 運(yùn)行內(nèi)存泄漏是隱形殺手。每次下鉆registerMap都會(huì)新增一份地圖數(shù)據(jù)長(zhǎng)時(shí)間運(yùn)行內(nèi)存會(huì)漲。我的習(xí)慣是限制下鉆層級(jí)為兩級(jí)并且在返回時(shí)手動(dòng)把不再使用的地圖數(shù)據(jù)置空雖然 Echarts 內(nèi)部還有引用但至少業(yè)務(wù)側(cè)不再持有。另外setInterval輪詢數(shù)據(jù)更新時(shí)如果地圖沒變化只更新series.data不要整個(gè)setOption重設(shè)前者只觸發(fā)數(shù)據(jù)重繪后者會(huì)重建整個(gè)圖表。第三個(gè)是視覺編碼的克制。很多大屏喜歡在地圖上堆特效飛線、漣漪、光暈全上結(jié)果業(yè)務(wù)方根本看不清哪個(gè)區(qū)縣指標(biāo)高。我的經(jīng)驗(yàn)是顏色映射只用一個(gè)visualMap不要同時(shí)用itemStyle.areaColor和visualMap兩套顏色邏輯會(huì)互相覆蓋標(biāo)簽只在 hover 時(shí)顯示飛線數(shù)量控制在 10 條以內(nèi)多了就是一團(tuán)亂麻。重慶的地形是山地主城和區(qū)縣的數(shù)據(jù)分布往往極不均衡用分段型visualMap比連續(xù)型更能突出差異。最后一個(gè)技巧關(guān)于數(shù)據(jù)更新。如果地圖數(shù)據(jù)是實(shí)時(shí)刷新的series.data的更新頻率建議控制在 5 秒以上太快人眼也反應(yīng)不過來還增加渲染壓力。更新時(shí)用chart.setOption({ series: [{ data: newData }] })這種局部更新Echarts 會(huì)做 diff比全量setOption快很多。驗(yàn)證更新是否生效可以在setOption后讀chart.getOption().series[0].data對(duì)比比肉眼看顏色靠譜。這套方案我在幾個(gè)大屏項(xiàng)目里反復(fù)用過最大的教訓(xùn)是地圖可視化的難點(diǎn)從來不在 Echarts 配置而在數(shù)據(jù)準(zhǔn)備和名稱對(duì)齊。前期花半小時(shí)把 GeoJSON 的name字段和業(yè)務(wù)數(shù)據(jù)的區(qū)縣字段做一次完整 diff能省掉后面幾小時(shí)的調(diào)試。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取