監聽導覽事件

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

總覽

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

查看程式碼

偵測抵達目的地

這裡的「目的地」是指最終目的地或路線點。如要偵測到抵達目的地，請呼叫 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 服務位置 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。這個列舉值會是 heavy、meduim、light 或 unknown。這會對應到您在 Google 地圖 UI 中看到的預估抵達時間顏色 (嚴重 = 紅色、中等 = 黃色、輕微 = 綠色)。如果您需要自行建立 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);
    }
});

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