簡介一份面向Android開發(fā)者的百度地圖導(dǎo)航功能工程資源覆蓋從開發(fā)包集成、權(quán)限聲明、位置獲取、起終點(diǎn)設(shè)置、路線規(guī)劃到導(dǎo)航引導(dǎo)的完整鏈路適合需要快速為已有應(yīng)用接入地圖導(dǎo)航模塊的中級開發(fā)者。壓縮包為rar格式共1343個(gè)文件約22.55MB內(nèi)含大量布局與配置文件、圖標(biāo)素材、Java源碼、依賴庫、AIDL接口、JSON數(shù)據(jù)、Gradle構(gòu)建腳本以及可直接運(yùn)行的調(diào)試安裝包基本覆蓋一個(gè)Android項(xiàng)目從源碼資源到編譯產(chǎn)物的各個(gè)層面目錄結(jié)構(gòu)清晰。已有520人學(xué)習(xí)下載。通過該工程可對照理解百度地圖位置監(jiān)聽、路線檢索、路徑繪制、語音播報(bào)等核心API的實(shí)際用法同時(shí)可基于現(xiàn)成的界面與構(gòu)建配置直接運(yùn)行調(diào)試并便捷地?cái)U(kuò)展駕車、步行、騎行等出行方式對于排查SDK接入、定位失敗、路線不顯示等常見問題也有直接參考價(jià)值是地圖導(dǎo)航模塊一個(gè)完整的起步模板。1. 導(dǎo)航功能不是從零寫的這份Demo把集成路線走通了拿到這份工程之前我也有一個(gè)執(zhí)念A(yù)pp 里做導(dǎo)航要么是調(diào)起外部地圖應(yīng)用要么是把路線規(guī)劃算法搬進(jìn)項(xiàng)目里自己算。把工程跑起來之后才發(fā)現(xiàn)常規(guī)做法遠(yuǎn)沒有這么重——地圖展示、實(shí)時(shí)定位、路線規(guī)劃、導(dǎo)航狀態(tài)推進(jìn)每一層都拆成獨(dú)立模塊再通過事件回調(diào)串成一條鏈路。這份 Demo 適合兩類人一類是業(yè)務(wù)系統(tǒng)里需要“路線預(yù)覽”和“模擬導(dǎo)航”能力的 Android 開發(fā)另一類是做物流配送、外勤打卡類項(xiàng)目想快速把定位和導(dǎo)航能力嵌進(jìn)自己 App 的團(tuán)隊(duì)。下面我按工程結(jié)構(gòu)、核心代碼、落地細(xì)節(jié)和避坑記錄逐個(gè)拆開講。2. 工程骨架拆解從一個(gè)按鈕到一條可導(dǎo)航路線的完整鏈路2.1 目錄結(jié)構(gòu)每個(gè)包只負(fù)責(zé)導(dǎo)航鏈路里的一環(huán)工程不是那種“所有代碼堆在一個(gè) Activity 里”的老式寫法打開根目錄就能看出模塊邊界NavDemo/ ├── app/ │ ├── build.gradle │ └── src/main/ │ ├── AndroidManifest.xml │ ├── java/com/demo/nav/ │ │ ├── MainActivity.kt │ │ ├── map/MapViewHolder.kt │ │ ├── location/LocationHelper.kt │ │ ├── route/RoutePlanService.kt │ │ ├── nav/NavigationManager.kt │ │ └── widget/RouteInfoPanel.kt │ └── res/ └── gradle/逐層說職責(zé)。MainActivity只做兩件事初始化地圖視圖把四個(gè)子模塊組裝起來MapViewHolder負(fù)責(zé)地圖生命周期包括創(chuàng)建、銷毀和相機(jī)控制LocationHelper封裝定位 SDK 的啟動(dòng)停止和權(quán)限申請對外只暴露一個(gè)“位置更新”回調(diào)RoutePlanService接收起終點(diǎn)坐標(biāo)發(fā)起路線規(guī)劃請求并解析結(jié)果NavigationManager是整個(gè)鏈路的調(diào)度者持有狀態(tài)機(jī)把路線數(shù)據(jù)交給地圖繪制同時(shí)接收導(dǎo)航事件回調(diào)RouteInfoPanel是底部信息面板展示剩余距離、剩余時(shí)間。這樣一個(gè)包里只有一個(gè)文件看著簡單但對于接入到自己項(xiàng)目里反而更方便——想刪掉語音播報(bào)就只動(dòng)NavigationManager想換定位策略就只改LocationHelper不需要在一千行的 Activity 里找邏輯。2.2 技術(shù)選型地圖 SDK、定位、路線規(guī)劃三者怎么協(xié)作先說清楚一個(gè)常見的誤解路線規(guī)劃不是地圖 SDK 的隱藏功能而是獨(dú)立的服務(wù)只是地圖 SDK 通常會(huì)附帶這個(gè)能力。這里的 NavMap SDK 泛指國內(nèi)常見的移動(dòng)端地圖 SDK接口細(xì)節(jié)可能略有差異但套路一致。工程里三者協(xié)作的時(shí)序是這樣的MainActivity創(chuàng)建地圖后先啟動(dòng)定位拿到當(dāng)前經(jīng)緯度作為路線起點(diǎn)用戶輸入終點(diǎn)后RoutePlanService帶著起終點(diǎn)坐標(biāo)去請求路線返回的路線數(shù)據(jù)被拆成兩個(gè)部分——一條用于地圖繪制的Polyline點(diǎn)串一組用于導(dǎo)航狀態(tài)機(jī)的“轉(zhuǎn)向指令”NavigationManager進(jìn)入導(dǎo)航中狀態(tài)后開始監(jiān)聽定位回調(diào)把真實(shí)位置投射到路線附近同時(shí)每走到一個(gè)拐彎點(diǎn)就觸發(fā)一次語音播報(bào)和面板更新。用戶點(diǎn)擊“開始導(dǎo)航” ↓ RoutePlanService.requestRoute(origin, destination) ↓ 返回 DriveRouteResult ↓ NavigationManager.startNavigation(route) ↓ 訂閱定位回調(diào) 啟動(dòng)模擬導(dǎo)航 ↓ 按路段索引推進(jìn)播報(bào) → 更新時(shí)間 → 判斷到達(dá)這段鏈路里最容易忽略的是“定位來源”和“路線坐標(biāo)”不是同一套坐標(biāo)系大部分地圖 SDK 內(nèi)部已經(jīng)做了轉(zhuǎn)換但如果你自己對接第三方定位 SDK就一定要確認(rèn)坐標(biāo)系是 GCJ-02 還是 WGS-84否則畫出來的路線會(huì)整體偏移一百米左右。2.3 生命周期管理導(dǎo)航對象跟著頁面走而不是跟著進(jìn)程走地圖是重資源SDK 都要求在 Activity 的onResume、onPause、onDestroy里調(diào)用對應(yīng)生命周期方法。工程里MapViewHolder做了這件事class MapViewHolder(private val mapView: MapView) { fun onResume() { mapView.onResume() locationHelper.start() } fun onPause() { mapView.onPause() locationHelper.stop() } fun onDestroy() { mapView.onDestroy() NavigationManager.instance.release() } }說明定位如果不在onPause停掉退出頁面后定位回調(diào)還會(huì)持續(xù)上報(bào)造成耗電和內(nèi)存泄漏。這里把LocationHelper.start/stop和地圖生命周期綁在一起可以確保頁面不可見時(shí)定位鏈路整體掛起。NavigationManager是單例但加了一個(gè)release()方法清理回調(diào)監(jiān)聽否則跨頁面持有 Activity 里的視圖引用是老項(xiàng)目最常見的崩潰來源之一。3. 核心鏈路代碼復(fù)盤定位、路線規(guī)劃與導(dǎo)航狀態(tài)機(jī)3.1 定位封裝從權(quán)限申請到坐標(biāo)回調(diào)LocationHelper是個(gè)典型封裝調(diào)用方不關(guān)心 SDK 細(xì)節(jié)只接一個(gè)回調(diào)class LocationHelper(private val context: Context) { private var listener: ((LatLng) - Unit)? null fun setOnLocationChanged(listener: (LatLng) - Unit) { this.listener listener } fun start() { if (!hasPermission()) { requestPermission() return } // 間隔1秒回調(diào)一次移動(dòng)超過10米也觸發(fā)一次 NavMapSDK.startLocation( interval 1000L, distanceFilter 10f, callback { latLng - listener?.invoke(latLng) } ) } fun stop() { NavMapSDK.stopLocation() } private fun hasPermission(): Boolean { return ContextCompat.checkSelfPermission( context, Manifest.permission.ACCESS_FINE_LOCATION ) PackageManager.PERMISSION_GRANTED } }參數(shù)說明interval是定位回調(diào)的時(shí)間間隔單位毫秒導(dǎo)航場景下 1000 毫秒是比較合適的折中太密耗電太疏會(huì)導(dǎo)致轉(zhuǎn)彎播報(bào)滯后distanceFilter表示移動(dòng)多少米才觸發(fā)下一次回調(diào)設(shè)成 10f 能過濾掉定位漂移帶來的抖動(dòng)。這里有個(gè)細(xì)節(jié)——沒有權(quán)限時(shí)我沒有立刻彈申請而是先返回權(quán)限結(jié)果通過onRequestPermissionsResult再調(diào)一次start()。很多新手在這里踩坑權(quán)限回調(diào)里直接判斷granted就繼續(xù)走忘記重新觸發(fā)定位啟動(dòng)。3.2 路線規(guī)劃把起終點(diǎn)坐標(biāo)變成一條可行駛的路線路線規(guī)劃核心代碼在RoutePlanServiceclass RoutePlanService { fun requestRoute(origin: LatLng, destination: LatLng, callback: (DriveRoute?) - Unit) { NavMapSDK.routeSearch().driverRoute( origin origin, destination destination, wayPoints emptyList(), strategy RouteStrategy.SHORTEST_TIME ) { result, error - if (error ! null) { callback(null) returndriverRoute } // 取第一條推薦路線 val route result?.routes?.firstOrNull() callback(route) } } }說明這里把“選路策略”直接寫死了是SHORTEST_TIME實(shí)際項(xiàng)目中我一般會(huì)把策略做成一個(gè)下拉選項(xiàng)讓用戶選“最快”“最短”“避開高速”。注意wayPoints參數(shù)傳空列表表示普通起終點(diǎn)導(dǎo)航如果用在外勤系統(tǒng)里這里可以塞途經(jīng)點(diǎn)列表實(shí)現(xiàn)多點(diǎn)配送路徑。路線規(guī)劃返回的DriveRoute不是一個(gè)孤立的點(diǎn)串它里面帶著latitudeList路線形狀點(diǎn)、stepList轉(zhuǎn)向指令列表、distance總長度、duration預(yù)計(jì)耗時(shí)。繪制到地圖上只取latitudeList但導(dǎo)航播報(bào)必須遍歷stepList兩者要區(qū)別使用拿到對象后別一股腦扔給MapAdapter。3.3 導(dǎo)航狀態(tài)機(jī)空閑、規(guī)劃中、導(dǎo)航中、到達(dá)導(dǎo)航最怕“狀態(tài)亂”。用戶反復(fù)點(diǎn)擊開始、退出、重新規(guī)劃時(shí)如果不用狀態(tài)機(jī)約束會(huì)出現(xiàn)語音重復(fù)播報(bào)、路線重疊繪制、定位還在跑但頁面已經(jīng)是結(jié)果頁等怪現(xiàn)象。工程里的NavigationManager用枚舉管理狀態(tài)enum class NavState { IDLE, // 無任務(wù) ROUTING, // 正在請求路線 NAVIGATING, // 導(dǎo)航中 ARRIVED // 已到達(dá) }class NavigationManager private constructor() { private var state NavState.IDLE fun startNavigation(route: DriveRoute) { if (state NavState.NAVIGATING) { stopNavigation() // 先回收舊任務(wù) } state NavState.NAVIGATING routeIndex 0 // 開始模擬導(dǎo)航每秒推進(jìn)一步 simulateNavigation(route) } fun stopNavigation() { state NavState.IDLE NavMapSDK.stopSimulate() listener?.onNavigationStopped() } }狀態(tài)機(jī)的意義在于任何外部操作都先判斷當(dāng)前狀態(tài)比如“開始導(dǎo)航”按鈕在ROUTING和NAVIGATING狀態(tài)下可以直接復(fù)用不需要針對每個(gè)入口加布爾開關(guān)。stopNavigation()里我加了一個(gè)先導(dǎo)動(dòng)作確保重復(fù)點(diǎn)擊時(shí)舊任務(wù)一定被清理不會(huì)出現(xiàn)兩個(gè)定時(shí)器同時(shí)在推前進(jìn)位置。4. 導(dǎo)航體驗(yàn)落地模擬導(dǎo)航、語音播報(bào)與實(shí)時(shí)糾偏4.1 模擬導(dǎo)航?jīng)]有真機(jī)也能演示完整跑線流程開發(fā)導(dǎo)航功能最頭疼的是測試——總不能在真機(jī)上真的開全程車。工程里做了一個(gè)很實(shí)用的設(shè)計(jì)模擬導(dǎo)航模式給定一個(gè)速度讓“假位置”沿路線勻速前進(jìn)。private fun simulateNavigation(route: DriveRoute) { val points route.latitudeList NavMapSDK.startSimulate( points points, speed 60f, // 模擬行駛速度 km/h onLocationTick { position - // position 是當(dāng)前在路線上的插值坐標(biāo) updateCamera(position) checkAndHandleTurn(position) updateRoutePanel(position) }, onArrived { state NavState.ARRIVED listener?.onArrived() } ) }說明startSimulate是地圖 SDK 提供的能力傳入整條路線點(diǎn)串SDK 會(huì)按照speed參數(shù)在點(diǎn)與點(diǎn)之間插值自動(dòng)產(chǎn)生平滑的位置上報(bào)。這里速度我給的是 60km/h適合演示如果你給調(diào)度車輛做軌跡預(yù)覽可以把速度調(diào)成 20km/h 看路口細(xì)節(jié)。onLocationTick回調(diào)里的checkAndHandleTurn(position)是播報(bào)的關(guān)鍵邏輯每次回調(diào)都判斷當(dāng)前位置距離下一個(gè)轉(zhuǎn)向點(diǎn)還有多遠(yuǎn)小于閾值就觸發(fā)播報(bào)并切換索引。4.2 到達(dá)判斷與糾偏不要只比“距離終點(diǎn)小于N米”到達(dá)判斷是導(dǎo)航功能里最容易被做假的點(diǎn)。簡單實(shí)現(xiàn)往往是“距離終點(diǎn)小于 50 米就算到達(dá)”但實(shí)際路網(wǎng)里終點(diǎn)的 GPS 信號可能漂移或者路線終點(diǎn)和車實(shí)際能停的位置有偏差導(dǎo)致導(dǎo)航還沒結(jié)束就彈出到達(dá)頁。工程里的到達(dá)邏輯參考了 SDK 自帶的狀態(tài)回調(diào)自己只做兜底private fun checkArrive(position: LatLng, route: DriveRoute) { val remainDistance route.stepList.sumOf { step - // 當(dāng)前路段剩余 后續(xù)路段總長 step.remainDistance(position) } // 同時(shí)滿足“剩余距離近似0”和“接近路線終點(diǎn)”兩個(gè)條件 if (remainDistance 30f position.distanceTo(route.destination) 60f) { state NavState.ARRIVED listener?.onArrived() } }邏輯說明兩個(gè)條件必須同時(shí)成立避免單個(gè)條件誤判。比如路線終點(diǎn)恰好在一片 GPS 信號遮擋區(qū)位置漂移讓“距終點(diǎn)”小于 60 米但剩余距離還很長此時(shí)不會(huì)誤報(bào)到達(dá)。反過來如果剩余距離已經(jīng)很小但真實(shí)位置離終點(diǎn)還有 100 米因?yàn)槁肪€結(jié)束點(diǎn)在輔路也不會(huì)提前結(jié)束。這套雙條件寫法在真實(shí)路測里比單一閾值穩(wěn)定得多。4.3 語音播報(bào)把轉(zhuǎn)向指令轉(zhuǎn)成可聽懂的路口提示語音播報(bào)在工程里沒有接大而全的 TTS 服務(wù)商而是通過NavigationManager內(nèi)部維護(hù)一個(gè)指令隊(duì)列到點(diǎn)后取出一條文案交給系統(tǒng) TTSprivate fun checkAndHandleTurn(position: LatLng) { val currentStep steps[routeIndex] if (position.distanceTo(currentStep.turnPoint()) 80f) { // 到播報(bào)點(diǎn)朗讀指令 tts.speak( 前方${currentStep.action}${currentStep.roadName}, finish { routeIndex listener?.onStepPassed(routeIndex) } ) } }參數(shù)說明turnPoint()是轉(zhuǎn)向指令對應(yīng)的導(dǎo)航點(diǎn)80f是提前播報(bào)的半徑車速越快這個(gè)值要適當(dāng)放大否則語音還沒念完路口已經(jīng)過去了。路口播報(bào)之后立刻滾動(dòng)routeIndex保證下一次播報(bào)用的是下一個(gè)轉(zhuǎn)向點(diǎn)。這里有個(gè)很容易漏的坑如果用戶中途偏航routeIndex必須重置否則播報(bào)永遠(yuǎn)停留在舊路線上——下一章的避坑手冊里我把這條列在了第一位。5. 避坑手冊權(quán)限、生命周期與偏航恢復(fù)的五個(gè)常見問題5.1 高頻故障現(xiàn)象、原因、解決現(xiàn)象原因解決地圖正常路線畫在地圖之外定位坐標(biāo)與地圖 SDK 坐標(biāo)系不一致常見于先接了一個(gè) WGS-84 定位源再疊加地圖確認(rèn)坐標(biāo)系統(tǒng)一用地圖 SDK 自帶的坐標(biāo)轉(zhuǎn)換接口或換用 SDK 內(nèi)置定位點(diǎn)擊開始導(dǎo)航后沒有任何反應(yīng)路線請求異步返回為空因?yàn)榻K點(diǎn)坐標(biāo)非法或超出服務(wù)區(qū)在RoutePlanService回調(diào)里先判斷route null彈 toast 并回退狀態(tài)為IDLE不要自動(dòng)跳到導(dǎo)航退出頁面后語音還在播報(bào)NavigationManager是單例生命周期沒有隨頁面銷毀在頁面onDestroy里調(diào)用stopNavigation()并注銷 TTS 監(jiān)聽模擬導(dǎo)航一到路口就“飛線”定位漂移把位置拉出路線更新相機(jī)時(shí)直接跟隨漂移點(diǎn)對onLocationTick的結(jié)果做路線吸附取路線投影點(diǎn)作為展示坐標(biāo)第二次進(jìn)入頁面出現(xiàn)兩個(gè)地圖Activity 重建時(shí)MapViewHolder沒有在onCreate里做狀態(tài)恢復(fù)在MapViewHolder保存經(jīng)緯度與縮放級別重建后調(diào)用mapView.onRestoreInstanceState恢復(fù)5.2 排查技巧用最小鏈路定位導(dǎo)航問題導(dǎo)航功能一旦出了問題最忌諱的是直接在真機(jī)上開著車看日志。我在跑這個(gè)工程時(shí)有一個(gè)固定流程先確認(rèn)“定位有沒有上報(bào)”再確認(rèn)“路線有沒有畫出來”最后才看導(dǎo)航狀態(tài)推進(jìn)。如果定位回調(diào)一直為空優(yōu)先查權(quán)限和 SDK Key如果路線能畫但不能開始導(dǎo)航查NavigationManager.state是否停在ROUTING如果模擬導(dǎo)航不動(dòng)查startSimulate的points是否被傳成空列表。一個(gè)更省事的做法是在NavigationManager里加一個(gè) debug 日志開關(guān)把每次狀態(tài)切換打印出來private fun logState(from: NavState, to: NavState) { if (BuildConfig.DEBUG) { Log.d(NavTag, state: $from - $to) } }做法說明狀態(tài)機(jī)的好處在這里體現(xiàn)得特別明顯——只要狀態(tài)切換是有序的鏈路就是健康的如果發(fā)現(xiàn)日志里出現(xiàn)NAVIGATING - NAVIGATING這樣自己切自己的情況說明有外部調(diào)用沒有經(jīng)過stopNavigation()直接定位到那個(gè)入口即可不用把整個(gè)頁面邏輯翻一遍。6. 二次開發(fā)把這套導(dǎo)航工程改成自己業(yè)務(wù)里的輪子拿到工程之后最常見的一個(gè)改造訴求是“把路線預(yù)覽放在下單詳情里”。做法是把第 3 章里規(guī)劃的鏈路從MainActivity中抽出來改成一組 fagment先請求路線畫一條不可交互的Polyline再根據(jù)用戶點(diǎn)擊進(jìn)入完整導(dǎo)航。這里有一個(gè)輕量改法只動(dòng)NavigationManager把它暴露的監(jiān)聽器擴(kuò)展成業(yè)務(wù)需要的回調(diào)集合interface NavEventObserver { fun onStepPassed(index: Int) {} fun onArrive() {} fun onProgress(distance: Float, duration: Long) {} }NavigationManager內(nèi)部維護(hù)一個(gè)Observer列表業(yè)務(wù)方按需注冊。比如配送 App 只需要onProgress來實(shí)時(shí)回傳位置不需要語音播報(bào)那就只實(shí)現(xiàn)這一個(gè)方法。這樣做比在單例里寫業(yè)務(wù)回調(diào)更干凈也方便單元測試——測試時(shí)可以注入一個(gè)假的NavEventObserver直接驗(yàn)證狀態(tài)機(jī)每一步推演是否正確。改造前先想清楚兩件事第一路線規(guī)劃是網(wǎng)絡(luò)請求回調(diào)線程可能不在主線程所有 UI 更新要自己post回主線程第二業(yè)務(wù)系統(tǒng)里如果已經(jīng)有自己的賬號體系和本地緩存不要把定位數(shù)據(jù)和路線數(shù)據(jù)也一股腦放進(jìn)去建議單獨(dú)建一個(gè)NavRepository只負(fù)責(zé)導(dǎo)航鏈路的數(shù)據(jù)存取這樣將來換地圖 SDK 時(shí)只改倉儲實(shí)現(xiàn)其他層完全不動(dòng)。我從這個(gè) Demo 里學(xué)到的最大一條教訓(xùn)是導(dǎo)航功能不要從“能不能走通”開始驗(yàn)證要從“狀態(tài)切換是否閉環(huán)”開始驗(yàn)證。從那以后每次接手類似項(xiàng)目我都先畫一遍狀態(tài)圖再跑一遍最小可運(yùn)行鏈路確認(rèn)IDLE - ROUTING - NAVIGATING - ARRIVED每一步都有日志可查才敢往上疊業(yè)務(wù)邏輯。這套笨辦法幫我少踩了好多坑希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取