監聽導覽事件

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

總覽

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

查看程式碼

偵測抵達目的地

這裡的目的地是指最終目的地或中途點。如要偵測抵達時間，請呼叫 Navigator.addArrivalListener()，在裝置抵達目的地時註冊回呼。

抵達目的地後，Android 版 Navigation SDK 會觸發 onArrival() 回呼，然後使用 Navigator.stopGuidance() 停止逐步導航，或使用 Navigator.continueToNextDestination() 前往下一個途中的航點。如果導航工作階段只包含單一目的地，或目的地清單中沒有任何目的地，呼叫 Navigator.continueToNextDestination() 會自動停止導航。

呼叫 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 服務位置 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。這個列舉會是大量、中量、少量或不明。這對應於地圖使用者介面中預計抵達時間的顏色 (嚴重 = 紅色、中等 = 黃色、輕微 = 綠色)。如需建立自己的 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);
    }
});

您也可以透過程式輔助方式設定夜間模式。詳情請參閱「設定夜間模式」。