監聽導覽事件

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

總覽

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

查看程式碼

偵測抵達目的地

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

Navigation SDK for Android 啟動後會觸發 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 頁尾，這個方法就十分實用。

為避免記憶體流失，不再需要事件監聽器時，必須呼叫 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);
    }
});