監聽導覽事件

您可以參考本指南，讓應用程式監聽並回應使用者沿著路線前進時發生的各種事件變化。本指南不會說明如何定義路線，只會說明如何回應沿路的事件。

總覽

iOS 版 Navigation SDK 會提供與使用者位置和路線沿途狀況相關的事件監聽器，以及重要時間和距離資料。在地圖的 View Controller 中，應用程式需要採用下列事件監聽器的通訊協定：GMSRoadSnappedLocationProviderListener 和 GMSNavigatorListener。

以下清單列出可用於導覽事件的事件監聽器方法：

查看程式碼

宣告符合必要通訊協定

在實作導覽方法之前，View Controller 必須採用下列通訊協定：

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 事件，偵測到達目的地時機。您可以呼叫 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 屬性。這個值以秒為單位。如果未設定此屬性，服務會使用一秒的預設值。

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