换路通知

功能介绍

导航过程中，当 SDK 开始、完成或取消一次路线更新（换路）时，通过 NavigationEventListener.onNavigationRouteUpdating 推送进度通知。常见场景包括：

• 自动换路：偏航后更新路线、避开封闭交通/限时通行、EV 续航/充电站不可达等
• 主动换路：用户接受 更优的路 提案（NavigationSession.acceptRouteProposal）、切换 备选路 等

HMI 应在此回调中刷新地图路线图层，并在 SUCCEEDED 时切换到 newRoute 继续导航。

与 onBetterRouteDetected 的区别： onBetterRouteDetected 仅表示检测到可选更优路线，需用户确认后才会换路；onNavigationRouteUpdating 表示换路流程已在进行或已结束，无论自动还是已确认的主动换路。

前置条件： 已按 真实导航与模拟导航 注册 NavigationEventListener 并处于导航会话中。

接口说明

fun onNavigationRouteUpdating(progress: BetterRouteUpdateProgress)

收到回调后先判断 progress.status，再读取其它字段（部分状态下其它字段无效）。

BetterRouteUpdateProgress.Status

状态	说明	HMI 建议
STARTED	当前路线不符合使用要求时，SDK 内部自动触发求路；STARTED 表示求路已开始	可展示 loading；结合 reason、betterRouteContext 了解触发原因
SUCCEEDED	求路成功，新路已可用	使用 newRoute 刷新地图与导航 UI
FAILED	通常为求路失败，或新路仍不符合要求；SDK 可能在满足条件时重新触发求路	保留当前路线；newRoute 不可用；可按产品策略提示或静默等待下次通知
CANCELED	本次求路/换路已取消（如偏航触发更新路线过程中恢复沿路）	忽略本次更新，继续当前路线

BetterRouteUpdateProgress 字段

字段	说明
status	换路进度状态（必先看）
reason	触发原因，见下表
newRoute	更新后的路线；SUCCEEDED 时有效
betterRouteContext	换路上下文（阻塞交通、限时路段、节省时长等）

Reason 触发原因

常量	说明
DEVIATION	偏航后更新路线
UPDATE_INTERNAL	内部因素触发的换路，例如：Content Switch（路线内容版本与当前地图数据版本不匹配，需重新求路对齐）；Update guidance（路线引导信息不完整或需补全引导数据）
AVOID_BLOCKING_TRAFFIC	避开封闭/阻塞交通（含接受更优路提案后）
AVOID_TIMED_RESTRICTION	避开限时通行（参见 限时通行）
SAVE_TIME	更优的路节省时间（参见 更优的路）
ALTERNATIVE_ROUTE_SELECTED	用户选择备选路，或车辆直接驶入备选路（参见 备选路）
INSUFFICIENT_BATTERY_LEVEL	仅 EV：当前电量不足以到达下一充电站/终点
RESUME_EV_TRIP_PLAN	仅 EV：EV 求路仅支持 Cloud；网络不佳时可能先用 Onboard 求普通路，待网络等条件恢复后重新恢复 EV 行程规划路线 时返回此 Reason
UPDATE_EV_TRIP_PLAN	仅 EV：EV 行程规划路线需更新（Cloud EV 求路），参见 EV导航
CHARGING_STATION_UNAVAILABLE	仅 EV：前方规划充电站不可用
LOW_ARRIVAL_BATTERY_LEVEL	仅 EV：预计到达电量过低

betterRouteContext（RouteUpdateContext）常用字段

字段	说明
route	换路所基于的监控路线
blockingIncidents	当前路线上的阻塞性交通事件
blockingFlows	当前路线上的阻塞性交通流
timedRestrictionEdges	前方首个限时受限 edge
savedTime	新旧路线预计节省时间（秒）
batteryInsufficientInfo	EV：电量不足信息
lowArrivalBatteryInfo	EV：到达电量过低信息

流程概览

导航中触发换路（偏航 / 接受更优路 / 备选路 / EV 等）
        ↓
onNavigationRouteUpdating(status = STARTED)
        ↓
算路完成
        ↓
onNavigationRouteUpdating(status = SUCCEEDED, newRoute = …)   ← 刷新地图与引导
   或 status = FAILED / CANCELED

示例代码

override fun onNavigationRouteUpdating(progress: BetterRouteUpdateProgress) {
    when (progress.status) {
        BetterRouteUpdateProgress.Status.STARTED -> {
            mainHandler.post { showRouteUpdatingIndicator(progress.reason) }
        }
        BetterRouteUpdateProgress.Status.SUCCEEDED -> {
            val route = progress.newRoute ?: return
            val previousRouteId = currentNavigationRoute?.id

            // 1. 更新 HMI 导航路线上下文（缓存 Route、highlightedRouteId、ViewModel 等）
            currentNavigationRoute = route
            navigationRouteLiveData.postValue(route)

            mainHandler.post {
                // 2. 刷新地图：旧路线 ID 变化时先移除，再绘制并高亮新路线
                if (previousRouteId != null && previousRouteId != route.id) {
                    mapView.routesController().remove(previousRouteId)
                }
                mapView.routesController().refresh(route)
                mapView.routesController().highlight(route.id)
                mapView.routesController().updateRouteProgress(route.id)

                hideRouteUpdatingIndicator()
            }
        }
        BetterRouteUpdateProgress.Status.FAILED -> {
            mainHandler.post {
                hideRouteUpdatingIndicator()
                showRouteUpdateFailedHint()
            }
        }
        BetterRouteUpdateProgress.Status.CANCELED -> {
            mainHandler.post { hideRouteUpdatingIndicator() }
        }
    }
}

注意事项

• 回调线程： Message 线程，更新 UI / MapView 请切主线程。
• 先读 status： 勿在 STARTED 或 FAILED 时直接使用 newRoute。
• 路线 ID 变化： SUCCEEDED 时 newRoute.id 可能与旧路线不同，需移除旧路线图层并高亮新路线（参考 SDK Examples BaseNavFragment）。
• 联动回调： 换路成功后还可能触发 onTurnByTurnListUpdated、onNavigationEventUpdated 等，HMI 应以 newRoute 为准整表刷新。