監聽導覽事件

請參閱本指南，瞭解如何讓應用程式監聽及回應使用者沿路線導航時發生的各種事件。本指南不會說明如何定義路徑，只會說明如何回應路徑上的事件。

總覽

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 執行個體會顯示下列屬性：

地點屬性 說明
高度 目前海拔高度。
coordinate.latitude 目前道路對齊的緯度座標。
coordinate.longitude 目前路段的經度座標。
課程 目前的航向 (以度為單位)。
速度 目前速度。
時間戳記 目前讀數的日期/時間。

如要持續接收位置更新，請呼叫 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 屬性。這個值以秒為單位。如果未設定這項屬性，服務會使用一秒的預設值。

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 屬性 (值以公尺為單位)。如果未設定這項屬性，服務會使用一公尺的預設值。

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;
}