GMSNavigator 类参考文档

GMSNavigator 类参考

概览

这是 Google Navigation SDK for iOS 的主类,提供了用于控制目的地导航以及访问路线和进度信息的方法。

此类不支持子类化。

此类不是线程安全的。所有方法都必须从主线程调用。

公开成员函数

(void) - addListener:
 添加监听器。
(BOOL)- removeListener:
 移除监听器。
(void) - setDestinations:callback:
 设置多个用于导航的目的地,替换之前设置的任何目的地。
(void) - setDestinations:routingOptions:callbacksetDestinations:routingOptions:callback:
 设置多个用于导航的目的地,替换之前设置的任何目的地。
(void) - setDestinations:routeToken:callback:
 设置多个导航目的地,使用路线令牌在预计算的路线上导航。
(void) - getRouteInfoForDestination:withRoutingOptions:callback:
 根据路由策略返回路线信息:默认的最佳路线或较短的路线。
(可为 null 的 GMSNavigationWaypoint *)- continueToNextDestination
 已弃用。
(void) - clearDestinations
 清除之前设置的所有目的地,并从地图中移除所有计算的路线。
(NSTimeInterval)- timeToWaypoint
 返回给定航点的预计时间,或者如果航点不是当前路线的一部分,则返回 CLTimeIntervalMax。
(CLLocationDistance)- distanceToWaypoint:
 返回与指定航点的估算距离,或者如果航点不是当前路线的一部分,则返回 CLLocationDistanceMax。
(void) - setTransactionIDs:errorHandler:
 设置当前导航会话期间适用于导航事件的持续事务 ID 并将其记录到服务器。

属性

BOOL avoidsHighways
 生成前往目的地的路线时是否避开高速公路。
BOOL avoidsTolls
 生成前往目的地的路线时是否避开收费路段。
BOOL avoidsFerries
 生成前往目的地的路线时是否避开轮渡。
GMSNavigationLicensePlateRestriction *licensePlateRestriction
 使用当前驾照的最后一位数和国家/地区代码来设置牌照限制。
BOOL guidanceActive
 当前是否启用了精细导航。
BOOL stopGuidanceAtArrival
 调用 -navigator:didArriveAtWaypoint: 时,是否应自动停止导航。
NSTimeInterval timeUpdateThreshold
 预计到达下一目的地所需的时间的最小变化将触发调用 navigator:didUpdateRemainingTime: 方法。
CLLocationDistancedistanceUpdateThreshold
 与下一个目的地的预计距离的最小变化值会触发调用 navigator:didUpdateRemainingDistance: 方法。
NSTimeInterval timeToNextDestination
 返回到达下一个目的地的预计时间。
CLLocationDistancedistanceToNextDestination
 返回与下一个目的地的预计距离。
GMSNavigationDelayCategorydelayCategoryToNextDestination
 返回下一个目的地的延迟类别。
GMSRouteLeg *currentRouteLeg
 旅程的当前路程。
NSArray<GMSRouteLeg * >*routeLegs
 路线路程的数组,其中每条路程对应一个设定的目的地。
GMSPath *traveledPath
 用户在最近一次指导会话中所走的路径,定义为上次指导活动设置为“是”的时间。
GMSNavigationVoiceGuidancevoiceGuidance
 确定是否应为路况和精细导航提醒启用语音导航。
GMSVoiceGuidanceAudioDeviceTypeaudioDeviceType
 决定可以通过哪些音频设备播放语音导航。
BOOL vibrationEnabled
 确定在播放语音提醒时设备是否也应振动。
BOOL sendsBackgroundNotifications
 确定当应用在后台运行时,是否会显示包含导航信息的 UILocalNotifications。
GMSNavigationLightingModesuggestedLightingMode
 系统根据一天当中的时段和设备所在的位置推荐的光照模式。
BOOL shouldDisplayPrompts
 决定是否应显示路况、更优路线和事故等提示。
GMSNavigationSpeedAlertOptions *speedAlertOptions
 GMSNavigationSpeedAlertOptions,用于自定义 GMSNavigationSpeedAlertSeverity 的触发阈值。

(请注意,这些并非成员函数。)

