到达和离开

功能介绍

导航过程中，SDK 通过两个回调区分途经点/终点的到达与离开时刻，供 HMI 更新停靠状态、播报与下一段引导。

接口	时刻	说明
onNavigationStopReached	到达途经点/终点前（距点 ≤ 阈值）	stopIndex == -1 表示终点
onDepartWaypoint	离开途经点之后	仅途经点，无终点离开回调

到达通知早于物理到达点，便于展示提示与到达类语音（参见 播报）。离开通知表示车辆已驶离该途经点，可开始下一段引导或标记途经点已完成。

核心接口：

接口	说明
NavigationEventListener.onNavigationStopReached(stopIndex, stopLocation)	到达途经点/终点（提前触发）
NavigationEventListener.onDepartWaypoint(departureWaypointInfo)	离开途经点
NavigationServiceOptions.Builder.setArrivalDistanceThreshold(...)	配置到达提前触发距离（创建 NavigationService 时）

前置条件： 已 startNavigation 并注册 NavigationEventListener（两个回调均为必实现）。

流程概览

导航中，距停靠点 ≤ 到达阈值
        ↓
onNavigationStopReached(stopIndex, stopLocation)
        ↓
HMI：到达提示 / 播报 / 途经点「已到达」状态
        ↓
（仅途经点）车辆实际驶离
        ↓
onDepartWaypoint(DepartureWaypointInfo)
        ↓
HMI：途经点「已离开」、恢复下一段引导
        ↓
（终点 stopIndex == -1）→ 结束导航 UI、清理路线等（无 onDepartWaypoint）

---

1. 到达：onNavigationStopReached

fun onNavigationStopReached(stopIndex: Int, stopLocation: Int)

参数

参数	说明
stopIndex	途经点索引（从 0 开始）；-1 表示到达终点
stopLocation	停靠点相对匹配位置的方位，见 com.telenav.sdk.drivesession.model.StopLocation

触发条件

• 自车与途经点/终点的距离 ≤ 到达阈值（见本节末尾「配置到达阈值」）。
• 普通道路与高速可使用不同阈值。
• 偏航（NavigationEvent.deviated == true）时不会发送到达通知。

触发后，该途经点剩余距离在 ETA 等估计中会并入下一停靠点的前段（终点除外）。

StopLocation 取值

常量	值	含义
INVALID	0	无效
LEFT	1	到达的途经点或终点在道路的左侧
RIGHT	2	到达的途经点或终点在道路的右侧
AHEAD	3	到达的途经点或终点在道路的正前方
OFF_ROAD	4	离路（如停车场区域）
PEDESTRIAN	5	人行道
RESTRICTED	6	车辆禁行

示例

override fun onNavigationStopReached(stopIndex: Int, stopLocation: Int) {
    mainHandler.post {
        if (stopIndex == -1) {
            finishNavigationUi()
            return
        }
        showWaypointArrived(stopIndex)
        when (stopLocation) {
            StopLocation.LEFT -> showArrivalHint("左侧到达")
            StopLocation.RIGHT -> showArrivalHint("右侧到达")
            else -> { }
        }
    }
}

配置到达阈值：setArrivalDistanceThreshold

在创建 NavigationService 之前通过 NavigationServiceOptions.Builder 配置。仅影响本回调的触发时机。

NavigationServiceOptions.Builder()
    .setArrivalDistanceThreshold(
        localDistanceThreshold = 60,     // 普通道路，米
        highwayDistanceThreshold = 100   // 高速，米
    )
    .build()

当自车处于普通道路或高速时，分别使用对应阈值：距途经点/终点距离 ≤ 阈值即触发 onNavigationStopReached。

参数	说明	默认
localDistanceThreshold	普通道路上触发到达通知的距离（米）	60
highwayDistanceThreshold	高速上触发到达通知的距离（米）	100

未调用本方法时使用上述默认值。导航中不可修改，需重新创建 NavigationService。

---

2. 离开：onDepartWaypoint

fun onDepartWaypoint(departureWaypointInfo: DepartureWaypointInfo)

参数

字段	说明
DepartureWaypointInfo.waypointIndex	离开的途经点索引（从 0 开始）

车辆在实际离开该途经点后触发。底层存在多种离开类型（常规、偏航、离路等），Android 侧统一以 waypointIndex 标识；具体场景可结合当时是否偏航等由 HMI 判断。

示例

override fun onDepartWaypoint(info: DepartureWaypointInfo) {
    mainHandler.post {
        markWaypointDeparted(info.waypointIndex)
        resumeTurnByTurnForNextLeg()
    }
}

---

与其它能力的关系

能力	关系
导航状态信息	travelEstToStop 等在到达阈值触发后可能仍显示「剩余」距离
播报	到达类 TTS 常与 onNavigationStopReached 配合

注意事项

• 终点： 仅 onNavigationStopReached(stopIndex = -1)；无 onDepartWaypoint。
• 到达为提前触发： 进入阈值即回调，不等于已停在点上。
• 偏航： 偏航时不发到达通知；更新路线后依赖 换路通知 等。
• 回调顺序： SDK 在同一状态更新中可能先处理离开、再处理到达（depart 先于 reach）；HMI 按各自回调独立更新即可。
• 回调线程： Message 线程，更新 UI 请切主线程。