路线修改

功能介绍

导航过程中，HMI 可通过 NavigationSession.createRerouteTask 基于当前导航路线发起一次主动更新路线请求（reroute request），用于修改目的地、途经点，或避开指定路段/交通事件等。算路成功后，调用 acceptRerouteResult 将新路线应用到导航会话；换路进度由换路通知的 onNavigationRouteUpdating 通知。

与其它换路方式的区别：

方式	接口	性质
路线修改（本文）	`createRerouteTask` + `acceptRerouteResult`	HMI 主动发起更新路线请求
更优的路	`onBetterRouteDetected` + `acceptRouteProposal`	SDK 检测到的可选更优路
备选路	`requestAlternativeRoutesCalculation` + `acceptAlternativeRoute`	与当前路并行的备选路线
换路通知	`onNavigationRouteUpdating`	偏航、内部更新等自动换路进度

核心接口：

接口	说明
`NavigationSession.createRerouteTask(request)`	创建算路任务
`NavigationSession.acceptRerouteResult(rerouteInfo)`	接受新路线并切换导航路线
`RerouteRequest.Builder`	配置算路条件（目的地、途经点、避让等）

前置条件： 已 startNavigation 并持有 NavigationSession；已注册 NavigationEventListener（用于接收换路通知）。

流程概览

导航中，用户确认修改（改终点 / 改途经点 / 避开事件等）
        ↓
createRerouteTask(RerouteRequest) → Task<RerouteResponse>
        ↓
异步/同步获取 RerouteInfo，getStatus() == OK
        ↓
（可选）预览 getRoute()，展示新旧路线对比
        ↓
acceptRerouteResult(rerouteInfo)   // 须使用本次 Task 返回的 RerouteInfo
        ↓
onNavigationRouteUpdating(SUCCEEDED)   ← 见「换路通知」
        ↓
刷新地图、引导、ETA、沿途交通等

发起更新路线请求：`createRerouteTask`

fun createRerouteTask(request: RerouteRequest): Task<RerouteResponse>?

基于当前导航中的路线计算新路线。
返回 null 表示无法创建任务，常见原因：
导航会话已结束（stopNavigation 之后调用）
请求无效
EV 模式下不支持（createRerouteTask 返回 null，参见 EV导航）
使用 Task.runAsync / runSync 获取结果，用毕调用 task.dispose()。

`RerouteRequest.Builder` 配置项

方法	说明
`setDestination(destination)`	设置新终点；未设置时使用当前路线终点
`setWaypoints(waypoints)`	设置新途经点列表（按到达顺序）。未设置时沿用当前路线中未经过的途经点
`setAvoidIncidents(incidents)`	避开指定交通事件（通常来自沿途交通的 `AlongRouteTrafficIncidentInfo`）
`setAvoidSteps(steps)`	避开指定 step（`StepInfo`，可从 `ManeuverInfo.stepInfo` 等获取）

常见场景与配置示例

场景	配置
修改目的地	`setDestination(newGeoLocation)`
新增/调整途经点	`setWaypoints(listOf(waypoint1, waypoint2, …))`
避开交通事件	`setAvoidIncidents(listOf(incident))`
避开某段引导	`setAvoidSteps(listOf(stepInfo))`
仅刷新路线（沿用当前起终点与途经点）	`RerouteRequest.Builder().build()`

接受结果：`acceptRerouteResult`

fun acceptRerouteResult(rerouteInfo: RerouteInfo): Boolean

将 createRerouteTask 返回的 RerouteInfo 原样传入（勿自行构造）。
返回 true 表示接受成功；false 表示结果已失效（例如导航状态已变化）。
接受成功后，本次 RerouteRequest 中的设置（避让、目的地偏好等）会保留，供后续由客户端或 SDK 内部触发的更新路线请求继续使用。
成功后关注 onNavigationRouteUpdating（SUCCEEDED 时 newRoute 与 getRoute() 一致）。

`RerouteInfo` 字段

方法	说明
`getStatus()`	算路状态，见 `DirectionErrorCode`；`OK` 表示成功
`getRoute()`	更新路线后的新路线；成功时非 null
`getCurrentRoute()`	更新路线前的当前导航路线

示例代码

修改目的地

fun changeDestination(newDest: GeoLocation) {
    val task = navigationSession?.createRerouteTask(
        RerouteRequest.Builder().setDestination(newDest).build()
    ) ?: return

    task.runAsync { result ->
        val info = result.getResponse()
        if (info.getStatus() == DirectionErrorCode.OK && info.getRoute() != null) {
            if (navigationSession?.acceptRerouteResult(info) == true) {
                // 换路结果见 onNavigationRouteUpdating
            }
        }
        task.dispose()
    }
}

避开沿路交通事件

fun avoidIncident(incident: AlongRouteTrafficIncidentInfo) {
    val request = RerouteRequest.Builder()
        .setAvoidIncidents(listOf(incident))
        .build()
    navigationSession?.createRerouteTask(request)?.runAsync { result ->
        val info = result.getResponse()
        if (info.getStatus() == DirectionErrorCode.OK) {
            // 可选：先预览新路线
            navigationSession?.acceptRerouteResult(info)
        }
    }
}

修改途经点

val waypoint = Waypoint(GeoLocation(latLon), false)
navigationSession?.createRerouteTask(
    RerouteRequest.Builder().setWaypoints(listOf(waypoint)).build()
)?.runAsync { result ->
    val info = result.getResponse()
    if (info.getStatus() == DirectionErrorCode.OK) {
        navigationSession?.acceptRerouteResult(info)
    }
}

与其它能力的关系

能力	关系
换路通知	`acceptRerouteResult` 成功后触发 `onNavigationRouteUpdating`
沿途交通	`AlongRouteTrafficIncidentInfo` 可作为 `setAvoidIncidents` 输入
导航指令列表	`ManeuverInfo.stepInfo` 可构造 `StepInfo` 用于 `setAvoidSteps`
EV导航	EV 模式不支持 `createRerouteTask`

注意事项

两步操作： 先 createRerouteTask 算路，用户确认后再 acceptRerouteResult；算路成功不等于已切换导航路线。
EV 模式不支持： EV 导航下暂不支持此功能
接受失败： acceptRerouteResult 返回 false 时保留当前路线，可重新发起 createRerouteTask。
设置保留： 某次 acceptRerouteResult 成功后，该次 RerouteRequest 中的避让/目的地等设置会影响后续内部更新路线行为。
回调线程： Task 回调与 onNavigationRouteUpdating 在 Message 线程，更新 UI / MapView 请切主线程。
资源释放： Task 使用完毕后调用 dispose()。
路线修改属于高影响操作，建议给用户明确确认后再调用 acceptRerouteResult。