导航状态信息

功能介绍

导航进行期间，SDK 通过 NavigationEventListener.onNavigationEventUpdated 以约 1 Hz 推送 NavigationEvent，用于刷新 HMI 主界面的路线进度、下一机动、剩余里程/时间、偏航状态等。

本文说明 onNavigationEventUpdated 回调中的 NavigationEvent 字段及集成要点。

NavigationEvent 字段在主界面中的示意

前置条件： 已按真实导航与模拟导航注册 NavigationEventListener 并完成 startNavigation。

监听注册

建议在 startNavigation 之前注册，在 stopNavigation 之后 removeNavigationEventListener：

val listener = object : NavigationEventListener {
    override fun onNavigationEventUpdated(navEvent: NavigationEvent) {
        // 约 1 Hz 刷新主界面
    }
    // 其它回调见各专题文档，按需实现
}

navigationService.eventHub.addNavigationEventListener(listener)

`NavigationEvent` 字段说明

路线定位索引

legIndex、stepIndex、edgeIndex、edgePointIndex 用于在 Route 上快速定位车辆。索引均为 从 0 开始，且 相对于所属父级（step 相对 leg，edge 相对 step，shape point 相对 edge）。

字段	说明
`legIndex`	当前 leg 索引
`stepIndex`	当前 leg 内 step 索引
`edgeIndex`	当前 step 内 edge 索引
`edgePointIndex`	当前 edge 上 shape point 索引

非沿路时的行为： 仅沿路时上述索引会随位置更新；偏航或离路时保持为最后一次沿路时的值（见 NavigationEvent 字段注释）。

机动引导

字段	类型	说明
`deviated`	`Boolean`	`true` 表示未沿当前导航路线行驶（偏航，见概述）；不表示离路
`currentManeuver`	`ManeuverInfo?`	即将执行的机动点信息
`nextManeuver`	`ManeuverInfo?`	再下一机动；仅在紧接转弯（两机动距离很近）时有效
`distanceToTurn`	`Double`	沿路线到当前机动点的剩余距离（米）

currentManeuver、nextManeuver 的类型为 ManeuverInfo。字段说明如下：

字段	类型	说明
`legIndex`	`Int`	机动所属 leg 索引（从 0 开始）
`stepIndex`	`Int`	机动所属 step 索引（从 0 开始，相对所属 leg）
`turnAction`	`Int`（`Action`）	主转向动作，如左转、右转、继续直行等
`turnAssistAction`	`Int`（`AssistAction`）	辅助动作，如进出高速、进出环岛、上匝道等
`leftSideDriving`	`Boolean`	是否左侧通行国家/地区
`latitude` / `longitude`	`Double`	机动点坐标
`lengthMeters`	`Double`	本 step 起点到机动点的距离（米）
`laneInfo`	`List<LaneInfo>?`	车道引导；从左至右排列，左/右舵国家顺序一致
`streetName`	`String?`	转弯后道路名（next street name）
`signpostBranchNames`	`List<Name>?`	路牌 Branch Name（分支名），见概述 · Branch Name 与 Towards Name
`signpostTowardsNames`	`List<Name>?`	路牌 Towards Name（方向名），见概述 · Branch Name 与 Towards Name
`exitLabel`	`List<Name>?`	高速出口编号/名称（由高速驶出或高速间切换时）
`roundaboutInfo`	`RoundaboutInfo?`	环岛信息（出口序号、各出口角度等）
`stepInfo`	`StepInfo?`	所属 step 的完整信息；可用于地图高亮转向箭头等
`shieldInfoList`	`List<ShieldInfo>?`	路盾列表（道路编号 + 图标上下文）
`isTightTurn`	`Boolean`	是否为紧接转弯（下一机动距离很近，需提前准备）
`fromRoadClass` / `toRoadClass`	`Int`（`RoadClass`）	转弯前/后的道路等级；可反映如「由高速驶入次干道」等变化，用于自动缩放、播报距离等策略

turnAction（Action）常用取值：

常量	含义
`CONTINUE`	继续直行
`TURN_SLIGHT_LEFT` / `TURN_LEFT` / `TURN_SHARP_LEFT`	微左 / 左 / 急左
`TURN_SLIGHT_RIGHT` / `TURN_RIGHT` / `TURN_SHARP_RIGHT`	微右 / 右 / 急右
`U_TURN_LEFT` / `U_TURN_RIGHT`	左掉头 / 右掉头
`STAY_LEFT` / `STAY_RIGHT` / `STAY_MIDDLE`	靠左 / 靠右 / 居中
`STOP_LEFT` / `STOP_RIGHT` / `STOP_AHEAD`	目的地在左 / 右 / 正前方
`ENTER_AHEAD` / `EXIT_AHEAD`	进入/离开无明确方向的区域（如环岛入口、渡口等）

完整枚举见 com.telenav.sdk.map.direction.model.Action。

turnAssistAction（AssistAction）常用取值：