类型定义符 void(^GMSRouteStatusCallback)(GMSRouteStatusrouteStatus)GMSRouteStatus
 当找到从设备位置到所提供目的地的路线,或因 RouteStatus 指明的原因找不到路线时调用。
类型定义符 void(^GMSRouteInfoCallback )(GMSNavigationRouteInfo *_Nullable 路由信息)GMSNavigationRouteInfo
 在计算到指定航点的路线信息(预计到达时间和距离)时调用。
类型定义符 void(^GMSNavigationTransactionIDErrorHandler )(NSError *错误)
 在通过 setTransactionID 设置交易 ID 失败时调用。

成员函数文档

- (void) addListener: (id<GMSNavigatorListener>) 监听器

添加监听器。

监听器通过弱引用保持。

参数:
监听器符合 GMSNavigatorListener 协议的对象。
- (BOOL) removeListener: (id<GMSNavigatorListener>) 监听器

移除监听器。

参数:
监听器符合 GMSNavigatorListener 协议的对象。
返回
如果监听器已移除,则返回 YES。如果对象不是监听器,则返回 NO。
- (void) setDestinations: (NSArray< GMSNavigationWaypoint * > *) 目标平台
回调: (GMSRouteStatusCallback) 回调函数

设置多个用于导航的目的地,替换之前设置的任何目的地。

如果找到从设备位置到指定目的地的路线,将使用 GMSRouteStatusOK 调用所提供的回调。如果在找到路线之前设置了新目的地,则系统将取消请求,并使用 GMSRouteStatusCanceled 调用回调。如果由于任何其他原因而找不到路线,则使用相应的错误状态调用回调函数。

回调将始终在主队列中异步分派。

- (void) setDestinations: (NSArray< GMSNavigationWaypoint * > *) 目标平台
routingOptions: (GMSNavigationRoutingOptions *) routingOptions
回调: (GMSRouteStatusCallback) 回调函数

设置多个用于导航的目的地,替换之前设置的任何目的地。

返回的路线是使用路线选项计算的。

参数:
目的地目的地航点数组。
routingOptions影响路由逻辑(路由策略)的选项。
callback当找到从消费者所在位置到提供的目的地的路线,或由于 RouteStatus 指示的原因找不到路线时调用。
- (void) setDestinations: (NSArray< GMSNavigationWaypoint * > *) 目标平台
routeToken: (NSString *)  routeToken
回调: (GMSRouteStatusCallback) 回调函数

设置多个导航目的地,使用路线令牌在预计算的路线上导航。

路线将保持不变,但驾驶员出发位置和道路/路况信息将以模数形式发生变化。系统仍会根据令牌中编码的路由选项重新路由。

当您使用路线令牌启动导航会话时,仅支持 GMSNavigationTravelModeDrivingGMSNavigationTravelModeTwoWheeler。通过设置 travelMode 配置出行方式。如果当前出行方式不受支持,调用将失败,并且回调中会返回 GMSRouteStatusTravelModeUnsupported

参数:
目的地目的地航点数组应与为获取路线令牌而提供给 RoutesPreferred API 的目的地相同。
routeTokenRoutesPreferred API 返回的路线令牌字符串。RoutesPreferred API 中指定的转送选项在此路线令牌中进行编码,并将用于在发生重新规划路线时重新生成预计算的路线或新路线。
callback当找到从消费者所在位置到提供的目的地的路线,或由于 RouteStatus 指示的原因找不到路线时调用。
- (void) getRouteInfoForDestination: (GMSNavigationWaypoint *) 目标位置
withRoutingOptions: (GMSNavigationRoutingOptions *) routingOptions
回调: (GMSRouteInfoCallback) 回调函数

根据路由策略返回路线信息:默认的最佳路线或较短的路线。

此方法仅适用于由 Google 按交易结算的移动服务客户。如果项目缺少调用此 API 的权限,则返回“nil”值。

参数:
目标账号目的地航点。
routingOptions用于提取路线信息的选项。由于此方法会返回所有路由策略的路由信息,因此系统会忽略路由策略和备选路由策略。
callback收到路线信息时调用的回调。

已弃用。

改用新的目的地列表调用其中一个 -setDestinations:... 方法。

