监听导航事件

您的应用可以监听用户沿路线导航时发生的事件。

概览

使用以下接口可监听导航事件：

查看代码

检测到达目的地

在此处，目的地是指最终目的地或途经点。如需检测到达情况，请调用 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 颜色（严重拥堵 = 红色，中度拥堵 = 黄色，轻微拥堵 = 绿色）。如果您需要创建自己的 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 以注册夜间模式更改时的回调。

以下示例展示了如何在导航 fragment 上监听夜间模式更改。

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

您还可以通过程序化方式设置夜间模式。如需了解详情，请参阅设置夜间模式。