类别	示例常量
高速	`ENTER_FREEWAY`、`EXIT_FREEWAY`、`SWITCH_FREEWAY`
匝道 / 主辅路	`ONTO_RAMP`、`ONTO_MAIN_ROAD`、`ONTO_FRONTAGE_ROAD`
立交	`ONTO_OVERPASS`、`ONTO_UNDERPASS`、`AVOID_OVERPASS`、`AVOID_UNDERPASS`
特殊路段	`ENTER_TUNNEL`、`EXIT_TUNNEL`、`ENTER_FERRY`、`EXIT_FERRY`、`PASS_TOLL_BOOTH`
环岛	`ENTER_ROUNDABOUT`、`EXIT_ROUNDABOUT`
保持主路	`KEEP_CURRENT_ROAD`：配合 `STAY_LEFT` / `STAY_RIGHT` / `STAY_MIDDLE` 等机动，表示继续沿当前主路行驶（多见于高速或其它快速路）
钩形转弯	`PERFORM_HOOK_TURN`：Hook turn（钩形转弯，澳大利亚常见）：右转时不进路口中央，先靠左至左前角等待本向红灯，待横向绿灯后再随横向车流驶入目标路

完整枚举见 com.telenav.sdk.map.direction.model.AssistAction。HMI 绘制转向图标时通常 turnAction 与 turnAssistAction 组合使用。

laneInfo（LaneInfo）字段：

字段	说明
`pattern`	车道可通行方向图案（`LanePattern`），用于绘制车道总览
`applicableDirection`	本车道适用于当前路径的行驶方向（`ApplicableDrivingDirection`）
`type`	车道类型 bitmask（`LaneType`），如 BUS、ETC、HOV、BICYCLE 等
`isPreferred`	是否推荐车道；紧接下一机动时，推荐更易安全跟线的车道

pattern（LanePattern）常量：

LanePattern 为整型常量；单方向取值与 ApplicableDrivingDirection 一致，组合方向为位或（|）结果。

常量	值	说明
`NONE`	0	无
`CONTINUE`	1	直行
`LEFT`	2	左转
`CONTINUE_AND_LEFT`	3	直行 + 左转
`RIGHT`	4	右转
`CONTINUE_AND_RIGHT`	5	直行 + 右转
`LEFT_AND_RIGHT`	6	左转 + 右转
`CONTINUE_AND_LEFT_AND_RIGHT`	7	直行 + 左转 + 右转
`LEFT_UTURN`	8	左掉头
`CONTINUE_AND_LEFT_UTURN`	9	直行 + 左掉头
`LEFT_AND_LEFT_UTURN`	10	左转 + 左掉头
`CONTINUE_AND_LEFT_AND_LEFT_UTURN`	11	直行 + 左转 + 左掉头
`RIGHT_UTURN`	16	右掉头
`CONTINUE_AND_RIGHT_UTURN`	17	直行 + 右掉头
`RIGHT_AND_RIGHT_UTURN`	20	右转 + 右掉头
`CONTINUE_AND_RIGHT_AND_RIGHT_UTURN`	21	直行 + 右转 + 右掉头
`SLIGHT_LEFT`	32	微左
`CONTINUE_AND_SLIGHT_LEFT`	33	直行 + 微左
`LEFT_AND_SLIGHT_LEFT`	34	左转 + 微左
`SLIGHT_LEFT_AND_LEFT_UTURN`	40	微左 + 左掉头
`CONTINUE_AND_SLIGHT_LEFT_AND_LEFT_UTURN`	41	直行 + 微左 + 左掉头
`SLIGHT_RIGHT`	64	微右
`CONTINUE_AND_SLIGHT_RIGHT`	65	直行 + 微右
`RIGHT_AND_SLIGHT_RIGHT`	68	右转 + 微右
`SLIGHT_RIGHT_AND_RIGHT_UTURN`	80	微右 + 右掉头
`CONTINUE_AND_SLIGHT_RIGHT_AND_RIGHT_UTURN`	81	直行 + 微右 + 右掉头
`SLIGHT_LEFT_AND_SLIGHT_RIGHT`	96	微左 + 微右
`CONTINUE_AND_SLIGHT_LEFT_AND_SLIGHT_RIGHT`	97	直行 + 微左 + 微右
`SHARP_LEFT`	128	急左
`LEFT_AND_SHARP_LEFT`	130	左转 + 急左
`SLIGHT_LEFT_AND_SHARP_LEFT`	160	微左 + 急左
`SHARP_RIGHT`	256	急右
`RIGHT_AND_SHARP_RIGHT`	260	右转 + 急右
`SLIGHT_RIGHT_AND_SHARP_RIGHT`	320	微右 + 急右
`SECOND_LEFT`	512	第二左转
`SECOND_RIGHT`	1024	第二右转

applicableDirection（ApplicableDrivingDirection）常用取值：

常量	值	说明
`NOT_APPLICABLE`	0	不适用于当前路径
`STRAIGHT`	1	直行
`LEFT`	2	左转
`RIGHT`	4	右转
`LEFT_UTURN`	8	左掉头
`RIGHT_UTURN`	16	右掉头
`SLIGHT_LEFT`	32	微左
`SLIGHT_RIGHT`	64	微右
`SHARP_LEFT`	128	急左
`SHARP_RIGHT`	256	急右
`SECOND_LEFT`	512	第二左转
`SECOND_RIGHT`	1024	第二右转

