監聽導覽事件

應用程式可以監聽使用者沿著路線導覽時發生的事件。

總覽

請使用以下介面監聽導覽事件：

查看程式碼

偵測抵達目的地

此處的目的地是指最終的目的地或路線控點。如要偵測抵達時間，請呼叫 Navigator.addArrivalListener()，即可在裝置抵達目的地時註冊回呼。

抵達後，Android 版 Navigation SDK 會觸發 onArrival() 回呼，並停止即時路線指引。您必須明確呼叫 Navigator.continueToNextDestination() 才能前往下一個路線控點，並使用 Navigator.startGuidance() 繼續即時路線導航。

當您呼叫 continueToNextDestination() 時，導覽器會捨棄上一個目的地的所有資訊。如要分析上一個路徑片段的相關資訊，請先從導覽器擷取資訊，然後再呼叫 continueToNextDestination()。

為避免記憶體流失，當您不再需要事件監聽器時，必須呼叫 removeArrivalListener(listener)。

mNavigator.addArrivalListener(new Navigator.ArrivalListener() {
    @Override
    public void onArrival(ArrivalEvent arrivalEvent) {
        displayMessage("onArrival: You've arrived at a waypoint: "
                + mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_BOTH);
        // Start turn-by-turn guidance for the next leg of the route.
        if (arrivalEvent.isFinalDestination()) {
            displayMessage("onArrival: You've arrived at the final destination.",
                    DISPLAY_BOTH);
        } else {
            mNavigator.continueToNextDestination();
            mNavigator.startGuidance();
        }
    }
});

接收位置更新資訊

從 NavigationApi 取得 RoadSnappedLocationProvider，然後呼叫 RoadSnappedLocationProvider.addLocationListener() 來註冊裝置位置或標題變更時的回呼。請注意，這個位置會對齊道路，因此可能與 Google Play 服務 location API 中整合式位置預測提供工具傳回的位置不同。

Navigation SDK 會盡可能頻繁提供位置更新通知。有可用的位置更新時，Navigation SDK 會觸發 onLocationChanged() 回呼。

道路旋轉的位置更新與導覽無關，且可在導航停止後繼續。訂閱位置更新位置更新可能會導致電池耗電、記憶體流失，或是在背景執行位置更新通知，但不小心收集到裝置位置資料。如果不再需要事件監聽器，請呼叫 RoadSnappedLocationProvider.removeLocationListener。

mRoadSnappedLocationProvider =
        NavigationApi.getRoadSnappedLocationProvider(getApplication());
if (mRoadSnappedLocationProvider != null) {
    mRoadSnappedLocationProvider.addLocationListener(
            new RoadSnappedLocationProvider.LocationListener() {
                @Override
                public void onLocationChanged(Location location) {
                    displayMessage("onLocationUpdated: Navigation engine has provided a new"
                                    + " road-snapped location: "
                                    + location.toString(),
                            DISPLAY_LOG);
                }
            });
} else {
    displayMessage("ERROR: Failed to get a location provider", DISPLAY_LOG);
}

接收時間和距離更新

當剩餘時間 (秒) 或距離 (公尺) 超過指定閾值時，請呼叫 Navigator.addRemainingTimeOrDistanceChangedListener() 來註冊回呼。

如果時間或距離的變化超過指定數量，Navigation SDK 會觸發 onRemainingTimeOrDistanceChanged() 回呼。

如要查看剩餘的時間和距離，請呼叫 Navigator.getTimeAndDistanceList()。請注意，清單中的時間和距離都是累計的，它們會顯示目前位置與每個路線控點之間的時間和距離，而不是從一個路線點到另一個路線控點的時間。TimeAndDistance 物件現在也會傳回 delaySeverity。列舉項目會是重、中度、輕度或不明。這對應於地圖 UI 中看到的 Eta 顏色 (重，紅色 = 紅色，中等 = 黃色，淺綠色 = 綠色)。如果您需要建立自己的 Eta 頁尾，這種做法非常實用。

為避免記憶體流失，當您不再需要事件監聽器時，必須呼叫 Navigator.removeRemainingTimeOrDistanceChangedListener(listener)。

如果剩餘時間變化超過 60 秒，或剩餘距離改變超過 100 公尺，則範例會要求回呼。

mNavigator.addRemainingTimeOrDistanceChangedListener(60, 100,
        new Navigator.RemainingTimeOrDistanceChangedListener() {
            @Override
            public void onRemainingTimeOrDistanceChanged() {
                displayMessage("onRemainingTimeOrDistanceChanged: Time or distance estimate"
                        + " has changed.",
                        DISPLAY_LOG);
            }
        });

您可以使用 setEtaCardEnabled() 方法，並傳遞包含 TRUE 值的參數，使用內建螢幕顯示剩餘時間和距離資訊。如要隱藏時間/距離，請將此值設為 FALSE。

您也可以使用 getTimeAndDistanceList() 方法，公開多個路線控點的預計到達時間。

接收路線更新

呼叫 Navigator.addRouteChangedListener() 以註冊在路徑變更時的回呼。

路徑變更時，Navigation SDK 會觸發 onRouteChanged() 回呼。您可以呼叫 Navigator.getRouteSegments 和 Navigator.getCurrentRouteSegment() 找出新路徑。

為避免記憶體流失，當您不再需要事件監聽器時，必須呼叫 removeRouteChangedListener(listener)。

mNavigator.addRouteChangedListener(new Navigator.RouteChangedListener() {
    @Override
    public void onRouteChanged() {
        displayMessage("onRouteChanged: The driver's route has changed. Current waypoint: "
                + mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_LOG);
    }
});

偵測夜間模式變更的時間

呼叫 NavigationView.addOnNightModeChangedListener 或 SupportNavigationFragment.addOnNightModeChangedListener，在夜間模式變更時註冊回呼。

以下範例顯示監聽導覽片段的夜間模式變更。

mNavFragment.addOnNightModeChangedListener(new NavigationView.OnNightModeChangedListener() {
    @Override
    public void onNightModeChanged(NightModeChangedEvent nightModeChangedEvent) {
        displayMessage("Night mode is active: " + nightModeChangedEvent.inNightMode(),
        DISPLAY_LOG);
    }
});