Navigation SDK for Android 快速參考

Navigation SDK for Android 可將 Google 地圖即時路況導航功能加入 Android 應用程式,並提供 UI 自訂和路線設定功能。其中包含 Maps SDK 地圖圖層,因此使用該程式庫的應用程式無法同時包含 Maps SDK for Android。

Navigation SDK for Android:重要資訊

  • 產品:Navigation SDK for Android
  • 又稱:Navigation SDK
  • 類別:路徑
  • 平台:Android
  • 執行位置:用戶端 (應用程式或瀏覽器程式碼)
  • 推出階段:GA
  • 生命週期:有效
  • 總覽:Navigation SDK for Android 總覽

Navigation SDK for Android:使用時機

在下列情況下使用 Navigation SDK for Android:

  • 您需要在自己的 Android 應用程式中,提供 Google 地圖即時路況導航功能,讓使用者不必切換至其他應用程式。
  • 您需要自訂導航 UI,使其符合品牌形象,或打造自訂導航體驗。
  • 您需要應用程式內導航功能,用於開車、步行、騎單車或兩輪車。
  • 您必須將路徑權杖傳遞至 SDK,才能沿著使用 Routes API 規劃的路徑導航。

請勿在下列情況使用 Navigation SDK for Android:

Navigation SDK for Android:設定

官方 Navigation SDK for Android 套件:

  • maven:com.google.android.libraries.navigation:navigation

Navigation SDK for Android:常見錯誤

  • 問題:Navigation SDK 已隨附 Maps SDK。如果版本直接或透過傳遞依附元件提取 play-services-maps,就會產生重複的 Maps SDK 副本。修正方式:從所有依附元件中排除 com.google.android.gms:play-services-maps (Gradle 設定排除或 Maven 排除),並移除任何直接的 Maps SDK 依附元件。請參閱 /maps/documentation/navigation/android-sdk/android-studio-setup。
  • 問題:Navigation SDK 8.0 以上版本會宣告 minAndroidGradlePluginVersion=9.0.1,因此使用舊版 AGP 的建構作業會失敗。修正方式:使用 8.0 以上版本建構前,請先升級至 AGP 9.0.1、Gradle 9.1.0 和 Kotlin 2.3.0。請參閱 /maps/documentation/navigation/android-sdk/kotlin-compatibility-migration。
  • 問題:使用 NavigationFragment 時直接呼叫 NavigationView 生命週期方法,或未按照 NavigationView 順序呼叫,會導致錯誤。修正方式:使用 NavigationFragment 管理生命週期回呼。如果使用 NavigationView,請嚴格按照順序轉送生命週期方法。請參閱 /maps/documentation/navigation/android-sdk/nav-map-interactions-best-practices。
  • 問題:使用者必須接受 Google 導航服務條款,才能使用導航功能。修正方式:讓 SDK 在首次叫用導覽器時顯示提示,或使用 TermsAndConditionsCheckOption/NavigationApi.showTermsAndConditionsDialog 提早顯示對話方塊 (例如在註冊期間)。請參閱 /maps/documentation/navigation/android-sdk/route。

Navigation SDK for Android:舊版和已淘汰的功能

  • Waypoint fromLatLng() 和 fromPlaceId():自 2021 年 5 月 10 日起停用。替代項目:Waypoint.builder() (Waypoint.Builder)。症狀:已在 3.0 版中移除;呼叫不會針對 3.0 以上版本進行編譯。請參閱遷移指南。
  • SupportNavigationFragment:自 2026 年 10 月 1 日起淘汰。替代方案:NavigationFragment。Symptom:已在 Navigation SDK 8.0.0 版中淘汰。請參閱遷移指南。
  • NavigationView 和 SupportNavigationFragment 上的 setLocationMarkerEnabled:自 2023 年 7 月 7 日起停用。替代方案:GoogleMap.setMyLocationEnabled。症狀:5.0.0 版已移除 (4.1 版已淘汰);呼叫無法針對 5.0 以上版本進行編譯。
  • DisplayOptions showTrafficLights 和 showStopSigns:自 2026 年 10 月 1 日起停用。替代方案:不需替代方案,導航時一律會顯示交通號誌和停止標誌。症狀:呼叫這些方法時,無法針對 8.0.0 版進行編譯。
  • Maven 構件 com.google.android.maps:navsdk (私人存放區,4.x 版) 和 AAR 套件下載:自 2023 年 7 月 7 日起停用。替代項目:google() Maven 存放區中的 com.google.android.libraries.navigation:navigation。症狀:5.0 以上版本僅在 Google Maven 上以 com.google.android.libraries.navigation:navigation 形式提供,不再發布 AAR 套件。請參閱遷移指南。

Navigation SDK for Android 的用途

請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。

Navigation SDK for Android:地圖

Navigation SDK for Android:地圖註解

Navigation SDK for Android:地圖樣式

Navigation SDK for Android:導航