監聽導覽事件

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

總覽

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

查看程式碼

偵測抵達目的地

這裡的「目的地」是指最終目的地或路線點。如要偵測抵達目的地,請呼叫 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。列舉為粗體、中間值、淺色或未知。這與地圖 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.getRouteSegmentsNavigator.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.addOnNightModeChangedListenerSupportNavigationFragment.addOnNightModeChangedListener,註冊在夜間模式變更時註冊回呼。

以下範例說明如何在導覽片段上監聽夜間模式變更。

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

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