沿途交通

功能介绍

导航过程中，SDK 会周期性推送当前导航路线前方的沿路交通信息，包括分段路况（flow）与交通事件（incident）。HMI 可用于：

• 在路线条/交通条上展示前方拥堵分布与延误
• 在地图上按路况着色（见 路线渲染）
• 列出事故、施工、封闭等事件，供用户查看或触发更新路线请求

核心接口：

接口	说明
NavigationEventListener.onAlongRouteTrafficUpdated(alongRouteTraffic)	接收沿路交通更新
NavigationServiceOptions.Builder.setTrafficFetchRange(seconds)	配置沿路交通采集/推送的时间范围

前置条件： 已 startNavigation 并注册 NavigationEventListener（本回调为必实现方法，无默认空实现）。

流程概览

创建 NavigationService 时 setTrafficFetchRange（可选，默认 3600 秒）
        ↓
startNavigation
        ↓
SDK 周期性推送 onAlongRouteTrafficUpdated(AlongRouteTraffic)
        ↓
HMI 解析 flow / incident → 更新交通条、事件列表
        ↓
地图：RoutesController.refreshAlongRouteTraffic(alongRouteTraffic) 刷新路线着色

配置采集范围：setTrafficFetchRange

在创建 NavigationService 之前配置；导航中不可动态修改。

NavigationServiceOptions.Builder()
    .setTrafficFetchRange(3600)   // 单位：秒
    .build()

参数	说明	默认
seconds	沿路交通采集范围（自当前位置起，沿路线方向的预计行驶时间）	3600（1 小时）
有效范围	1～Integer.MAX_VALUE；Integer.MAX_VALUE 表示覆盖整条路线	—

语义： SDK 仅采集并推送该时间范围内、且会影响预计到达时间（ETA） 的沿路交通数据。范围越小，数据量越少；范围越大，可提前展示更远路段的路况，但更新负载更高。

接收更新：onAlongRouteTrafficUpdated

fun onAlongRouteTrafficUpdated(alongRouteTraffic: AlongRouteTraffic)

导航会话激活期间，SDK 周期性下发最新沿路交通。回调中的 route、totalRouteDistance 等字段由 SDK 在分发前补全，可直接使用。

AlongRouteTraffic 字段

字段	说明
route	当前导航路线（Route）
totalRouteDistance	路线总长度（米）
alongRouteTrafficCollectDistance	本次采集到的交通信息覆盖距离（米）
collectedStartLegIndex / Step / Edge	采集区间起点在路线上的 leg / step / edge 索引（从 0 起）
collectedEndLegIndex / Step / Edge	采集区间终点索引
alongRouteTrafficFlow	分段路况列表，见下表；若列表为空（或 null），通常表示网络环境异常，HMI 可据此清空路况展示
alongRouteTrafficIncidents	交通事件列表，见下表；若列表为空（或 null），通常表示网络环境异常，HMI 可据此清空事件展示
additionalInfo	调试信息（请求/响应时间戳）

AlongRouteTrafficFlowSegment（分段路况）

字段	说明
startLegIndex / startStepIndex / startEdgeIndex	本段 flow 起点索引
startEdgeOffset	起点 edge 内偏移（米）；负值表示无效
endLegIndex / endStepIndex / endEdgeIndex	本段 flow 终点索引
endEdgeOffset	终点 edge 内偏移（米）；负值表示无效
distanceFromRouteStart	本段起点距路线起点的距离（米）
flowLength	本段长度（米）
flowSpeed	平均速度（米/秒）；0 表示阻塞；负值表示无数据
congestionLevel	拥堵等级，见 TrafficLevel

TrafficLevel 常用常量

常量	说明
FREE_FLOW	畅通
HEAVY	行驶缓慢
SLOW_SPEED	缓行
CONGESTED	拥堵
QUEUING	严重拥堵
CLOSED	封闭
UNKNOWN_LEVEL	未知

AlongRouteTrafficIncidentInfo（交通事件）

字段	说明
delayTime	事件造成的延误时间（秒）
routeID	所属路线 ID
legIndex / stepIndex / edgeIndex	事件在路线上的位置
trafficIncidentType	事件类型，见 TrafficIncidentType（如 ACCIDENT、CONSTRUCTION、ROAD_CLOSURE）
trafficIncidentSeverity	严重程度，见 TrafficIncidentSeverity
trafficIncidentUrgency	紧急程度，见 TrafficIncidentUrgencyLevel
blocking	是否阻塞通行
description	事件描述
incidentLocation	事件位置（TrafficIncidentLocation）
averageSpeed / maxSpeedLimit	受影响路段平均/最高限速（米/秒）；负值表示无数据
affectedLength	受影响路段长度（米）；负值表示无数据
affectedEdges	受影响的 edge 列表

地图刷新

沿路交通更新后，将 AlongRouteTraffic 原样传入 RoutesController.refreshAlongRouteTraffic 即可刷新路线路况着色，无需重新算路或 addRouteLine。详见 路线渲染。

示例代码

// 创建 NavigationService 时配置采集范围
val navOptions = NavigationServiceOptions.Builder()
    .setTrafficFetchRange(3600)
    .build()

// 导航中接收沿路交通
override fun onAlongRouteTrafficUpdated(alongRouteTraffic: AlongRouteTraffic) {
    mainHandler.post {
        // 更新 HMI 交通条 / 事件列表
        trafficBar.updateTrafficInfo(alongRouteTraffic)
        alongRouteTraffic.alongRouteTrafficIncidents?.let { showIncidentList(it) }

        // 地图刷新路线路况着色
        mapView.routesController()?.refreshAlongRouteTraffic(alongRouteTraffic)
    }
}

与其它能力的关系

能力	关系
更优的路	BetterRouteProposal.blockingIncidents / blockingFlows 描述更优路检测时的阻塞交通，数据模型与本文 incident / flow 相同
换路通知	换路成功后沿路交通会随新路线重新推送
算路结果	首屏路线上的交通字段可用于算路预览；导航中持续更新以本回调为准

注意事项

• setTrafficFetchRange 须在创建 NavigationService 时设置，导航中无法修改。
• 回调线程： Message 线程，更新 UI / MapView 请切主线程。
• additionalInfo 仅供调试，生产环境请勿依赖。
• 地图着色仅刷新路况颜色，不改变路线几何；换路后需按 换路通知 更新路线上下文。
• 首次 / 换路后首次回调： 首次开始导航或换路完成后，onAlongRouteTrafficUpdated 通常会再回调一次；该次 Traffic 来自 Cloud 算路结果自带的 traffic，仅包含 alongRouteTrafficFlow，不包含 alongRouteTrafficIncidents。算路结果中的 traffic 与本地缓存的底图 Traffic 可能采集于不同时刻，展示上可能存在差异；待 SDK 下一次沿路 Traffic 请求返回后，二者会刷新为一致。
• 空列表： alongRouteTrafficFlow 和 alongRouteTrafficIncidents 为空时，通常表示网络环境异常，应清空 HMI 沿路 Traffic 展示（交通条、事件列表、地图路况着色等）。
• 交通数据具有时效性，以 SDK 周期性推送为准；弱网时可能出现数据延迟。