从当前目的地列表中弹出第一个目的地。此次通话结束后,指引将前往下一个目的地(如果有的话)。

返回
航点导航现在正朝向航点,如果不再有航点,则返回 nil。
注意
此 API 已弃用。请改用 -setDestinations:... 方法之一。

清除之前设置的所有目的地,并从地图中移除所有计算的路线。

如果导航已启用,系统会自动停止导航。

- (NSTimeInterval) timeToWaypoint (GMSNavigationWaypoint *) 航点

返回给定航点的预计时间,或者如果航点不是当前路线的一部分,则返回 CLTimeIntervalMax。

当导航处于启用状态时,系统会根据当前的设备位置更新此值。

如果提供的路标不是当前路线中的目的地,则返回 CLTimeIntervalMax。

- (CLLocationDistance) distanceToWaypoint: (GMSNavigationWaypoint *) 航点

返回与指定航点的估算距离,或者如果航点不是当前路线的一部分,则返回 CLLocationDistanceMax。

当导航功能处于启用状态时,系统会根据当前的设备位置更新此设置。

如果提供的航点不是当前路线中的目的地,则返回 CLLocationDistanceMax。

- (void) setTransactionIDs: (NSArray< NSString * > *) transactionIDs
errorHandler: (可为 null 的 GMSNavigationTransactionIDErrorHandler errorHandler

设置当前导航会话期间适用于导航事件的持续事务 ID 并将其记录到服务器。

交易 ID 将在导航会话结束时清除。此方法仅适用于由 Google 按交易结算的移动服务客户。如果项目缺少调用此 API 的权限,则返回“nil”值。

参数:
transactionIDs适用于当前导航会话的事务 ID。每笔可结算交易的交易 ID 都必须是唯一的。单个交易 ID 必须至少包含一个字符,最多 64 个字符。当交易结束(但会话仍在进行)时,列表可以为空。
errorHandler如果在事务 ID 无效时发生错误,将在主线程上异步调用的块。

- (typedef void(^ GMSRouteStatusCallback)(GMSRouteStatusrouteStatus) [related]

当找到从设备位置到所提供目的地的路线,或因 RouteStatus 指明的原因找不到路线时调用。

- (typedef void(^ GMSRouteInfoCallback)(GMSNavigationRouteInfo *_Nullable 路由信息) [related]GMSNavigationRouteInfo

在计算到指定航点的路线信息(预计到达时间和距离)时调用。

参数:
routeInfo到指定目的地的路线信息。如果计算失败,则为 nil。
- (typedef void(^ GMSNavigationTransactionIDErrorHandler)(NSError *error)) [related]

在通过 setTransactionID 设置交易 ID 失败时调用。

如需了解详情,请参阅 API 的文档。


属性说明

- (BOOL) avoidsHighways [read, write, assign]

生成前往目的地的路线时是否避开高速公路。

默认为 NO。

- (BOOL) avoidsTolls [read, write, assign]

生成前往目的地的路线时是否避开收费路段。

默认为 NO。

- (BOOL) avoidsFerries [read, write, assign]

生成前往目的地的路线时是否避开轮渡。

默认值为 YES。

使用当前驾照的最后一位数和国家/地区代码来设置牌照限制。

这使我们能够根据车牌号确定某些类型的道路限制。这仅适用于设置此值后进行的 setDestinations 调用。理想情况下,您应在获取导航器后立即设置此属性。

如果没有车牌限制,则设置为 nil。默认值为 nil。

- (BOOL) guidanceActive [read, write, assign]

当前是否启用了精细导航。

如果 navigationActive 为 YES,但当前没有可用路线,则系统会在有路线可用时启动导航。如果调用 clearDestinations 或到达航点,则该属性将设置为 NO。

- (BOOL) stopGuidanceAtArrival [read, write, assign]

调用 -navigator:didArriveAtWaypoint: 时,是否应自动停止导航。

如果选择“否”,在抵达后仍会继续显示导航页眉和页脚。导航标题将继续显示最后一个导航步骤,导航页脚将继续更新剩余时间和距离,直到达到时间/距离为 0。此外,-navigator:didUpdateRemainingTime 和 -navigator:didUpdateRemainingDistance 将会继续更新。将guidanceActive明确设置为“否”,以停止导航和剩余时间/距离更新。

如果设为“是”,系统会在您抵达时自动将“guidanceActive”设为“否”。

默认值为 YES。

- (NSTimeInterval) timeUpdateThreshold [read, write, assign]

预计到达下一目的地所需的时间的最小变化将触发调用 navigator:didUpdateRemainingTime: 方法。

如果将此值设为 NSTimeIntervalMax,则将停用时间更新回调。如果设置为负值,则将使用 1 秒的默认阈值。默认值为 1 秒。

注意
如果没有实现 navigator:didUpdateRemainingTime: 的监听器,系统会忽略此值。
- (CLLocationDistance) distanceUpdateThreshold [read, write, assign]

与下一个目的地的预计距离的最小变化值会触发调用 navigator:didUpdateRemainingDistance: 方法。

如果设为 CLLocationDistanceMax,则将停用距离更新回调。如果设为负值,则将使用一电表的默认阈值。默认值为一米。

注意
如果没有实现 navigator:didUpdateRemainingDistance: 的监听器,系统会忽略此值。
- (NSTimeInterval) timeToNextDestination [read, assign]

返回到达下一个目的地的预计时间。

当导航功能处于启用状态时,系统会根据当前的设备位置更新此设置。

如果没有可用的路线,则返回 CLTimeIntervalMax。

- (CLLocationDistance) distanceToNextDestination [read, assign]

返回与下一个目的地的预计距离。

当导航功能处于启用状态时,系统会根据当前的设备位置更新此设置。

如果没有路线,则返回 CLLocationDistanceMax。

- (GMSNavigationDelayCategory) delayCategoryToNextDestination [read, assign]

返回下一个目的地的延迟类别。

当导航功能处于启用状态时,系统会根据当前的设备位置更新此设置。

如果没有路线可用或路况数据不可用,则返回 GMSNavigationDelayCategoryNoData。

- (GMSRouteLeg*) currentRouteLeg [read, assign]

旅程的当前路程。

GMSRouteLeg将其起始位置设为设备最近的已知(道路贴靠)位置。

- (NSArray<GMSRouteLeg *>*) routeLegs [read, assign]

路线路程的数组,其中每条路程对应一个设定的目的地。

- (GMSPath*) traveledPath [read, assign]

用户在最近一次指导会话中所走的路径,定义为上次指导活动设置为“是”的时间。

该路径包含由 GMSRoadSnappedLocationProvider 返回的道路贴靠位置,经过简化后可生成线段。

注意
系统会轮询客户端以获取 GPS 信号,以获取位置数据。GPS 信号不佳会导致进一步的内插,从而可能生成不太精确的路线。如果导航从未启动,则此路径为空。
- (GMSNavigationVoiceGuidance) voiceGuidance [read, write, assign]

确定是否应为路况和精细导航提醒启用语音导航。

默认值为 GMSNavigationVoiceGuidanceAlertsAndGuidance。

决定可以通过哪些音频设备播放语音导航。

默认值为 GMSVoiceGuidanceAudioDeviceTypeBluetooth。

- (BOOL) vibrationEnabled [read, write, assign]

确定在播放语音提醒时设备是否也应振动。

- (BOOL) sendsBackgroundNotifications [read, write, assign]

确定当应用在后台运行时,是否会显示包含导航信息的 UILocalNotifications。

默认值为 YES。

系统根据一天当中的时段和设备所在的位置推荐的光照模式。

- (BOOL) shouldDisplayPrompts [read, write, assign]

决定是否应显示路况、更优路线和事故等提示。

默认值为 YES。

GMSNavigationSpeedAlertOptions,用于自定义 GMSNavigationSpeedAlertSeverity 的触发阈值。

您可以使用此属性来自定义次要提醒和重大提醒的速度提醒触发阈值(以百分比表示)。您还可以使用此方法自定义主要速度提醒的基于时间的触发阈值。

将 nil 设置为 nil,您将不会收到任何超速 Feed 数据,并且 NavSDK 的默认速度提醒会显示:当速度超过 5 英里/小时或 10 公里/小时时,显示红色文字;当速度超过 10 英里/小时或 20 公里/小时时,显示白色文字和红色背景。