监听导航事件

通过本指南，您可以让应用监听并响应随着用户沿着路线导航而发生变化的各种事件。本指南不介绍如何定义路线，只介绍如何响应路线上的事件。

概览

Navigation SDK for iOS 可为您提供与用户位置和路线沿途情况相关联的监听器，以及重要的时间和距离数据。在地图的视图控制器上，您的应用需要采用以下监听器的协议：GMSRoadSnappedLocationProviderListener 和 GMSNavigatorListener。

以下列表显示了可用于导航事件的监听器方法：

查看代码

声明符合所需协议

在实现导航方法之前，视图控制器必须采用以下协议：

Swift

class ViewController: UIViewController, GMSNavigatorListener,
GMSRoadSnappedLocationProviderListener {

Objective-C

@interface ViewController () <GMSNavigatorListener,
GMSRoadSnappedLocationProviderListener>

@end

采用导航协议后，将监听器设置为视图控制器。例如，您可以将以下代码添加到 viewDidLoad() 方法中。

Swift

mapView.navigator?.add(self) mapView.roadSnappedLocationProvider?.add(self)

Objective-C

[_mapView.navigator addListener:self]; [_mapView.roadSnappedLocationProvider
addListener:self];

接收或停止接收位置信息更新

必须有位置信息更新，才能在地图上显示用户的进度。

location 实例公开了以下属性：

地点属性 说明
altitude 当前海拔。
coordinate.latitude 当前的道路贴靠纬度坐标。
coordinate.longitude 当前的道路贴靠经度坐标。
课程 当前航向（以度为单位）。
速度 当前速度。
时间戳 当前读数的日期/时间。

如需接收持续位置信息更新，请调用 mapView.roadSnappedLocationProvider.startUpdatingLocation，并使用 GMSRoadSnappedLocationProviderListener 处理 didUpdateLocation 事件。

以下示例展示了如何调用 startUpdatingLocation：

Swift

mapView.roadSnappedLocationProvider.startUpdatingLocation()

Objective-C

[_mapView.roadSnappedLocationProvider startUpdatingLocation];

以下代码会创建一个用于处理 didUpdateLocation 事件的 GMSRoadSnappedLocationProviderListener。

Swift

func locationProvider(_ locationProvider: GMSRoadSnappedLocationProvider,
didUpdate location: CLLocation) { print("Location: \(location.description)") }

Objective-C

-   (void)locationProvider:(GMSRoadSnappedLocationProvider *)locationProvider
    didUpdateLocation:(CLLocation *)location { NSLog(@"Location: %@",
    location.description); }

如需在应用在后台运行时接收位置信息更新，请将 allowsBackgroundLocationUpdates 设置为 true：

Swift

mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true

Objective-C

 _mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;

检测到达事件

您的应用使用 didArriveAtWaypoint 事件检测何时到达目的地。您可以调用 continueToNextDestination()，然后重新启用导航，以便恢复导航并前往下一个航点。您的应用必须在调用 continueToNextDestination() 后重新启用引导。

应用调用 continueToNextDestination 后，导航器将不再拥有与上一个目的地相关的数据。如果您想分析路线航段的相关信息，则必须先从导航器中检索这些信息，然后再调用 continueToNextDestination()。

以下代码示例展示了处理 didArriveAtWaypoint 事件的方法：

Swift

func navigator(_ navigator: GMSNavigator, didArriveAt waypoint:
GMSNavigationWaypoint) { print("You have arrived at: \(waypoint.title)")
mapView.navigator?.continueToNextDestination()
mapView.navigator?.isGuidanceActive = true }

Objective-C

-   (void)navigator:(GMSNavigator *)navigator
    didArriveAtWaypoint:(GMSNavigationWaypoint *)waypoint { NSLog(@"You have
    arrived at: %@", waypoint.title); [_mapView.navigator
    continueToNextDestination]; _mapView.navigator.guidanceActive = YES; }

接收路线变更更新

如需在路线发生变化时接收通知，请创建一个用于处理 navigatorDidChangeRoute 事件的方法。您可以使用 GMSNavigator 的 routeLegs 和 currentRouteLeg 属性访问新路线。

Swift

func navigatorDidChangeRoute(_ navigator: GMSNavigator) { print("The route has
changed.") }

Objective-C

-   (void)navigatorDidChangeRoute:(GMSNavigator *)navigator { NSLog(@"The route
    has changed."); }

接收目的地到达时间更新

如需接收持续更新的目的地到达时间，请创建一个用于处理 didUpdateRemainingTime 事件的方法。time 参数提供到达下一个目的地所需的预计时间（以秒为单位）。

Swift

func navigator(_ navigator: GMSNavigator, didUpdateRemainingTime time:
TimeInterval) { print("Time to next destination: \(time)") }

Objective-C

-   (void)navigator:(GMSNavigator *)navigator
    didUpdateRemainingTime:(NSTimeInterval)time { NSLog(@"Time to next
    destination: %f", time); }

如需设置到下一个目的地的预计时间最小变化值，请在 GMSNavigator 上设置 timeUpdateThreshold 属性。此值以秒为单位。如果未设置此属性，服务将使用默认值 1 秒。

Swift

navigator?.timeUpdateThreshold = 10

Objective-C

navigator.timeUpdateThreshold = 10;

接收到达目的地的距离更新

如需接收持续更新的距离目的地信息，请创建一个用于处理 didUpdateRemainingDistance 事件的方法。distance 参数提供到下一个目的地的预计距离（以米为单位）。

Swift

func navigator(_ navigator: GMSNavigator, didUpdateRemainingDistance distance:
CLLocationDistance) { let miles = distance * 0.00062137 print("Distance to next
destination: \(miles) miles.") }

Objective-C

-   (void)navigator:(GMSNavigator *)navigator
    didUpdateRemainingDistance:(CLLocationDistance)distance { double miles =
    distance * 0.00062137; NSLog(@"%@", [NSString stringWithFormat:@"Distance to
    next destination: %.2f.", miles]); }

如需设置到下一目的地的预计距离的最小变化值，请在 GMSNavigator 上设置 distanceUpdateThreshold 属性（值以米为单位）。如果未设置此属性，服务将使用默认值 1 米。

Swift

navigator?.distanceUpdateThreshold = 100

Objective-C

navigator.distanceUpdateThreshold = 100;

接收路况动态

如需接收剩余路线的交通流量持续更新，请创建一个用于处理 didUpdateDelayCategory 事件的方法。调用 delayCategoryToNextDestination 会返回 GMSNavigationDelayCategory，该值的范围为 0 到 3。对此类别的更新基于应用用户的当前位置。如果没有流量数据，GMSNavigationDelayCategory 会返回 0。数字 1-3 表示流量从小到大。

Swift

func navigator(_ navigator: GMSNavigator, didUpdate delayCategory:
GMSNavigationDelayCategory) { print("Traffic flow to next destination:
\(delayCategory)") }

Objective-C

-   (void)navigator:(GMSNavigator *)navigator
    didUpdateDelayCategory:(GMSNavigationDelayCategory)delayCategory {
    NSLog(@"Traffic flow to next destination: %ld", (long)delayCategory); }

GMSNavigationDelayCategory 属性公开了以下延迟级别：

延迟类别 说明
GMSNavigationDelayCategoryNoData 0 - 不可用，没有流量数据，或者：
路线。
GMSNavigationDelayCategoryHeavy 1 - 严重。
GMSNavigationDelayCategoryMedium 2 - 中等。
GMSNavigationDelayCategoryLight 3 - 轻度。

接收超速更新

如需在驾驶员超速时接收更新，请创建一个用于处理 didUpdateSpeedingPercentage 事件的方法。

Swift

// Listener to handle speeding events. func navigator( _ navigator:
GMSNavigator, didUpdateSpeedingPercentage percentageAboveLimit: CGFloat ) {
print("Speed is \(percentageAboveLimit) above the limit.") }

Objective-C

// Listener to handle speeding events. - (void)navigator:(GMSNavigator
*)navigator didUpdateSpeedingPercentage:(CGFloat)percentageAboveLimit {
NSLog(@"Speed is %f percent above the limit.", percentageAboveLimit); }

更改建议的光效模式

如需接收照明估算变化的更新，请创建一个用于处理 didChangeSuggestedLightingMode 事件的方法。

Swift

// Define a listener for suggested changes to lighting mode. func navigator(_
navigator: GMSNavigator, didChangeSuggestedLightingMode lightingMode:
GMSNavigationLightingMode) { print("Suggested lighting mode has changed:
\(String(describing: lightingMode))")

 // Make the suggested change. mapView.lightingMode = lightingMode }

Objective-C

// Define a listener for suggested changes to lighting mode.
-(void)navigator:(GMSNavigator *)navigator didChangeSuggestedLightingMode:
(GMSNavigationLightingMode)lightingMode { NSLog(@"Suggested lighting mode has
changed: %ld", (long)lightingMode);

 // Make the suggested change. _mapView.lightingMode = lightingMode; }