Navigation SDK for iOS 快速参考

Navigation SDK for iOS 可将 Google 地图精细导航功能添加到 iOS 应用中,并提供界面自定义和路线配置功能。它扩展了 Maps SDK for iOS,后者提供地图图层,也必须安装在应用中。

Navigation SDK for iOS:关键信息

  • 产品:Navigation SDK for iOS
  • 别名:Navigation SDK
  • 类别:路线
  • 平台:iOS
  • 运行位置:客户端(应用或浏览器代码)
  • 发布阶段:GA
  • 生命周期:有效
  • 概览:Navigation SDK for iOS 概览
  • 适用区域:有限。驾车和步行路线在大多数国家/地区都可用;路况、实时中断、两轮车、骑行、限速、红绿灯和停车标志因国家/地区而异。(覆盖范围详情)

Navigation SDK for iOS:何时使用

在以下情况下使用 Navigation SDK for iOS:

  • 您需要在自己的原生 iOS 应用中提供 Google 地图精细导航功能,以便用户无需切换应用。
  • 您需要在导航期间自定义导航界面、地图样式、镜头或布局,以契合您的品牌。
  • 您需要使用 Routes API 或 Route Optimization API 中的路线偏好设置、多个航点或路线令牌。
  • 您需要行程事件(位置、到达、路线变更、预计到达时间)或精细导航数据 Feed,才能实现自定义导航界面或 CarPlay。

在以下情况下,请勿使用 Navigation SDK for iOS:

Navigation SDK for iOS:设置

官方 Navigation SDK for iOS 软件包:

  • swift_package: https://github.com/googlemaps/ios-navigation-sdk (GoogleNavigation)

不应与 Navigation SDK for iOS 搭配使用的软件包:

  • cocoapods:GoogleNavigation。CocoaPods 分发自 11.0.0 版起已弃用,并于 2025 年 8 月 18 日进入维护模式。请改用 Swift Package Manager。

Navigation SDK for iOS:常见错误

  • 问题:由于 SDK 未停用 iOS 空闲计时器,屏幕会在导航期间变暗或关闭。修复:在导航时设置 UIApplication.shared.isIdleTimerDisabled = true。请参阅 /maps/documentation/navigation/ios-sdk/route。
  • 问题:SDK 的未来主要版本将使用高度计 (CMAltimeter),如果应用在 Info.plist 中没有 NSMotionUsageDescription,则会在初始化时崩溃。现在添加该键不会对当前行为产生任何影响。解决方法:将 NSMotionUsageDescription(隐私 - 动作使用说明)添加到 Info.plist。请参阅 /maps/documentation/navigation/ios-sdk/route。
  • 问题:Places SDK for iOS 未与 Navigation SDK 捆绑在一起(从 Places SDK 5.0 开始),因此缺少 Places 类。修复方法:单独安装 Places SDK for iOS,并使用与 Navigation SDK 相同的版本。请参阅 /maps/documentation/navigation/ios-sdk/xcode-setup。
  • 问题:如果应用的 travelMode 不是 driving 或 twoWheeler,则使用路线令牌设置目的地会失败,并显示 .travelModeUnsupported。解决方法:将 mapView.travelMode 设置为 .driving 或 .twoWheeler。查看 resolvedParameters.travelMode,了解路线使用的模式。请参阅 /maps/documentation/navigation/ios-sdk/route-customizations。

Navigation SDK for iOS:旧版和已弃用的功能

  • CocoaPods 分发:自 2026 年 8 月 6 日起弃用。替代方案:Swift Package Manager。症状:自 2025 年 8 月 18 日起进入维护模式。2026 年第 2 季度之后,将不再发布新的 CocoaPods 版本。请参阅迁移指南。
  • GMSNavigator setDestinations:callback:、setDestinations:routingOptions:callback:、setDestinations:routeToken:callback: (GMSRouteStatusCallback):自 2026 年 11 月 2 日起弃用。更换:setDestinations:completionHandler:、setDestinations:routingOptions:completionHandler:、setDestinationsWithToken:completionHandler: (GMSNavigationRouteCompletionHandler)。
  • GMSServices 实例属性 appCheckTokenProvider:自 2026 年 9 月 24 日起已弃用。替代项:类属性 GMSServices.appCheckTokenProvider (+[GMSServices setAppCheckTokenProvider:])。症状:在 11.1.0 中,通过 GMSServices.sharedServices() 配置 App Check 失败。请参阅迁移指南。
  • GMSNavigator continueToNextDestination:自 2026 年 4 月 7 日起已弃用。换货:GMSNavigator continueToNextDestinationWithCompletion:。
  • GMSUISettings showsTrafficLights 和 showsStopSigns:自 2026 年 8 月 6 日起已停用。替代方案:无需替代方案;导航期间默认显示红绿灯和停车标志。
  • .terrain 导航期间的地图类型:自 2026 年 8 月 6 日起停用。替换:.normal (kGMSTypeNormal)、.satellite 或 .hybrid 地图类型。
  • GMSNavigatorDelegate 和 GMSRoadSnappedLocationProviderDelegate 协议:自 2021 年 5 月 13 日起停用。替代项:GMSNavigatorListener 和 GMSRoadSnappedLocationProviderListener(使用 -addListener: 添加;在 GMSNavigator 上设置 timeUpdateThreshold 和 distanceUpdateThreshold)。请参阅迁移指南。

Navigation SDK for iOS 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。

Navigation SDK for iOS:地图样式设置

Navigation SDK for iOS:导航