戰(zhàn)：多端層級、坐標(biāo)系與性能優(yōu)化)
簡介本資源是一套基于uni-app與Leaflet深度集成的地圖開發(fā)實(shí)踐方案面向使用Vue語法開發(fā)跨平臺移動應(yīng)用iOS/Android/H5/小程序的中高級前端開發(fā)者解決在uni-app中無法原生支持復(fù)雜地圖交互如撒點(diǎn)、軌跡繪制、GeoJSON解析、自定義區(qū)域等的痛點(diǎn)。壓縮包共18個(gè)文件含8個(gè)核心JS腳本含leaflet主庫、中文圖層適配、坐標(biāo)糾偏、WKT解析等插件、5張地圖圖標(biāo)與圖層PNG資源、3個(gè)Source Map調(diào)試文件、1個(gè)Vue組件mapContainer.vue及1個(gè)CSS樣式文件整體僅660KB輕量易集成。已有1980人學(xué)習(xí)下載資源結(jié)構(gòu)清晰直接提供可運(yùn)行的地圖容器組件、高德瓦片加載示例、多類型地理要素渲染邏輯及完整GeoJSON動態(tài)加載流程開箱即用顯著降低地圖功能在uni-app多端項(xiàng)目中的落地門檻。 做uniapp地圖功能那天我本來以為只是放個(gè)map組件、標(biāo)幾個(gè)marker結(jié)果愣是在安卓真機(jī)上從下午排查到晚上。彈窗被地圖蓋住、定位報(bào)錯(cuò)、marker不顯示三件事同時(shí)炸。后來跟同行聊才發(fā)現(xiàn)這不是我一個(gè)人的問題——map組件在uniapp里的坑是全端開發(fā)最容易被忽視的重災(zāi)區(qū)。這篇東西不打算把文檔里的API羅列一遍而是把我在實(shí)際項(xiàng)目里趟過的地圖組件相關(guān)問題一次說清為什么多端表現(xiàn)不一樣、遮擋問題怎么排查、定位坐標(biāo)系為什么總是報(bào)錯(cuò)、markers怎么寫才不卡。如果你正在被uniapp的map組件折磨這篇至少能讓你少走兩天彎路。1. 為什么uniapp的map組件多端表現(xiàn)不一致從原生組件說起1.1 一個(gè)追了一天的bug彈窗被地圖結(jié)結(jié)實(shí)實(shí)蓋住先講那天最典型的場景。業(yè)務(wù)邏輯很簡單地圖頁底部有個(gè)篩選按鈕點(diǎn)擊后彈出uni-popup里面放篩選條件。微信小程序預(yù)覽一切正常popup安安穩(wěn)穩(wěn)浮在地圖上。打包成安卓App后popup確實(shí)彈出來了但地圖像一塊鐵板一樣蓋在彈窗上面篩選按鈕點(diǎn)不到彈窗內(nèi)容被地圖完全遮住。我用z-index從999調(diào)到99999毫無反應(yīng)。這個(gè)問題的根源不是uniapp的bug而是map組件在不同端的渲染身份完全不一樣。很多人寫uniapp時(shí)習(xí)慣把它當(dāng)成“一套代碼到處跑”的魔法但地圖這類組件恰恰是例外中的例外。1.2 map在三端的真實(shí)渲染身份uniapp的map組件在微信小程序端、App端、H5端走的是三條完全不同的技術(shù)路線運(yùn)行端map組件的真實(shí)身份渲染方式層級表現(xiàn)微信小程序原生組件原生層渲染脫離WebView舊版本有嚴(yán)重層級問題現(xiàn)在部分平臺支持同層渲染AppHBuilderX打包原生地圖控件高德/騰訊plus-nativeObj或原生控件與WebView分離默認(rèn)蓋住WebView里的普通元素依賴同層渲染或cover-viewH5瀏覽器第三方JS SDK騰訊地圖/高德JS APIScript動態(tài)加載普通DOM節(jié)點(diǎn)層級由CSS z-index正?？刂谱钍⌒目吹絾栴}了嗎H5端地圖就是一個(gè)普通div你想蓋住它很容易。微信小程序端現(xiàn)在多數(shù)情況支持同層渲染普通view也能浮在地圖上。但App端尤其是Android的某些WebView版本map組件是獨(dú)立于WebView渲染的“原生層”原生層天然在WebView之上你寫一百層z-index也沒用。1.3 原生組件帶來的三個(gè)連鎖問題一旦明白了渲染身份差異你在uniapp里遇到的地圖問題就都能歸因了層級問題普通view、彈窗、popup蓋不住地圖需要cover-view或subNVue兜底。性能問題地圖是原生控件頻繁更新markers、頻繁調(diào)用mapContext方法會在原生層和WebView層之間造成大量通信開銷表現(xiàn)為掉幀、地圖閃爍。生命周期問題地圖在tab切換、頁面銷毀、App退后臺時(shí)渲染狀態(tài)和定位狀態(tài)經(jīng)常“失憶”回到頁面地圖白屏或定位漂移。如果你現(xiàn)在就在排查地圖問題第一步不是改代碼而是先確認(rèn)你當(dāng)前在哪個(gè)端復(fù)現(xiàn)。同一個(gè)代碼微信小程序正常不能證明App端正常反之亦然。這也是為什么我后面所有經(jīng)驗(yàn)都強(qiáng)調(diào)“真機(jī)驗(yàn)證”四個(gè)字模擬器里地圖有時(shí)候正常到讓你產(chǎn)生錯(cuò)覺。2. 地圖被遮罩和彈窗蓋住安卓端遮擋問題的完整排查鏈路這一章是App端地圖遮擋問題的實(shí)戰(zhàn)排查過程。我盡量把排查思路寫出來而不是直接扔結(jié)論因?yàn)橄麓文阌龅筋愃茊栴}換了個(gè)場景直接套結(jié)論可能又失效。2.1 先復(fù)現(xiàn)再縮小范圍最后確認(rèn)平臺差異遇到遮擋問題時(shí)我的排查路徑是這樣的先確認(rèn)所有端都復(fù)現(xiàn)還是只有特定端復(fù)現(xiàn)。如果H5也蓋不住那大概率是你的CSS問題如果只有App端蓋不住進(jìn)入下一步。把彈窗內(nèi)容換成純色塊排除彈窗內(nèi)部樣式干擾確定是地圖蓋住了整個(gè)彈窗還是只蓋住了彈窗的某一部分。檢查彈窗是使用uni-popup、自定義view還是cover-view實(shí)現(xiàn)。這一步很關(guān)鍵因?yàn)椴煌瑢?shí)現(xiàn)方案在App端的表現(xiàn)天差地別。把地圖組件加上show屬性控制顯隱手動設(shè)為false如果彈窗立刻正?；咀鴮?shí)是原生地圖層級壓制問題。我用這個(gè)鏈路定位問題時(shí)最終確認(rèn)是地圖原生層的鍋跟我彈窗里的內(nèi)容沒關(guān)系跟z-index也沒關(guān)系。2.2 方案一讓地圖自己把顯隱控制權(quán)交出來最簡單粗暴的解法是在需要彈窗時(shí)把地圖隱藏關(guān)閉彈窗后再顯示。map組件有個(gè)show屬性默認(rèn)true設(shè)為false后地圖不可見它占的層級空間自然就空了。map :showmapShow :latitudelatitude :longitudelongitude :markersmarkers /// 彈出篩選彈窗時(shí) this.mapShow false; // 關(guān)閉彈窗后 this.mapShow true;這個(gè)方案看起來有點(diǎn)“笨”但勝在穩(wěn)定適合“彈窗內(nèi)容與地圖本身沒有聯(lián)動關(guān)系”的場景。比如篩選條件、用戶協(xié)議、實(shí)名認(rèn)證彈窗地圖顯示不顯示都不影響業(yè)務(wù)流程。注意一點(diǎn)show設(shè)為false會讓整個(gè)地圖消失如果用戶關(guān)閉彈窗時(shí)地圖需要立即恢復(fù)渲染可能會有一個(gè)重建過程體驗(yàn)上會有輕微閃動業(yè)務(wù)可接受就沒問題。2.3 方案二cover-view的正確打開方式如果你必須保留地圖可見同時(shí)要在上面蓋一層按鈕或彈層那就得請出cover-view。cover-view是專門用來覆蓋原生組件的視圖容器它也是原生層的東西所以能蓋在map、video這類原生組件上面。微信小程序里它很常見uniapp App端同樣支持。map idmap :latitudelatitude :longitudelongitude :markersmarkers classmap-container / cover-view classmap-overlay cover-view classoverlay-card tapshowFilterPopup 篩選 /cover-view /cover-view注意幾個(gè)細(xì)節(jié)cover-view內(nèi)部只能嵌套cover-view和cover-image不能放普通的view、text寫了普通組件在部分端會渲染不出來。cover-view的樣式支持有限z-index、position、transform這些基礎(chǔ)屬性沒問題但類似box-shadow、border-radius在個(gè)別端可能表現(xiàn)不一致真機(jī)為準(zhǔn)。如果是為了整塊彈窗內(nèi)容cover-view寫起來會非常痛苦因?yàn)樗鼉?nèi)部不能放復(fù)雜DOM只能用原生組件堆。所以我的建議是簡單按鈕、標(biāo)簽、小卡片用cover-view復(fù)雜業(yè)務(wù)彈層直接用2.4的subNVue方案。2.4 方案三subNVue兜底復(fù)雜彈層當(dāng)你需要在App端地圖上方彈出一個(gè)包含列表、圖片、表單的完整頁面時(shí)cover-view根本沒法滿足而地圖又必須在彈窗下層保持顯示。這時(shí)候正解是使用subNVue原生子窗口。subNVue是uniapp App端提供的一種原生子窗體方案它獨(dú)立于WebView渲染因此天然蓋住地圖。我在地圖門店列表、地圖天氣詳情浮層這類需求上最終都用subNVue解決。// 創(chuàng)建/打開一個(gè)subNVue const subNVue uni.requireNativePlugin(subNVue); const popup subNVue.create({ id: subNVue_popup, url: /hybrid/html/filter.html, styles: { position: absolute, width: 100%, height: 400px, left: 0, bottom: 0, backgroundColor: #ffffff, borderRadius: 16px 16px 0 0 } }); popup.show();subNVue的使用門檻稍高因?yàn)樽禹撁媸仟?dú)立html不能直接用頁面的data和方法需要用uni.postMessage或plus.webview通信接口與主頁面交互。數(shù)據(jù)量小還好數(shù)據(jù)多了管起來會有點(diǎn)煩。如果你不想引入subNVue也可以退而求其次在彈窗顯示時(shí)把地圖暫時(shí)銷毀用v-if控制map節(jié)點(diǎn)或者用map外面套一層透明view并給一個(gè)高z-index——但在App端這個(gè)方案經(jīng)常無效。我實(shí)測下來真正可靠排序是subNVue 動態(tài)show隱藏地圖 cover-view。覆蓋簡單元素用cover-view最輕覆蓋復(fù)雜彈層用subNVue最穩(wěn)純隱藏地圖是懶得引入子窗口時(shí)的保底選項(xiàng)。3. 定位坐標(biāo)系的坑getLocation:fail translate coordinate system根因分析地圖組件繞不開定位。你在網(wǎng)上搜“uniapp getLocation報(bào)錯(cuò)”大概率會看到getlocation:fail translate coordinate system這一串英文。這個(gè)報(bào)錯(cuò)我第一次看到時(shí)完全懵后來定位到問題根源才發(fā)現(xiàn)又是坐標(biāo)系在搞事情。3.1 坐標(biāo)系不是玄學(xué)是行業(yè)規(guī)范國內(nèi)主流地圖服務(wù)坐標(biāo)系大致分三種坐標(biāo)系全稱使用方特點(diǎn)WGS-84世界大地坐標(biāo)系GPS原始坐標(biāo)、國際通用海外地圖、部分后端系統(tǒng)GCJ-02國測局坐標(biāo)高德、騰訊、大多數(shù)國內(nèi)地圖國內(nèi)民用地圖普遍使用的標(biāo)準(zhǔn)BD-09百度坐標(biāo)百度地圖在GCJ-02基礎(chǔ)上二次加密偏移如果你調(diào)用uni.getLocation拿到的坐標(biāo)和你在高德/騰訊地圖上看到的實(shí)際位置對不上通常就是坐標(biāo)系不匹配。這個(gè)偏移量在城市區(qū)域可能相差幾十米到幾百米放在地圖上看就是你的marker掉在馬路對面甚至隔壁街區(qū)。3.2 H5端定位報(bào)錯(cuò)的完整修復(fù)步驟H5端調(diào)用uni.getLocation報(bào)getlocation:fail translate coordinate system是很多人在瀏覽器里調(diào)試地圖時(shí)遇到的典型問題。這個(gè)報(bào)錯(cuò)的本質(zhì)是uniapp在H5端默認(rèn)使用騰訊地圖SDK進(jìn)行定位而騰訊地圖在做坐標(biāo)解析時(shí)要求你傳入正確的坐標(biāo)系參數(shù)或正確配置SDK的安全密鑰一旦配置缺失或參數(shù)錯(cuò)位SDK就會返回這個(gè)translate坐標(biāo)系失敗的錯(cuò)誤。修復(fù)步驟我整理出來打開manifest.json切到“H5配置”標(biāo)簽頁。在“小程序配置”或“App SDK配置”里找到地圖相關(guān)項(xiàng)填上騰訊地圖的key。注意H5端地圖定位用的是騰訊地圖所以必須在騰訊位置服務(wù)控制臺申請WebServiceAPI的key并且配置好域名白名單。確保uni.getLocation的type參數(shù)正確。如果你需要的是火星坐標(biāo)國內(nèi)地圖通用傳gcj02如果后端要求原始GPS坐標(biāo)傳wgs84。保存后重新編譯H5不要在舊編譯狀態(tài)下直接刷新uniapp的manifest配置改動需要重新編譯才生效。uni.getLocation({ type: gcj02, isHighAccuracy: true, success: (res) { console.log(當(dāng)前坐標(biāo):, res.latitude, res.longitude); }, fail: (err) { console.error(定位失敗:, err); } });如果你已經(jīng)按照上面步驟配置仍然報(bào)translate coordinate system可以檢查一下代碼里是否手動修改過地圖SDK的坐標(biāo)系參數(shù)或者在定位回調(diào)中又做了一次二次坐標(biāo)轉(zhuǎn)換。很多人為了兼容后端數(shù)據(jù)在拿到坐標(biāo)后又去調(diào)高德/騰訊的坐標(biāo)轉(zhuǎn)換API結(jié)果傳入?yún)?shù)錯(cuò)誤反而觸發(fā)了這個(gè)報(bào)錯(cuò)。3.3 App端與小程序端的定位參數(shù)取舍在微信小程序端uni.getLocation底層其實(shí)就是wx.getLocation返回坐標(biāo)系由type決定。需要注意的是小程序后臺需要配置定位權(quán)限申請理由否則會直接fail。App端的情況稍微復(fù)雜一點(diǎn)uniapp打包App后地圖和定位能力由高德或騰訊SDK提供你必須在manifest.json的“App模塊配置”里勾選“Geolocation定位”模塊并填寫對應(yīng)的key。如果你用的是高德定位SDK定位結(jié)果默認(rèn)就是GCJ-02用騰訊也是一樣國內(nèi)地圖坐標(biāo)都是基于GCJ-02的標(biāo)準(zhǔn)。我在App端常用的定位配置是{ permission: { scope.userLocation: { desc: 獲取你的位置信息用于展示附近門店 } }, requiredPrivateInfos: [getLocation] }requiredPrivateInfos是微信小程序隱私接口聲明App端打包時(shí)也需要在manifest里聲明定位權(quán)限用途否則在部分安卓機(jī)型上定位會靜默失敗不報(bào)錯(cuò)就是回調(diào)遲遲不來。3.4 坐標(biāo)互轉(zhuǎn)的實(shí)用代碼如果在定位拿到WGS-84坐標(biāo)而后端或地圖SDK要求GCJ-02你不一定非得調(diào)第三方API前端完全可以手動轉(zhuǎn)換。網(wǎng)上流傳比較廣的轉(zhuǎn)換算法基本夠用這里貼一份我項(xiàng)目里穩(wěn)定跑了一年多的精簡版const PI 3.1415926535897932384626; const A 6378245.0; const EE 0.00669342162296594323; function outOfChina(lat, lng) { return lng 72.004 || lng 137.8347 || lat 0.8293 || lat 55.8271; } function transformLat(x, y) { let ret -100.0 2.0 * x 3.0 * y 0.2 * y * y 0.1 * x * y 0.2 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * PI) 20.0 * Math.sin(2.0 * x * PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(y * PI) 40.0 * Math.sin(y / 3.0 * PI)) * 2.0 / 3.0; ret (160.0 * Math.sin(y / 12.0 * PI) 320 * Math.sin(y * PI / 30.0)) * 2.0 / 3.0; return ret; } function transformLng(x, y) { let ret 300.0 x 2.0 * y 0.1 * x * x 0.1 * x * y 0.1 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * PI) 20.0 * Math.sin(2.0 * x * PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(x * PI) 40.0 * Math.sin(x / 3.0 * PI)) * 2.0 / 3.0; ret (150.0 * Math.sin(x / 12.0 * PI) 300.0 * Math.sin(x / 30.0 * PI)) * 2.0 / 3.0; return ret; } function wgs84ToGcj02(lat, lng) { if (outOfChina(lat, lng)) { return { latitude: lat, longitude: lng }; } let dLat transformLat(lng - 105.0, lat - 35.0); let dLng transformLng(lng - 105.0, lat - 35.0); const radLat lat / 180.0 * PI; let magic Math.sin(radLat); magic 1 - EE * magic * magic; const sqrtMagic Math.sqrt(magic); dLat (dLat * 180.0) / ((A * (1 - EE)) / (magic * sqrtMagic) * PI); dLng (dLng * 180.0) / (A / sqrtMagic * Math.cos(radLat) * PI); return { latitude: lat dLat, longitude: lng dLng }; }轉(zhuǎn)換邏輯本身不復(fù)雜但我的經(jīng)驗(yàn)是項(xiàng)目里千萬不要每個(gè)頁面各寫一份坐標(biāo)轉(zhuǎn)換邏輯統(tǒng)一封裝到一個(gè)utils/geo.js所有定位入口都過一遍避免不同頁面一個(gè)用GCJ-02一個(gè)用WGS-84最后地圖上marker位置歪得離譜還查不到原因。4. markers與覆蓋物自定義標(biāo)記點(diǎn)的高級用法與性能優(yōu)化地圖上最核心的業(yè)務(wù)呈現(xiàn)方式就是標(biāo)記點(diǎn)。這里不說最基礎(chǔ)的“加個(gè)icon顯示個(gè)點(diǎn)”而是把我在項(xiàng)目里踩過的markers相關(guān)坑和優(yōu)化經(jīng)驗(yàn)講透。4.1 先看一份能直接用的markers基礎(chǔ)配置markers是一個(gè)數(shù)組每個(gè)marker代表一個(gè)標(biāo)記點(diǎn)。官方文檔字段不少但實(shí)際高頻使用的核心字段就這些this.markers [ { id: 1, latitude: 39.908, longitude: 116.397, iconPath: /static/marker_red.png, width: 28, height: 32, title: 故宮, label: { content: 故宮, color: #333333, fontSize: 12, anchorX: -10, anchorY: -30, bgColor: #ffffff, borderRadius: 4, padding: 6 }, callout: { content: 故宮博物院, display: BYCLICK, bgColor: #ffffff, color: #333333, fontSize: 14, borderRadius: 8, padding: 8, display: BYCLICK } } ];幾個(gè)容易踩的細(xì)節(jié)iconPath在App端和微信小程序端都支持本地路徑以/static開頭也支持網(wǎng)絡(luò)路徑。但網(wǎng)絡(luò)路徑在部分安卓機(jī)器上加載慢會出現(xiàn)marker先空白后閃現(xiàn)的情況建議上傳圖標(biāo)到CDN后在代碼里預(yù)下載或直接使用本地圖標(biāo)。width和height是邏輯像素不是圖片原始像素。圖片資源尺寸過大時(shí)地圖繪制圖標(biāo)會消耗性能建議圖標(biāo)本身控制在40x40px以內(nèi)。callout氣泡的display設(shè)置為BYCLICK才能在點(diǎn)擊標(biāo)記時(shí)彈出設(shè)為ALWAYS則常顯。如果你發(fā)現(xiàn)點(diǎn)擊標(biāo)記沒反應(yīng)先檢查是不是忘了設(shè)置idmarker沒有id點(diǎn)擊事件無法定位到具體標(biāo)記。4.2 標(biāo)記點(diǎn)點(diǎn)擊、氣泡與地圖列表聯(lián)動地圖和列表聯(lián)動是個(gè)經(jīng)典需求左側(cè)地圖顯示標(biāo)記點(diǎn)右側(cè)列表展示門店信息點(diǎn)列表高亮某個(gè)門店地圖上對應(yīng)的marker切換成高亮圖標(biāo)。實(shí)現(xiàn)方案不復(fù)雜核心是維護(hù)一個(gè)“當(dāng)前選中的門店id”然后動態(tài)更新markers數(shù)組handleSelectStore(store) { this.currentStoreId store.id; this.markers this.markers.map(marker { if (marker.id store.id) { return { ...marker, iconPath: /static/marker_selected.png, callout: { ...marker.callout, display: ALWAYS } }; } return { ...marker, iconPath: /static/marker_normal.png, callout: { ...marker.callout, display: BYCLICK } }; }); this.mapCtx.moveToLocation({ latitude: store.latitude, longitude: store.longitude }); }在markertap回調(diào)中e.detail.markerId可以拿到被點(diǎn)擊的marker idmap idmap :latitudelatitude :longitudelongitude :markersmarkers markertaponMarkerTap /onMarkerTap(e) { const markerId e.detail.markerId; const store this.storeList.find(item item.id markerId); if (store) { this.handleSelectStore(store); } }這里有個(gè)性能細(xì)節(jié)動態(tài)更新markers時(shí)不要每次把整個(gè)數(shù)組splice后重新push也不要無腦this.markers []再賦值這樣會導(dǎo)致地圖端頻繁重建原生標(biāo)記。正確做法是像上面那樣用map生成新數(shù)組一次性賦值讓地圖端最小化diff。4.3 大量標(biāo)記點(diǎn)卡頓聚合與節(jié)流的兩個(gè)方向當(dāng)業(yè)務(wù)數(shù)據(jù)量大起來比如地圖上要顯示幾百上千個(gè)門店或設(shè)備時(shí)markers數(shù)量過多會讓地圖明顯卡頓尤其在安卓低端機(jī)上拖動地圖時(shí)掉幀嚴(yán)重。這時(shí)候有兩條優(yōu)化路可以走第一是聚合思路。我項(xiàng)目里做的聚合方案是以當(dāng)前地圖視野的縮放級別為基準(zhǔn)將距離相近的標(biāo)記點(diǎn)合并成一個(gè)聚合點(diǎn)點(diǎn)數(shù)顯示在這個(gè)聚合marker的label上?？s放級別變大時(shí)聚合點(diǎn)自動拆分。這個(gè)邏輯有一定復(fù)雜度但效果立竿見影地圖上marker數(shù)量可以穩(wěn)定控制在100個(gè)以內(nèi)。第二是節(jié)流更新。在地圖視野變化事件regionchange中不要每次都重新請求數(shù)據(jù)并更新全部markers而是記錄當(dāng)前視野范圍等視野停止變化后再發(fā)起請求請求回來只更新新增區(qū)域的數(shù)據(jù)。配合防抖onRegionChange(e) { if (e.type end) { clearTimeout(this.regionTimer); this.regionTimer setTimeout(() { this.loadMarkersInCurrentView(); }, 300); } }regionchange事件在手指拖動過程中會頻繁觸發(fā)如果每次都加載數(shù)據(jù)地圖會一直處于“加載中”的狀態(tài)體驗(yàn)非常差。我實(shí)測加了這個(gè)300ms防抖后地圖拖動的流暢度提升非常明顯。5. 地圖與周邊業(yè)務(wù)場景串起來彈窗、tab切換與上架配置map組件從來不是孤立存在的它要和彈窗、tab切換、權(quán)限配置這些周邊環(huán)節(jié)配合。這一章把常見串場問題一次性講完。5.1 地圖頁彈uni-popup彈層還是會被蓋微信小程序端基本沒問題App端如果遇到popup被地圖蓋住可以回到第二章的三種方案里選。但這里要特別說一下uni-popup的實(shí)現(xiàn)uni-popup本身是用普通view組件堆出來的在App端原生地圖上層級天然吃虧就算你把popup的z-index調(diào)到最大也壓不過原生層。所以如果你非要用uni-popup建議在彈出時(shí)同步隱藏地圖。如果你不想隱藏地圖那就要把彈層內(nèi)容重構(gòu)成cover-view或者走subNVue原生子窗體。另外一個(gè)容易被忽略的點(diǎn)地圖上如果有自定義按鈕比如“回到當(dāng)前位置”的懸浮按鈕也請用cover-view包一層至少能保證按鈕在App端始終在上層可點(diǎn)。這個(gè)按鈕如果你用普通view寫iOS上可能正常安卓上就等著被地圖蓋住吧。5.2 tab切換后地圖白屏、定位丟失的處理在tabBar頁面中放map切走再切回來偶爾會遇到地圖白屏或者markers全部消失。說白了是地圖組件在原生的渲染生命周期沒有被正確恢復(fù)。一個(gè)可靠的解決方案在onShow生命周期里調(diào)用mapContext重新定位并主動觸發(fā)一次地圖視野刷新onShow() { if (this.mapCtx) { this.mapCtx.moveToLocation({ latitude: this.latitude, longitude: this.longitude, success: () { // 地圖恢復(fù)正常 } }); } }如果這樣做了還是白屏那就要考慮把tab頁面從“普通tab切換”改成“頁面棧跳轉(zhuǎn)”或使用條件渲染。我踩過一個(gè)比較刁鉆的場景tab頁里嵌webview再嵌地圖切走再切回地圖死活不刷新最后是把webview銷毀重建才解決。如果你用不到webview嵌套可以忽略但如果碰到白屏先想想是不是嵌套層次太多導(dǎo)致底層組件重建失敗。5.3 與地圖相關(guān)的工程化配置與上架前檢查地圖功能上架前有幾項(xiàng)配置是繞不開的manifest.json的App模塊配置里勾選Maps和Geolocation模塊并填寫對應(yīng)的高德或騰訊key。key要填對平臺打包Android時(shí)高德需要配置Android簽名的SHA1打包iOS時(shí)需要配置Bundle Identifier。key和包名不匹配地圖會加載白屏或者定位一直轉(zhuǎn)圈。權(quán)限聲明。Android端需要定位權(quán)限iOS端需要在Info.plist聲明NSLocationWhenInUseUsageDescription等描述內(nèi)容否則定位接口直接fail。隱私協(xié)議。現(xiàn)在的應(yīng)用市場對隱私合規(guī)要求越來越嚴(yán)彈窗里必須說明收集位置信息的目的和范圍用戶拒絕授權(quán)后還要確保App不至于崩潰。我在地圖頁統(tǒng)一做了授權(quán)失敗的降級處理沒有定位權(quán)限時(shí)顯示默認(rèn)城市的地圖而不是卡死在定位中。如果用了高德或騰訊地圖的Web服務(wù)API做坐標(biāo)轉(zhuǎn)換或逆地理編碼控制臺要配置域名白名單。H5端的白名單配置尤其重要漏了就會出現(xiàn)“請求失敗”的報(bào)錯(cuò)而且瀏覽器端報(bào)錯(cuò)信息還不太直觀。這些配置項(xiàng)不是難而是雜。我每次打包前都會過一遍檢查清單Android的SHA1、iOS的Bundle ID、key啟用哪些API、權(quán)限文案是否合規(guī)、無授權(quán)狀態(tài)是否有兜底頁面。地圖功能一旦上線用戶第一眼看到的就是位置是否準(zhǔn)確、地圖是否流暢這個(gè)環(huán)節(jié)出問題后面產(chǎn)品體驗(yàn)再好也白搭。最后分享一個(gè)個(gè)人習(xí)慣凡是涉及map組件的改動我一定會拿一臺低配安卓真機(jī)做回歸測試。模擬器里地圖至少能跑但安卓低端機(jī)才是地圖問題的照妖鏡遮擋、卡頓、白屏都在那兒等著你。uniapp的map組件能做好一個(gè)“穩(wěn)定可用”就已經(jīng)比很多項(xiàng)目強(qiáng)一截了希望這篇能幫你少踩幾個(gè)已經(jīng)有人踩過的坑。本文還有配套的精品資源點(diǎn)擊獲取 uniapp地圖組件避坑實(shí)戰(zhàn)：多端層級、坐標(biāo)系與性能優(yōu)化
簡介本資源是一套基于uni-app與Leaflet深度集成的地圖開發(fā)實(shí)踐方案面向使用Vue語法開發(fā)跨平臺移動應(yīng)用iOS/Android/H5/小程序的中高級前端開發(fā)者解決在uni-app中無法原生支持復(fù)雜地圖交互如撒點(diǎn)、軌跡繪制、GeoJSON解析、自定義區(qū)域等的痛點(diǎn)。壓縮包共18個(gè)文件含8個(gè)核心JS腳本含leaflet主庫、中文圖層適配、坐標(biāo)糾偏、WKT解析等插件、5張地圖圖標(biāo)與圖層PNG資源、3個(gè)Source Map調(diào)試文件、1個(gè)Vue組件mapContainer.vue及1個(gè)CSS樣式文件整體僅660KB輕量易集成。已有1980人學(xué)習(xí)下載資源結(jié)構(gòu)清晰直接提供可運(yùn)行的地圖容器組件、高德瓦片加載示例、多類型地理要素渲染邏輯及完整GeoJSON動態(tài)加載流程開箱即用顯著降低地圖功能在uni-app多端項(xiàng)目中的落地門檻。 做uniapp地圖功能那天我本來以為只是放個(gè)map組件、標(biāo)幾個(gè)marker結(jié)果愣是在安卓真機(jī)上從下午排查到晚上。彈窗被地圖蓋住、定位報(bào)錯(cuò)、marker不顯示三件事同時(shí)炸。后來跟同行聊才發(fā)現(xiàn)這不是我一個(gè)人的問題——map組件在uniapp里的坑是全端開發(fā)最容易被忽視的重災(zāi)區(qū)。這篇東西不打算把文檔里的API羅列一遍而是把我在實(shí)際項(xiàng)目里趟過的地圖組件相關(guān)問題一次說清為什么多端表現(xiàn)不一樣、遮擋問題怎么排查、定位坐標(biāo)系為什么總是報(bào)錯(cuò)、markers怎么寫才不卡。如果你正在被uniapp的map組件折磨這篇至少能讓你少走兩天彎路。1. 為什么uniapp的map組件多端表現(xiàn)不一致從原生組件說起1.1 一個(gè)追了一天的bug彈窗被地圖結(jié)結(jié)實(shí)實(shí)蓋住先講那天最典型的場景。業(yè)務(wù)邏輯很簡單地圖頁底部有個(gè)篩選按鈕點(diǎn)擊后彈出uni-popup里面放篩選條件。微信小程序預(yù)覽一切正常popup安安穩(wěn)穩(wěn)浮在地圖上。打包成安卓App后popup確實(shí)彈出來了但地圖像一塊鐵板一樣蓋在彈窗上面篩選按鈕點(diǎn)不到彈窗內(nèi)容被地圖完全遮住。我用z-index從999調(diào)到99999毫無反應(yīng)。這個(gè)問題的根源不是uniapp的bug而是map組件在不同端的渲染身份完全不一樣。很多人寫uniapp時(shí)習(xí)慣把它當(dāng)成“一套代碼到處跑”的魔法但地圖這類組件恰恰是例外中的例外。1.2 map在三端的真實(shí)渲染身份uniapp的map組件在微信小程序端、App端、H5端走的是三條完全不同的技術(shù)路線運(yùn)行端map組件的真實(shí)身份渲染方式層級表現(xiàn)微信小程序原生組件原生層渲染脫離WebView舊版本有嚴(yán)重層級問題現(xiàn)在部分平臺支持同層渲染AppHBuilderX打包原生地圖控件高德/騰訊plus-nativeObj或原生控件與WebView分離默認(rèn)蓋住WebView里的普通元素依賴同層渲染或cover-viewH5瀏覽器第三方JS SDK騰訊地圖/高德JS APIScript動態(tài)加載普通DOM節(jié)點(diǎn)層級由CSS z-index正?？刂谱钍⌒目吹絾栴}了嗎H5端地圖就是一個(gè)普通div你想蓋住它很容易。微信小程序端現(xiàn)在多數(shù)情況支持同層渲染普通view也能浮在地圖上。但App端尤其是Android的某些WebView版本map組件是獨(dú)立于WebView渲染的“原生層”原生層天然在WebView之上你寫一百層z-index也沒用。1.3 原生組件帶來的三個(gè)連鎖問題一旦明白了渲染身份差異你在uniapp里遇到的地圖問題就都能歸因了層級問題普通view、彈窗、popup蓋不住地圖需要cover-view或subNVue兜底。性能問題地圖是原生控件頻繁更新markers、頻繁調(diào)用mapContext方法會在原生層和WebView層之間造成大量通信開銷表現(xiàn)為掉幀、地圖閃爍。生命周期問題地圖在tab切換、頁面銷毀、App退后臺時(shí)渲染狀態(tài)和定位狀態(tài)經(jīng)常“失憶”回到頁面地圖白屏或定位漂移。如果你現(xiàn)在就在排查地圖問題第一步不是改代碼而是先確認(rèn)你當(dāng)前在哪個(gè)端復(fù)現(xiàn)。同一個(gè)代碼微信小程序正常不能證明App端正常反之亦然。這也是為什么我后面所有經(jīng)驗(yàn)都強(qiáng)調(diào)“真機(jī)驗(yàn)證”四個(gè)字模擬器里地圖有時(shí)候正常到讓你產(chǎn)生錯(cuò)覺。2. 地圖被遮罩和彈窗蓋住安卓端遮擋問題的完整排查鏈路這一章是App端地圖遮擋問題的實(shí)戰(zhàn)排查過程。我盡量把排查思路寫出來而不是直接扔結(jié)論因?yàn)橄麓文阌龅筋愃茊栴}換了個(gè)場景直接套結(jié)論可能又失效。2.1 先復(fù)現(xiàn)再縮小范圍最后確認(rèn)平臺差異遇到遮擋問題時(shí)我的排查路徑是這樣的先確認(rèn)所有端都復(fù)現(xiàn)還是只有特定端復(fù)現(xiàn)。如果H5也蓋不住那大概率是你的CSS問題如果只有App端蓋不住進(jìn)入下一步。把彈窗內(nèi)容換成純色塊排除彈窗內(nèi)部樣式干擾確定是地圖蓋住了整個(gè)彈窗還是只蓋住了彈窗的某一部分。檢查彈窗是使用uni-popup、自定義view還是cover-view實(shí)現(xiàn)。這一步很關(guān)鍵因?yàn)椴煌瑢?shí)現(xiàn)方案在App端的表現(xiàn)天差地別。把地圖組件加上show屬性控制顯隱手動設(shè)為false如果彈窗立刻正?；咀鴮?shí)是原生地圖層級壓制問題。我用這個(gè)鏈路定位問題時(shí)最終確認(rèn)是地圖原生層的鍋跟我彈窗里的內(nèi)容沒關(guān)系跟z-index也沒關(guān)系。2.2 方案一讓地圖自己把顯隱控制權(quán)交出來最簡單粗暴的解法是在需要彈窗時(shí)把地圖隱藏關(guān)閉彈窗后再顯示。map組件有個(gè)show屬性默認(rèn)true設(shè)為false后地圖不可見它占的層級空間自然就空了。map :showmapShow :latitudelatitude :longitudelongitude :markersmarkers /// 彈出篩選彈窗時(shí) this.mapShow false; // 關(guān)閉彈窗后 this.mapShow true;這個(gè)方案看起來有點(diǎn)“笨”但勝在穩(wěn)定適合“彈窗內(nèi)容與地圖本身沒有聯(lián)動關(guān)系”的場景。比如篩選條件、用戶協(xié)議、實(shí)名認(rèn)證彈窗地圖顯示不顯示都不影響業(yè)務(wù)流程。注意一點(diǎn)show設(shè)為false會讓整個(gè)地圖消失如果用戶關(guān)閉彈窗時(shí)地圖需要立即恢復(fù)渲染可能會有一個(gè)重建過程體驗(yàn)上會有輕微閃動業(yè)務(wù)可接受就沒問題。2.3 方案二cover-view的正確打開方式如果你必須保留地圖可見同時(shí)要在上面蓋一層按鈕或彈層那就得請出cover-view。cover-view是專門用來覆蓋原生組件的視圖容器它也是原生層的東西所以能蓋在map、video這類原生組件上面。微信小程序里它很常見uniapp App端同樣支持。map idmap :latitudelatitude :longitudelongitude :markersmarkers classmap-container / cover-view classmap-overlay cover-view classoverlay-card tapshowFilterPopup 篩選 /cover-view /cover-view注意幾個(gè)細(xì)節(jié)cover-view內(nèi)部只能嵌套cover-view和cover-image不能放普通的view、text寫了普通組件在部分端會渲染不出來。cover-view的樣式支持有限z-index、position、transform這些基礎(chǔ)屬性沒問題但類似box-shadow、border-radius在個(gè)別端可能表現(xiàn)不一致真機(jī)為準(zhǔn)。如果是為了整塊彈窗內(nèi)容cover-view寫起來會非常痛苦因?yàn)樗鼉?nèi)部不能放復(fù)雜DOM只能用原生組件堆。所以我的建議是簡單按鈕、標(biāo)簽、小卡片用cover-view復(fù)雜業(yè)務(wù)彈層直接用2.4的subNVue方案。2.4 方案三subNVue兜底復(fù)雜彈層當(dāng)你需要在App端地圖上方彈出一個(gè)包含列表、圖片、表單的完整頁面時(shí)cover-view根本沒法滿足而地圖又必須在彈窗下層保持顯示。這時(shí)候正解是使用subNVue原生子窗口。subNVue是uniapp App端提供的一種原生子窗體方案它獨(dú)立于WebView渲染因此天然蓋住地圖。我在地圖門店列表、地圖天氣詳情浮層這類需求上最終都用subNVue解決。// 創(chuàng)建/打開一個(gè)subNVue const subNVue uni.requireNativePlugin(subNVue); const popup subNVue.create({ id: subNVue_popup, url: /hybrid/html/filter.html, styles: { position: absolute, width: 100%, height: 400px, left: 0, bottom: 0, backgroundColor: #ffffff, borderRadius: 16px 16px 0 0 } }); popup.show();subNVue的使用門檻稍高因?yàn)樽禹撁媸仟?dú)立html不能直接用頁面的data和方法需要用uni.postMessage或plus.webview通信接口與主頁面交互。數(shù)據(jù)量小還好數(shù)據(jù)多了管起來會有點(diǎn)煩。如果你不想引入subNVue也可以退而求其次在彈窗顯示時(shí)把地圖暫時(shí)銷毀用v-if控制map節(jié)點(diǎn)或者用map外面套一層透明view并給一個(gè)高z-index——但在App端這個(gè)方案經(jīng)常無效。我實(shí)測下來真正可靠排序是subNVue 動態(tài)show隱藏地圖 cover-view。覆蓋簡單元素用cover-view最輕覆蓋復(fù)雜彈層用subNVue最穩(wěn)純隱藏地圖是懶得引入子窗口時(shí)的保底選項(xiàng)。3. 定位坐標(biāo)系的坑getLocation:fail translate coordinate system根因分析地圖組件繞不開定位。你在網(wǎng)上搜“uniapp getLocation報(bào)錯(cuò)”大概率會看到getlocation:fail translate coordinate system這一串英文。這個(gè)報(bào)錯(cuò)我第一次看到時(shí)完全懵后來定位到問題根源才發(fā)現(xiàn)又是坐標(biāo)系在搞事情。3.1 坐標(biāo)系不是玄學(xué)是行業(yè)規(guī)范國內(nèi)主流地圖服務(wù)坐標(biāo)系大致分三種坐標(biāo)系全稱使用方特點(diǎn)WGS-84世界大地坐標(biāo)系GPS原始坐標(biāo)、國際通用海外地圖、部分后端系統(tǒng)GCJ-02國測局坐標(biāo)高德、騰訊、大多數(shù)國內(nèi)地圖國內(nèi)民用地圖普遍使用的標(biāo)準(zhǔn)BD-09百度坐標(biāo)百度地圖在GCJ-02基礎(chǔ)上二次加密偏移如果你調(diào)用uni.getLocation拿到的坐標(biāo)和你在高德/騰訊地圖上看到的實(shí)際位置對不上通常就是坐標(biāo)系不匹配。這個(gè)偏移量在城市區(qū)域可能相差幾十米到幾百米放在地圖上看就是你的marker掉在馬路對面甚至隔壁街區(qū)。3.2 H5端定位報(bào)錯(cuò)的完整修復(fù)步驟H5端調(diào)用uni.getLocation報(bào)getlocation:fail translate coordinate system是很多人在瀏覽器里調(diào)試地圖時(shí)遇到的典型問題。這個(gè)報(bào)錯(cuò)的本質(zhì)是uniapp在H5端默認(rèn)使用騰訊地圖SDK進(jìn)行定位而騰訊地圖在做坐標(biāo)解析時(shí)要求你傳入正確的坐標(biāo)系參數(shù)或正確配置SDK的安全密鑰一旦配置缺失或參數(shù)錯(cuò)位SDK就會返回這個(gè)translate坐標(biāo)系失敗的錯(cuò)誤。修復(fù)步驟我整理出來打開manifest.json切到“H5配置”標(biāo)簽頁。在“小程序配置”或“App SDK配置”里找到地圖相關(guān)項(xiàng)填上騰訊地圖的key。注意H5端地圖定位用的是騰訊地圖所以必須在騰訊位置服務(wù)控制臺申請WebServiceAPI的key并且配置好域名白名單。確保uni.getLocation的type參數(shù)正確。如果你需要的是火星坐標(biāo)國內(nèi)地圖通用傳gcj02如果后端要求原始GPS坐標(biāo)傳wgs84。保存后重新編譯H5不要在舊編譯狀態(tài)下直接刷新uniapp的manifest配置改動需要重新編譯才生效。uni.getLocation({ type: gcj02, isHighAccuracy: true, success: (res) { console.log(當(dāng)前坐標(biāo):, res.latitude, res.longitude); }, fail: (err) { console.error(定位失敗:, err); } });如果你已經(jīng)按照上面步驟配置仍然報(bào)translate coordinate system可以檢查一下代碼里是否手動修改過地圖SDK的坐標(biāo)系參數(shù)或者在定位回調(diào)中又做了一次二次坐標(biāo)轉(zhuǎn)換。很多人為了兼容后端數(shù)據(jù)在拿到坐標(biāo)后又去調(diào)高德/騰訊的坐標(biāo)轉(zhuǎn)換API結(jié)果傳入?yún)?shù)錯(cuò)誤反而觸發(fā)了這個(gè)報(bào)錯(cuò)。3.3 App端與小程序端的定位參數(shù)取舍在微信小程序端uni.getLocation底層其實(shí)就是wx.getLocation返回坐標(biāo)系由type決定。需要注意的是小程序后臺需要配置定位權(quán)限申請理由否則會直接fail。App端的情況稍微復(fù)雜一點(diǎn)uniapp打包App后地圖和定位能力由高德或騰訊SDK提供你必須在manifest.json的“App模塊配置”里勾選“Geolocation定位”模塊并填寫對應(yīng)的key。如果你用的是高德定位SDK定位結(jié)果默認(rèn)就是GCJ-02用騰訊也是一樣國內(nèi)地圖坐標(biāo)都是基于GCJ-02的標(biāo)準(zhǔn)。我在App端常用的定位配置是{ permission: { scope.userLocation: { desc: 獲取你的位置信息用于展示附近門店 } }, requiredPrivateInfos: [getLocation] }requiredPrivateInfos是微信小程序隱私接口聲明App端打包時(shí)也需要在manifest里聲明定位權(quán)限用途否則在部分安卓機(jī)型上定位會靜默失敗不報(bào)錯(cuò)就是回調(diào)遲遲不來。3.4 坐標(biāo)互轉(zhuǎn)的實(shí)用代碼如果在定位拿到WGS-84坐標(biāo)而后端或地圖SDK要求GCJ-02你不一定非得調(diào)第三方API前端完全可以手動轉(zhuǎn)換。網(wǎng)上流傳比較廣的轉(zhuǎn)換算法基本夠用這里貼一份我項(xiàng)目里穩(wěn)定跑了一年多的精簡版const PI 3.1415926535897932384626; const A 6378245.0; const EE 0.00669342162296594323; function outOfChina(lat, lng) { return lng 72.004 || lng 137.8347 || lat 0.8293 || lat 55.8271; } function transformLat(x, y) { let ret -100.0 2.0 * x 3.0 * y 0.2 * y * y 0.1 * x * y 0.2 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * PI) 20.0 * Math.sin(2.0 * x * PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(y * PI) 40.0 * Math.sin(y / 3.0 * PI)) * 2.0 / 3.0; ret (160.0 * Math.sin(y / 12.0 * PI) 320 * Math.sin(y * PI / 30.0)) * 2.0 / 3.0; return ret; } function transformLng(x, y) { let ret 300.0 x 2.0 * y 0.1 * x * x 0.1 * x * y 0.1 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * PI) 20.0 * Math.sin(2.0 * x * PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(x * PI) 40.0 * Math.sin(x / 3.0 * PI)) * 2.0 / 3.0; ret (150.0 * Math.sin(x / 12.0 * PI) 300.0 * Math.sin(x / 30.0 * PI)) * 2.0 / 3.0; return ret; } function wgs84ToGcj02(lat, lng) { if (outOfChina(lat, lng)) { return { latitude: lat, longitude: lng }; } let dLat transformLat(lng - 105.0, lat - 35.0); let dLng transformLng(lng - 105.0, lat - 35.0); const radLat lat / 180.0 * PI; let magic Math.sin(radLat); magic 1 - EE * magic * magic; const sqrtMagic Math.sqrt(magic); dLat (dLat * 180.0) / ((A * (1 - EE)) / (magic * sqrtMagic) * PI); dLng (dLng * 180.0) / (A / sqrtMagic * Math.cos(radLat) * PI); return { latitude: lat dLat, longitude: lng dLng }; }轉(zhuǎn)換邏輯本身不復(fù)雜但我的經(jīng)驗(yàn)是項(xiàng)目里千萬不要每個(gè)頁面各寫一份坐標(biāo)轉(zhuǎn)換邏輯統(tǒng)一封裝到一個(gè)utils/geo.js所有定位入口都過一遍避免不同頁面一個(gè)用GCJ-02一個(gè)用WGS-84最后地圖上marker位置歪得離譜還查不到原因。4. markers與覆蓋物自定義標(biāo)記點(diǎn)的高級用法與性能優(yōu)化地圖上最核心的業(yè)務(wù)呈現(xiàn)方式就是標(biāo)記點(diǎn)。這里不說最基礎(chǔ)的“加個(gè)icon顯示個(gè)點(diǎn)”而是把我在項(xiàng)目里踩過的markers相關(guān)坑和優(yōu)化經(jīng)驗(yàn)講透。4.1 先看一份能直接用的markers基礎(chǔ)配置markers是一個(gè)數(shù)組每個(gè)marker代表一個(gè)標(biāo)記點(diǎn)。官方文檔字段不少但實(shí)際高頻使用的核心字段就這些this.markers [ { id: 1, latitude: 39.908, longitude: 116.397, iconPath: /static/marker_red.png, width: 28, height: 32, title: 故宮, label: { content: 故宮, color: #333333, fontSize: 12, anchorX: -10, anchorY: -30, bgColor: #ffffff, borderRadius: 4, padding: 6 }, callout: { content: 故宮博物院, display: BYCLICK, bgColor: #ffffff, color: #333333, fontSize: 14, borderRadius: 8, padding: 8, display: BYCLICK } } ];幾個(gè)容易踩的細(xì)節(jié)iconPath在App端和微信小程序端都支持本地路徑以/static開頭也支持網(wǎng)絡(luò)路徑。但網(wǎng)絡(luò)路徑在部分安卓機(jī)器上加載慢會出現(xiàn)marker先空白后閃現(xiàn)的情況建議上傳圖標(biāo)到CDN后在代碼里預(yù)下載或直接使用本地圖標(biāo)。width和height是邏輯像素不是圖片原始像素。圖片資源尺寸過大時(shí)地圖繪制圖標(biāo)會消耗性能建議圖標(biāo)本身控制在40x40px以內(nèi)。callout氣泡的display設(shè)置為BYCLICK才能在點(diǎn)擊標(biāo)記時(shí)彈出設(shè)為ALWAYS則常顯。如果你發(fā)現(xiàn)點(diǎn)擊標(biāo)記沒反應(yīng)先檢查是不是忘了設(shè)置idmarker沒有id點(diǎn)擊事件無法定位到具體標(biāo)記。4.2 標(biāo)記點(diǎn)點(diǎn)擊、氣泡與地圖列表聯(lián)動地圖和列表聯(lián)動是個(gè)經(jīng)典需求左側(cè)地圖顯示標(biāo)記點(diǎn)右側(cè)列表展示門店信息點(diǎn)列表高亮某個(gè)門店地圖上對應(yīng)的marker切換成高亮圖標(biāo)。實(shí)現(xiàn)方案不復(fù)雜核心是維護(hù)一個(gè)“當(dāng)前選中的門店id”然后動態(tài)更新markers數(shù)組handleSelectStore(store) { this.currentStoreId store.id; this.markers this.markers.map(marker { if (marker.id store.id) { return { ...marker, iconPath: /static/marker_selected.png, callout: { ...marker.callout, display: ALWAYS } }; } return { ...marker, iconPath: /static/marker_normal.png, callout: { ...marker.callout, display: BYCLICK } }; }); this.mapCtx.moveToLocation({ latitude: store.latitude, longitude: store.longitude }); }在markertap回調(diào)中e.detail.markerId可以拿到被點(diǎn)擊的marker idmap idmap :latitudelatitude :longitudelongitude :markersmarkers markertaponMarkerTap /onMarkerTap(e) { const markerId e.detail.markerId; const store this.storeList.find(item item.id markerId); if (store) { this.handleSelectStore(store); } }這里有個(gè)性能細(xì)節(jié)動態(tài)更新markers時(shí)不要每次把整個(gè)數(shù)組splice后重新push也不要無腦this.markers []再賦值這樣會導(dǎo)致地圖端頻繁重建原生標(biāo)記。正確做法是像上面那樣用map生成新數(shù)組一次性賦值讓地圖端最小化diff。4.3 大量標(biāo)記點(diǎn)卡頓聚合與節(jié)流的兩個(gè)方向當(dāng)業(yè)務(wù)數(shù)據(jù)量大起來比如地圖上要顯示幾百上千個(gè)門店或設(shè)備時(shí)markers數(shù)量過多會讓地圖明顯卡頓尤其在安卓低端機(jī)上拖動地圖時(shí)掉幀嚴(yán)重。這時(shí)候有兩條優(yōu)化路可以走第一是聚合思路。我項(xiàng)目里做的聚合方案是以當(dāng)前地圖視野的縮放級別為基準(zhǔn)將距離相近的標(biāo)記點(diǎn)合并成一個(gè)聚合點(diǎn)點(diǎn)數(shù)顯示在這個(gè)聚合marker的label上?？s放級別變大時(shí)聚合點(diǎn)自動拆分。這個(gè)邏輯有一定復(fù)雜度但效果立竿見影地圖上marker數(shù)量可以穩(wěn)定控制在100個(gè)以內(nèi)。第二是節(jié)流更新。在地圖視野變化事件regionchange中不要每次都重新請求數(shù)據(jù)并更新全部markers而是記錄當(dāng)前視野范圍等視野停止變化后再發(fā)起請求請求回來只更新新增區(qū)域的數(shù)據(jù)。配合防抖onRegionChange(e) { if (e.type end) { clearTimeout(this.regionTimer); this.regionTimer setTimeout(() { this.loadMarkersInCurrentView(); }, 300); } }regionchange事件在手指拖動過程中會頻繁觸發(fā)如果每次都加載數(shù)據(jù)地圖會一直處于“加載中”的狀態(tài)體驗(yàn)非常差。我實(shí)測加了這個(gè)300ms防抖后地圖拖動的流暢度提升非常明顯。5. 地圖與周邊業(yè)務(wù)場景串起來彈窗、tab切換與上架配置map組件從來不是孤立存在的它要和彈窗、tab切換、權(quán)限配置這些周邊環(huán)節(jié)配合。這一章把常見串場問題一次性講完。5.1 地圖頁彈uni-popup彈層還是會被蓋微信小程序端基本沒問題App端如果遇到popup被地圖蓋住可以回到第二章的三種方案里選。但這里要特別說一下uni-popup的實(shí)現(xiàn)uni-popup本身是用普通view組件堆出來的在App端原生地圖上層級天然吃虧就算你把popup的z-index調(diào)到最大也壓不過原生層。所以如果你非要用uni-popup建議在彈出時(shí)同步隱藏地圖。如果你不想隱藏地圖那就要把彈層內(nèi)容重構(gòu)成cover-view或者走subNVue原生子窗體。另外一個(gè)容易被忽略的點(diǎn)地圖上如果有自定義按鈕比如“回到當(dāng)前位置”的懸浮按鈕也請用cover-view包一層至少能保證按鈕在App端始終在上層可點(diǎn)。這個(gè)按鈕如果你用普通view寫iOS上可能正常安卓上就等著被地圖蓋住吧。5.2 tab切換后地圖白屏、定位丟失的處理在tabBar頁面中放map切走再切回來偶爾會遇到地圖白屏或者markers全部消失。說白了是地圖組件在原生的渲染生命周期沒有被正確恢復(fù)。一個(gè)可靠的解決方案在onShow生命周期里調(diào)用mapContext重新定位并主動觸發(fā)一次地圖視野刷新onShow() { if (this.mapCtx) { this.mapCtx.moveToLocation({ latitude: this.latitude, longitude: this.longitude, success: () { // 地圖恢復(fù)正常 } }); } }如果這樣做了還是白屏那就要考慮把tab頁面從“普通tab切換”改成“頁面棧跳轉(zhuǎn)”或使用條件渲染。我踩過一個(gè)比較刁鉆的場景tab頁里嵌webview再嵌地圖切走再切回地圖死活不刷新最后是把webview銷毀重建才解決。如果你用不到webview嵌套可以忽略但如果碰到白屏先想想是不是嵌套層次太多導(dǎo)致底層組件重建失敗。5.3 與地圖相關(guān)的工程化配置與上架前檢查地圖功能上架前有幾項(xiàng)配置是繞不開的manifest.json的App模塊配置里勾選Maps和Geolocation模塊并填寫對應(yīng)的高德或騰訊key。key要填對平臺打包Android時(shí)高德需要配置Android簽名的SHA1打包iOS時(shí)需要配置Bundle Identifier。key和包名不匹配地圖會加載白屏或者定位一直轉(zhuǎn)圈。權(quán)限聲明。Android端需要定位權(quán)限iOS端需要在Info.plist聲明NSLocationWhenInUseUsageDescription等描述內(nèi)容否則定位接口直接fail。隱私協(xié)議。現(xiàn)在的應(yīng)用市場對隱私合規(guī)要求越來越嚴(yán)彈窗里必須說明收集位置信息的目的和范圍用戶拒絕授權(quán)后還要確保App不至于崩潰。我在地圖頁統(tǒng)一做了授權(quán)失敗的降級處理沒有定位權(quán)限時(shí)顯示默認(rèn)城市的地圖而不是卡死在定位中。如果用了高德或騰訊地圖的Web服務(wù)API做坐標(biāo)轉(zhuǎn)換或逆地理編碼控制臺要配置域名白名單。H5端的白名單配置尤其重要漏了就會出現(xiàn)“請求失敗”的報(bào)錯(cuò)而且瀏覽器端報(bào)錯(cuò)信息還不太直觀。這些配置項(xiàng)不是難而是雜。我每次打包前都會過一遍檢查清單Android的SHA1、iOS的Bundle ID、key啟用哪些API、權(quán)限文案是否合規(guī)、無授權(quán)狀態(tài)是否有兜底頁面。地圖功能一旦上線用戶第一眼看到的就是位置是否準(zhǔn)確、地圖是否流暢這個(gè)環(huán)節(jié)出問題后面產(chǎn)品體驗(yàn)再好也白搭。最后分享一個(gè)個(gè)人習(xí)慣凡是涉及map組件的改動我一定會拿一臺低配安卓真機(jī)做回歸測試。模擬器里地圖至少能跑但安卓低端機(jī)才是地圖問題的照妖鏡遮擋、卡頓、白屏都在那兒等著你。uniapp的map組件能做好一個(gè)“穩(wěn)定可用”就已經(jīng)比很多項(xiàng)目強(qiáng)一截了希望這篇能幫你少踩幾個(gè)已經(jīng)有人踩過的坑。本文還有配套的精品資源點(diǎn)擊獲取