监听导航事件

您可以使用本指南让应用能够监听和响应用户沿路线导航时发生的各种事件。本指南不介绍如何定义路线，仅介绍如何响应路线上的事件。

概览

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 当前道路贴合经度坐标。
course 当前方位角（以度为单位）。
speed 当前速度。
timestamp 当前读数日期/时间。

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

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

Swift

mapView.roadSnappedLocationProvider.startUpdatingLocation()

Objective-C

[_mapView.roadSnappedLocationProvider startUpdatingLocation];

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

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 事件来检测何时到达目的地。您可以调用 continueToNextDestinationWithCompletion()，然后重新启用导航功能，以恢复导航并前往下一个航点。您的应用必须在调用 continueToNextDestinationWithCompletion() 后重新启用导航功能。

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

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

Swift

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

Objective-C

- (void)navigator:(GMSNavigator *)navigator didArriveAtWaypoint:(GMSNavigationWaypoint *)waypoint {
  NSLog(@"You have arrived at: %@", waypoint.title);
  [_mapView.navigator continueToNextDestinationWithCompletion:^(GMSNavigationWaypoint *waypoint,
                                                                GMSRouteStatus status){
  }];
  _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;
}