Navigation SDK for Android 快速参考

Navigation SDK for Android 可为 Android 应用添加 Google 地图精细导航功能,并支持界面自定义和路线配置。它包含 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 地图精细导航功能,这样用户就无需切换到其他应用。
  • 您需要自定义导航界面以契合您的品牌,或构建自定义导航体验。
  • 您需要为驾车、步行、骑行或两轮车出行提供应用内导航。
  • 您需要通过向 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 的 build 最终会产生重复的 Maps SDK 副本。修复方法:从所有依赖项(Gradle 配置排除项或 Maven 排除项)中排除 com.google.android.gms:play-services-maps,并移除所有直接 Maps SDK 依赖项。请参阅 /maps/documentation/navigation/android-sdk/android-studio-setup。
  • 问题:Navigation SDK 8.0 及更高版本会声明 minAndroidGradlePluginVersion=9.0.1,因此使用较低 AGP 版本的 build 会失败。修复方法:在使用 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。症状:在 Navigation SDK v8.0.0 中已废弃。请参阅迁移指南。
  • setLocationMarkerEnabled(NavigationView 和 SupportNavigationFragment):自 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(私有代码库,v4.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:导航