Skip to content

备选路

支持范围： 目前仅在乘用车（非 EV）Cloud 模式下支持此功能。

功能介绍

导航过程中，HMI 可基于当前位置请求备选路线（alternative routes）。备选路提供的是与当前导航路线不同的路线选择，不一定是更优路（与 更优的路 区分）。

典型用法：在地图上并列展示当前导航路与一条或多条备选路，供用户对比后主动切换。

核心接口：

接口 说明
NavigationSession.requestAlternativeRoutesCalculation(request) 发起备选路计算
NavigationEventListener.onAlternativeRoutesUpdated(info) 备选路列表或状态更新
NavigationSession.acceptAlternativeRoute(route) 用户选择某条备选路并切换

用户接受备选路后，换路进度由 换路通知 的 onNavigationRouteUpdating 通知（reason 常为 ALTERNATIVE_ROUTE_SELECTED）。

前置条件： 已 startNavigation 并持有 NavigationSession；已注册 NavigationEventListener。

流程概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
导航中
   ↓
requestAlternativeRoutesCalculation(AlternativeRouteRequest)
   ↓
onAlternativeRoutesUpdated(AlternativeRouteUpdateInfo)
   ↓
reason == CALCULATION_SUCCESS → 展示 navigationRoute + alternativeRoutes
   ↓
用户选择 → acceptAlternativeRoute(alternativeRoute)
   ↓
onNavigationRouteUpdating → 更新导航路线上下文与地图（见「换路通知」）

请求备选路：requestAlternativeRoutesCalculation

1
2
3
4
5
6
navigationSession.requestAlternativeRoutesCalculation(
    AlternativeRouteRequest.Builder()
        .setMaxRouteNumber(1)           // 最多请求条数，有效值 1 或 2，默认 1
        .setMaxTimeToBifurcation(600)   // 至分岔点最大预计时间（秒），≤ 3600，默认 600
        .build()
)
  • 基于当前导航位置计算备选路。
  • 若已有进行中的请求，新请求会取消旧请求。
  • 结果通过 onAlternativeRoutesUpdated 异步返回，无单独 Task 对象。

AlternativeRouteRequest 参数

参数 说明 默认
maxRouteNumber 最多请求的备选路条数 1（有效范围 1～2；超出范围将被忽略，不生效）
maxTimeToBifurcation 至分岔点的最大预计时间（秒） 600（有效范围 0～3600；超出范围将被忽略，不生效）

接收更新：onAlternativeRoutesUpdated

1
fun onAlternativeRoutesUpdated(info: AlternativeRouteUpdateInfo)

NavigationEventListener 中该回调带默认空实现，需按需 override。

触发时机

在调用 requestAlternativeRoutesCalculation 后，以下情况会触发本回调：

  1. 备选路计算成功或失败
  2. 未找到满足条件的备选路
  3. 导航路线发生变化（例如偏航触发更新路线、已接受某条备选路——原导航路会加入 alternativeRoutes）
  4. 导航结束
  5. 已进入备选路的分岔点已过

AlternativeRouteUpdateInfo.Reason

常量 说明 HMI 建议
CALCULATION_SUCCESS 至少找到一条备选路 展示 alternativeRoutes，绘制备选路线样式
NO_ALTERNATIVE_ROUTES 无有效备选路或未满足条件 可按策略稍后重试
CALCULATION_FAILURE 计算出错 提示或静默重试
NAVIGATION_ROUTE_CHANGED 导航路变更或导航结束 刷新列表；若 alternativeRoutes 为空可重新请求
PASSED 备选路入口点已过 移除失效备选路；列表为空时可重新请求

AlternativeRouteUpdateInfo 字段

字段 说明
reason 本次更新原因（先读）
navigationRoute 当前正在导航的路线
alternativeRoutes 当前可用的备选路列表；接受某条备选路后，原导航路可能出现在此列表中

AlternativeRoute 字段

字段 说明
route 备选路线（Route）
bifurcationTime 沿当前导航路至分岔点的预计时间（秒）
bifurcationDistance 沿当前导航路至分岔点的距离（米）
distanceDelta 与当前导航路的里程差（米）
etaDelta 与当前导航路的预计到达时间差（秒）
firstEdgeIndex 备选路第一个 edge 的 RouteEdgeIndex；地图绘制备选路时可传入 RouteRenderOptions.firstAlternativeRouteEdge

切换备选路：acceptAlternativeRoute

1
val success = navigationSession.acceptAlternativeRoute(alternativeRoute)
  • 接受后，该备选路成为新的导航路线，原导航路线会作为备选路之一保留在后续 alternativeRoutes 中。
  • 返回 true 表示成功；false 表示备选路已失效（例如分岔点已过、列表已更新）。
  • 成功后关注 onNavigationRouteUpdating 与 onAlternativeRoutesUpdated（NAVIGATION_ROUTE_CHANGED）更新 UI。

示例代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// 导航中周期性或按需请求备选路
navigationSession?.requestAlternativeRoutesCalculation(
    AlternativeRouteRequest.Builder()
        .setMaxRouteNumber(2)
        .setMaxTimeToBifurcation(600)
        .build()
)

override fun onAlternativeRoutesUpdated(info: AlternativeRouteUpdateInfo) {
    when (info.reason) {
        AlternativeRouteUpdateInfo.Reason.CALCULATION_SUCCESS -> {
            mainHandler.post {
                drawNavigationRoute(info.navigationRoute)
                // 地图中添加备选路
                info.alternativeRoutes.forEach { alt ->
                    mapView.routesController().add(
                        listOf(alt.route),
                        listOf(
                            RouteRenderOptions(
                                alternativeRoute = true,
                                firstAlternativeRouteEdge = alt.firstEdgeIndex
                            )
                        )
                    )
                }
            }
        }
        AlternativeRouteUpdateInfo.Reason.PASSED,
        AlternativeRouteUpdateInfo.Reason.NAVIGATION_ROUTE_CHANGED -> {
            // 刷新备选路
            mainHandler.post { refreshAlternativeRoutesOnMap(info) }
        }
        AlternativeRouteUpdateInfo.Reason.NO_ALTERNATIVE_ROUTES,
        AlternativeRouteUpdateInfo.Reason.CALCULATION_FAILURE -> {
            // 可按产品策略延迟重试 requestAlternativeRoutesCalculation
        }
    }
}

// 用户选中某条备选路
fun onAlternativeRouteSelected(alt: AlternativeRoute) {
    if (navigationSession?.acceptAlternativeRoute(alt) == true) {
        // 换路结果见 onNavigationRouteUpdating
    }
}

注意事项

  • 与更优的路区分： 备选路是平行路线选择，不强调「更优」；更优路见 更优的路（onBetterRouteDetected + acceptRouteProposal）。
  • acceptAlternativeRoute 可能失败： 分岔点已过或列表已变化时返回 false，应刷新 onAlternativeRoutesUpdated 最新数据后再选。
  • 地图样式： 当前导航路与备选路应使用不同样式；绘制备选路时使用 firstEdgeIndex 标明从何处与主路分离。
  • 回调线程： Message 线程，更新 UI / MapView 请切主线程。
  • 重复请求： 新请求会取消未完成的上一次计算；频繁请求需自行节流。
  • 备选路样式需单独配置： 备选路在地图上的线型与颜色由 TSS 单独定义，与导航路线样式独立。使用前请先配置。