roundaboutInfo（RoundaboutInfo）字段：

字段	说明
`exitNumber`	应驶出的环岛出口序号（从 1 起；0 表示无有效信息）
`exitAngles`	各出口相对入口的角度列表（度，`(0, 360]`），可用于绘制环岛示意图

shieldInfoList（ShieldInfo）字段：

字段	说明
`roadNumber`	道路编号文字
`shieldIconContext`	路盾图标渲染上下文；传入 `NavigationService.renderIcon(width, height, shieldIconContext)` 获取 `BitmapInfo?`（`bitmap` 为路盾图标），渲染失败时返回 `null`

Name（用于 signpostBranchNames、signpostTowardsNames、exitLabel）：

字段	说明
`type`	名称类型（`NameType`）
`format`	名称格式（`NameFormat`）
`orthography`	正字法名称（`NameRecord`），用于 HMI 展示
`phonemes`	音素名称列表，可用于 TTS

HMI 建议： 主界面下一机动优先用 turnAction + turnAssistAction 选图标，streetName 或路牌名做文字；isTightTurn == true 时可同时展示 nextManeuver；车道线用 laneInfo，高速场景关注 exitLabel 与 shieldInfoList。

行程估计（`TravelEstimation`）

字段	类型	说明
`travelEstToStop`	`TravelEstimation?`	到前方下一途经点/终点（下一途经点；若仅剩终点则与到终点一致）
`travelEstToDestination`	`TravelEstimation?`	到终点的估计
`traveledDistance`	`Double`	本次导航会话已行驶距离（米）；一般仅在 on-route 时累加
`traveledTime`	`Int`	本次导航会话已行驶时间（秒）
`stepEstimations`	`List<StepTravelEstimation>?`	当前位置之后各 step 的分段估计；仅当 `NavigationServiceOptions.Builder.setTravelEstimationLevel(STEP)` 或 `EDGE` 后非空

TravelEstimation 字段说明：

字段	说明
`distanceToStop`	剩余距离（米）
`timeToStop`	剩余时间（秒），含路况影响
`timeToStopWithoutTraffic`	剩余时间（秒），不含路况
`trafficDelay`	拥堵导致的额外延迟（秒）；无路况或无拥堵时为 0
`arrivalToStop`	预计到达时刻，本地时间字符串 `yyyy-MM-dd HH:mm:ss`
`timeZoneInfo`	途经点/终点所在时区
`arrivalBattery`	仅 EV；到达电量更新信息（若导航组件已校验该停靠点）

HMI 建议： 主界面 ETA / 剩余里程优先使用 travelEstToDestination；多途经点场景下，前方停靠点提示可使用 travelEstToStop。若需展示「全程拥堵延迟」，对尚未经过的各段 TravelEstimation.trafficDelay 按顺序累加（参见 TravelEstimation 类注释）。

主动获取行程估计（`NavigationSession.getTravelEstimationInfo`）

除 onNavigationEventUpdated 的 1Hz 被动回调外，NavigationSession 还提供主动读取接口：

fun getTravelEstimationInfo(): List<TravelEstimation>?

返回值说明：

列表元素类型为 TravelEstimation，字段语义与 travelEstToStop / travelEstToDestination 一致。

场景标志与其它

字段	说明
`inServiceArea`	是否处于服务区道路
`inParkingLot`	是否处于停车场道路
`nearbyChargingStation`	仅 EV；是否靠近规划中的充电站
`continueHighwayStatus`	高速继续行驶相关状态（如「继续沿高速行驶」提示）

示例代码

override fun onNavigationEventUpdated(navEvent: NavigationEvent) {
    navEvent.travelEstToDestination?.let { est ->
        mainHandler.post {
            binding.remainingDistance.text = formatDistance(est.distanceToStop)
            binding.remainingTime.text = formatDuration(est.timeToStop)
            binding.eta.text = est.arrivalToStop
        }
    }

    navEvent.currentManeuver?.let { maneuver ->
        mainHandler.post {
            updateTurnIcon(maneuver.turnAction, maneuver.turnAssistAction)
            updateDistanceToTurn(navEvent.distanceToTurn)
            updateNextStreetName(maneuver.streetName)
        }
    }

    if (navEvent.deviated) {
        mainHandler.post { showDeviationHint() }  // 偏航：在路上但不在导航路线上
    }
}

// 离路需在 PositionEventListener 中判断，例如：
// override fun onLocationUpdated(positionInfo: PositionInfo, ...) {
//     if (positionInfo.isOffRoad()) showOffRoadHint()
// }

注意事项

回调线程： onNavigationEventUpdated 在 Message 线程回调，更新 UI 请切主线程（见播报）。
判空： currentManeuver、travelEstToStop、travelEstToDestination 等可能为空。
deviated： 仅表示偏航；离路见 PositionInfo.isOffRoad()（概念见概述）。
1 Hz： 一般无需对同一字段再额外节流；若合并多源数据，避免重复降频导致界面滞后。