沿途信息

功能介绍

沿途信息（Alert）在 导航会话存活期间 向 HMI 提供与预测行驶路径相关的动态提示，包括一般道路上的限速/电子眼/交通事件、高速或快速路上的出口与服务区、以及车道级推荐等。

本章节按信息类别拆分为以下文档，建议按序号阅读：

序号	文档	说明
1	本文（概述）	Alert 初始化、开关、`AlertManager` 与监听注册
2	一般道路信息	`onAlertEventUpdated` / `AlertEvent` / `AlertItem`
3	高速或快速路信息	`onHighwayInfoUpdated` / `HighwayInfo`
4	车道推荐信息	`onLaneGuidanceInfoUpdated` / `LaneGuidanceInfo`

前置条件： 已完成主 SDK 与 NavigationService 初始化（见初始化）。沿途信息依赖 Alert 组件；关闭 Alert 后相关回调均不会触发。

数据流概览

NavigationService.Factory.createInstance(options)   ← Alert 组件随导航服务初始化
        ↓
navigationService.alertManager.enable*()            ← 运行时细分开关（可选）
        ↓
eventHub.addAlertEventListener(listener)
        ↓
导航中 / 巡航中 AlertService 持续探测（AlertService 线程）
        ↓
onAlertEventUpdated / onHighwayInfoUpdated / onLaneGuidanceInfoUpdated
        （Message 线程；eventHub 全部回调共用同一线程）
        ↓
HMI 展示

线程说明：

探测： 导航或巡航会话存活期间，AlertService 在 AlertService 线程 上持续做沿途检测（限速、电子眼、高速信息、车道推荐等）。
回调： 检测结果经 JNI 投递后，在 Message 线程（drv.msg）上解码并触发 AlertEventListener。eventHub 上的定位、导航、播报、沿途信息等 所有对外回调均在同一条 Message 线程上串行执行，集成方可在该线程上统一更新 UI，无需为各监听器单独切换线程。

Alert 初始化与开关

Alert 能力在创建 NavigationService 时一并初始化，分两层配置：

1. 创建时总开关（`NavigationServiceOptions`）

API	说明	默认值
`disableAlert()`	关闭整个 Alert 组件。同时会关闭语音引导（AudioGuidance）（存在依赖关系）。关闭后 `AlertManager` 各接口无效，且不会收到任何 `AlertEventListener` 回调	默认开启 Alert（不调用 `disableAlert`）

// 默认：Alert 开启
val navigationService = NavigationService.Factory.createInstance()

// 不需要沿途信息时
val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        .disableAlert()
        .build()
)

2. 运行时子功能开关（`AlertManager`）

在 Alert 组件 已开启 的前提下，通过 navigationService.alertManager 分别控制三类检测能力：

API	说明	默认值
`enableAlertDetection(enable)`	一般道路 Alert 检测（`onAlertEventUpdated`）	`true`
`enableHighwayInfoDetection(enable)`	高速 / 快速路信息检测（`onHighwayInfoUpdated`）	`true`
`enableLaneGuidanceDetection(enable)`	车道推荐信息检测（`onLaneGuidanceInfoUpdated`）	`false`

上述 API 均要求 Alert 组件已启用（未调用 disableAlert()）。若创建时已 disableAlert()，调用无效。

val navigationService = NavigationService.Factory.createInstance()

navigationService.alertManager.apply {
    enableAlertDetection(true)          // 一般道路，默认已开
    enableHighwayInfoDetection(true)    // 高速信息，默认已开
    enableLaneGuidanceDetection(true)   // 车道推荐，默认关闭，需显式开启
}

核心接口

接口 / 类	作用
`NavigationServiceOptions`	创建导航服务时配置；`disableAlert()` 关闭 Alert 与语音引导
`NavigationService.alertManager`	`AlertManager` 实例，运行时控制三类检测开关
`NavigationService.eventHub`	注册 `AlertEventListener`
`AlertEventListener`	沿途信息统一监听入口（三个回调）
`AlertEvent`	一般道路 Alert 载荷（`aheadAlertItems`）
`HighwayInfo`	高速 / 快速路信息载荷
`LaneGuidanceInfo`	车道推荐信息载荷

监听注册示例

val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        // .disableAlert()   // 不需要沿途信息时取消注释
        .build()
)

// 车道推荐默认关闭，按需开启
navigationService.alertManager.enableLaneGuidanceDetection(true)

navigationService.eventHub.addAlertEventListener(object : AlertEventListener {
    override fun onAlertEventUpdated(alertEvent: AlertEvent) {
        // 见「2 一般道路信息」
    }

    override fun onHighwayInfoUpdated(highwayInfo: HighwayInfo) {
        // 见「3 高速或快速路信息」
    }

    override fun onLaneGuidanceInfoUpdated(laneGuidanceInfo: LaneGuidanceInfo) {
        // 见「4 车道推荐信息」
    }
})

// 不再需要时
navigationService.eventHub.removeAlertEventListener(listener)

回调与场景说明

回调	触发概况	不触发 / 受限场景
`onAlertEventUpdated`	会话存活期间持续更新路径上的 Alert	`disableAlert()` 或 `enableAlertDetection(false)`
`onHighwayInfoUpdated`	在高速 / 快速路上行驶且已匹配到路线	导航偏航或 free drive 离路（off-road）时不通知
`onLaneGuidanceInfoUpdated`	存在车道级数据且已匹配到路线	同上；且默认需 `enableLaneGuidanceDetection(true)`

注意事项

先创建 NavigationService、再注册监听： AlertEventListener 须在 eventHub 上注册后才会收到回调。
车道推荐需显式开启： enableLaneGuidanceDetection 默认为 false，集成车道面板时务必打开。
不要依赖已废弃字段： AlertEvent 中的 aheadHighwayInfoItems、behindHighwayInfoItems、laneGuidanceInfo 已废弃，请分别使用 onHighwayInfoUpdated、onLaneGuidanceInfoUpdated。
与定位配合： 高速 / 车道类信息在偏航或 off-road 时不更新，需保证定位与路线匹配正常（见地图匹配）。
销毁时注销监听： 避免 removeAlertEventListener(null) 误删全部监听，应传入具体 listener 实例。