Skip to content

2 一般道路信息

功能介绍

一般道路信息通过 AlertEventListener.onAlertEventUpdated 推送，载荷为 AlertEvent。SDK 在预测行驶路径上持续检测并更新 前方（ahead） 的 Alert 条目，涵盖电子眼、限速、交通指示牌、道路设施、限行区域等。

典型用途包括：限速与电子眼预告、施工/事故/拥堵提示、隧道/收费站/边境等道路设施提醒。

前置条件： 未调用 NavigationServiceOptions.disableAlert()，且 alertManager.enableAlertDetection(true)（默认已开启）。见 概述。

回调接口

1
fun onAlertEventUpdated(alertEvent: AlertEvent)

触发时机： 导航会话存活期间，路径上的 Alert 集合发生变化时触发（SDK 会持续更新）。

不宜在回调内执行长时间阻塞操作。

AlertEvent

AlertEvent 仅使用前方字段（高速 / 车道字段、以及后方字段已废弃，勿使用）：

字段 说明
aheadAlertItems 前方预测路径上的 Alert 列表（List<AlertItem>）
behindAlertItems 车辆后方已通过路径上的 Alert 列表（已废弃，后续版本将移除；请仅使用 aheadAlertItems）

AlertItem

单条 Alert 由类型与多种可选详情组成：

字段 说明
basicInfo 基础信息（必填），见下表
pointInfo 点状 Alert 的位置信息
zoneInfo 区域状 Alert 的范围信息（如学校区、限行区）
cameraInfo 电子眼相关信息
restrictionInfo 道路通行限制（物理/法规/时段等）
crossBorderInfo 跨境信息
steepGradeInfo 陡坡信息
speedLimit 限速信息
tightenedSpeedLimitInfo 前方收紧限速预告
tollboothInfo 收费站信息
trafficIncidentInfo 交通事件（事故、施工、拥堵、封路等）
trafficFlowInfo 交通流信息（类型为 TRAFFIC_FLOW 时）
intersectionApproachingInfo 路口减速提醒
highwayMergePointInfo 高速汇入点提醒（类型为 HIGHWAY_MERGE_POINT 时）
sectionSpeedCameraInfo 区间测速信息（类型为 SECTION_SPEED_CAMERA 时）

具体哪个可选字段有效，取决于 basicInfo.type（AlertType）。

AlertBasicInfo

字段 说明
type Alert 类型，取值为 AlertType 常量（如 SPEED_CAMERA、TUNNEL、CONGESTION 等）
id Alert 唯一标识；同类型且同位置的 Alert 具有相同 id
distanceToVehicle 沿道路到车辆的距离（米）；区域 Alert 在区域内时为 0

TrafficFlowInfo

类型为 TRAFFIC_FLOW 时，AlertItem.trafficFlowInfo 有效：

字段 类型 说明
estimatedTime Int? 预计通过时间（秒）
flowLevel Int（TrafficLevel） 交通流等级；交通流 Alert 不会输出 FREE_FLOW 与 UNKNOWN_LEVEL
averageSpeed Float? 平均速度（米/秒）；默认 null

TrafficLevel 常用常量见 沿途交通 · TrafficLevel。

SectionSpeedCameraInfo（区间测速）

类型为 SECTION_SPEED_CAMERA（86）时，AlertItem.sectionSpeedCameraInfo 非空。区间信息在 zoneInfo。

  • 路径未经过 section start camera 时，distanceToSectionStartCamera 为 null，zoneInfo.beginLocation 也为 null。
  • 检测范围内没有对应的 section end camera 时，distanceToSectionEndCamera 为 null，zoneInfo.endLocation 也为 null。
  • 只有 section start camera 与 section end camera 都存在时，SDK 才会计算出有效的 averageSpeed；任一端缺失时 averageSpeed 为 null。
  • 任一端摄像头缺失时，zoneInfo.enteredDistance 为 0，zoneInfo.length 为 -1（无效）。

SECTION_START_CAMERA（4）与 SECTION_END_CAMERA（5）已废弃，请改用 SECTION_SPEED_CAMERA。

字段 类型 说明
speedLimit SpeedLimit 区间限速
averageSpeed Float? 自区间起点以来的平均速度（米/秒）。仅当起点与终点摄像头都存在时有效；任一端缺失时为 null
distanceToSectionStartCamera Int? 车辆到起点摄像头的有符号距离（米）。正值表示在前方，0 或负值表示已通过。路径未经过起点摄像头时为 null（此时 zoneInfo.beginLocation 也为 null）
distanceToSectionEndCamera Int? 车辆到终点摄像头的有符号距离（米）。正值表示在前方，0 或负值表示已通过。检测范围内没有对应终点摄像头时为 null（此时 zoneInfo.endLocation 也为 null）

HMI 宜用 speedLimit、averageSpeed、distanceToSectionEndCamera 更新区间测速界面。

AlertType

AlertBasicInfo.type 取值为 AlertType 整型常量。下表与 SDK AlertType 定义一致（数值 29、30、42、87 未使用）。

常量 值 说明
SPEED_CAMERA 0 测速摄像头
RED_LIGHT_CAMERA 1 闯红灯摄像头
BUS_LANE_CAMERA 2 公交专用道摄像头
RED_LIGHT_AND_SPEED_CAMERA 3 闯红灯兼测速摄像头
SECTION_START_CAMERA 4 区间测速起点摄像头（已废弃，请用 SECTION_SPEED_CAMERA）
SECTION_END_CAMERA 5 区间测速终点摄像头（已废弃，请用 SECTION_SPEED_CAMERA）
DISTANCE_CAMERA 6 距离测速摄像头
NO_LR_TURNS_CAMERA 7 禁止左右转摄像头
OTHER_CAMERA 8 其它类型摄像头
BEGINNING_POINT_OF_LANE_AND_SPEEDING_VIOLATION_BLOCK_CAMERA 9 车道及超速违章区间起点摄像头
EXCLUSIVE_BUS_LANE_AND_SPEEDING_VIOLATION_CAMERA 10 公交专用道及超速违章摄像头
EXCLUSIVE_BUS_LANE_VIOLATION_CAMERA 11 公交专用道违章摄像头
INFORMATION_GATHERING_CAMERA 12 信息采集摄像头
LOADING_VIOLATION_CAMERA 13 装载违章摄像头
NO_PASSING_ENFORCEMENT_CAMERA 14 禁止超车执法摄像头
OTHER_VIOLATION_CAMERA 15 其它违章摄像头
OVERLOADING_VIOLATION_CAMERA 16 超载违章摄像头
PARKING_VIOLATION_CAMERA 17 违章停车摄像头
SHOULDER_LANE_ENFORCEMENT_CAMERA 18 路肩车道执法摄像头
STOP_SIGN 19 停车让行标志
SCHOOL_ZONE 20 学校区域（区域 Alert，宜结合 zoneInfo）
BEGIN_OVERTAKING 21 超车开始
END_OVERTAKING 22 超车结束
PROTECTED_OVERTAKING_EXTRA_LANE 23 保护超车附加车道
PROTECTED_OVERTAKING_EXTRA_RIGHT 24 保护超车附加右侧车道
PROTECTED_OVERTAKING_EXTRA_LEFT 25 保护超车附加左侧车道
LANE_MERGE_RIGHT 26 右侧车道汇入
LANE_MERGE_LEFT 27 左侧车道汇入
LANE_MERGE_CENTER 28 中间车道汇入
ROAD_NARROWS 31 道路变窄
SHARP_CURVE_LEFT 32 向左急弯
SHARP_CURVE_RIGHT 33 向右急弯
WINDING_ROAD_STARTING_LEFT 34 连续弯路（左侧起始）
WINDING_ROAD_STARTING_RIGHT 35 连续弯路（右侧起始）
BEGIN_OVERTAKING_TRUCKS 36 货车超车开始
END_OVERTAKING_TRUCKS 37 货车超车结束
STEEP_HILL_UPWARDS 38 上陡坡（宜结合 steepGradeInfo）
STEEP_HILL_DOWNWARDS 39 下陡坡（宜结合 steepGradeInfo）
LATERAL_WIND 40 横风
GENERAL_WARNING_SIGN 41 一般警告标志
RISK_OF_GROUNDING 43 搁浅风险
GENERAL_CURVE 44 一般弯道
END_OF_ALL_RESTRICTIONS 45 所有限制结束
GENERAL_HILL 46 一般坡道
ANIMAL_CROSSING 47 动物穿越
ICY_CONDITIONS 48 结冰路面
SLIPPERY_ROAD 49 湿滑路面
FAILING_ROCKS 50 落石
LEFT_FAILING_ROCKS 51 左侧落石
RIGHT_FAILING_ROCKS 52 右侧落石
TRAMWAY_CROSSING 53 有轨电车横穿
CONGESTION_HAZARD 54 拥堵危险
ACCIDENT_HAZARD 55 事故危险
PRIORITY_OVER_ONCOMING_TRAFFIC 56 对向来车让行优先
YIELD_TO_ONCOMING_TRAFFIC 57 让行对向来车
CROSSING_WITH_PRIORITY_FROM_RIGHT 58 右侧来车优先的交叉口
PEDESTRIAN_CROSSING 59 人行横道
YIELD 60 让行
BEGIN_NO_ENGINE_BRAKE 61 禁止发动机制动开始
END_NO_ENGINE_BREAK 62 禁止发动机制动结束
NO_IDLING 63 禁止怠速
TRUCK_ROLLOVER 64 货车侧翻风险
BEGIN_LOW_GEAR 65 低速挡行驶开始
END_LOW_GEAR 66 低速挡行驶结束
URBAN_AREA 67 城区
EMBANKMENT 68 路堤
TWO_WAY_TRAFFIC 69 双向交通
UNEVEN_ROAD 70 路面不平
MAX_SPEED 71 最高限速
BICYCLE_CROSSING 72 自行车横穿
YIELD_TO_BICYCLES 73 让行自行车
FLOOD_AREA 74 积水区域
HUMP_BRIDGE 75 驼峰桥
S_TURNS 76 S 形弯道
WINDING_ROAD 77 连续弯路
CROSS_BORDER 78 跨境（宜结合 crossBorderInfo）
BLACK_SPOT 79 事故多发点
FERRY 80 轮渡
TUNNEL 81 隧道
OVER_PASS 82 上跨桥
UNDER_PASS 83 下穿通道
SPEED_BUMPER 84 减速带
UNPAVED 85 非铺装路面
SECTION_SPEED_CAMERA 86 区间测速摄像头（区域 Alert，结合 zoneInfo 与 sectionSpeedCameraInfo）
ACCESS_RESTRICTION 88 通行限制（区域 Alert，宜结合 restrictionInfo）
PHYSICAL_RESTRICTION 89 物理限制（区域 Alert，宜结合 restrictionInfo）
TIMED_RESTRICTION 90 时段限制（区域 Alert，宜结合 restrictionInfo）
RAINY_DAY_SPEED_LIMIT 91 雨天限速
SNOWY_DAY_SPEED_LIMIT 92 雪天限速
TIME_SPEED_LIMIT 93 分时段限速
SEASONAL_TIME_SPEED_LIMIT 94 季节性分时段限速
LANE_SPEED_LIMIT 95 分车道限速
FOGGY_DAY_SPEED_LIMIT 96 雾天限速
POLICE_CHECK_POINT 97 警察检查点（宜结合 trafficIncidentInfo）
ACCIDENT 98 交通事故（宜结合 trafficIncidentInfo）
ACCIDENT_CLEARED 99 事故已清除（宜结合 trafficIncidentInfo）
ROAD_CONSTRUCTION 100 道路施工（宜结合 trafficIncidentInfo）
ROAD_CONSTRUCTION_ENDED 101 道路施工结束（宜结合 trafficIncidentInfo）
BLOCKED_ROAD 102 道路封闭（宜结合 trafficIncidentInfo）
HAZARDOUS_ROAD 103 危险路况（宜结合 trafficIncidentInfo）
HAZARDOUS_ROAD_PASSED 104 危险路况已通过（宜结合 trafficIncidentInfo）
LANE_RESTRICTION 105 车道限制（宜结合 trafficIncidentInfo）
LANE_RESTRICTION_OVER 106 车道限制解除（宜结合 trafficIncidentInfo）
CONGESTION 107 拥堵（宜结合 trafficIncidentInfo）
CONGESTION_CLEARED 108 拥堵缓解（宜结合 trafficIncidentInfo）
ENTRY_BLOCK 109 入口封闭（宜结合 trafficIncidentInfo）
ENTRY_REOPEN 110 入口重新开放（宜结合 trafficIncidentInfo）
EXIT_BLOCK 111 出口封闭（宜结合 trafficIncidentInfo）
EXIT_REOPEN 112 出口重新开放（宜结合 trafficIncidentInfo）
TRAFFIC_FLOW 113 交通流（宜结合 trafficFlowInfo）
ROAD_WORK 114 道路作业
RAILWAY_CROSSING 115 铁路道口
HIGH_VIGILANCE_AREA 116 高警觉区域（区域 Alert；部分地区替代超速摄像头提示）
TRAFFIC_LIGHT 117 交通信号灯
TOLLBOOTH 118 收费站（宜结合 tollboothInfo）
SPEED_LIMIT_TIGHTENED 119 前方限速收紧（宜结合 tightenedSpeedLimitInfo）
INTERSECTION_APPROACHING 120 前方路口，建议减速（宜结合 intersectionApproachingInfo）
HAZARDOUS_MATERIAL_RESTRICTION 121 危险品通行限制
HIGHWAY_MERGE_POINT 122 高速汇入点（宜结合 highwayMergePointInfo）
ORDINARY_SPEED_LIMIT 300 普通限速
INVALID 1000 无效类型

示例代码

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
navigationService.eventHub.addAlertEventListener(object : AlertEventListener {
    override fun onAlertEventUpdated(alertEvent: AlertEvent) {
        alertEvent.aheadAlertItems?.forEach { item ->
            val id = item.basicInfo.id
            val type = item.basicInfo.type
            val distance = item.basicInfo.distanceToVehicle

            when (type) {
                AlertType.SPEED_CAMERA -> {
                    // 常规 Alert：展示电子眼预告（可结合 item.cameraInfo、item.speedLimit）
                    showCameraAlert(id, distance)
                }
                AlertType.SECTION_SPEED_CAMERA -> {
                    val info = item.sectionSpeedCameraInfo ?: return@forEach
                    showSectionSpeedCamera(
                        info.speedLimit,
                        info.averageSpeed,
                        info.distanceToSectionEndCamera
                    )
                }
                AlertType.TRAFFIC_FLOW -> {
                    // 常规 Alert：展示交通流（estimatedTime、flowLevel、averageSpeed）
                    showTrafficFlowAlert(id, item.trafficFlowInfo)
                }
                AlertType.ACCESS_RESTRICTION,
                AlertType.PHYSICAL_RESTRICTION,
                AlertType.TIMED_RESTRICTION,
                AlertType.HAZARDOUS_MATERIAL_RESTRICTION -> {
                    // Restriction 专项：参考 handle_restriction_alerts.md
                    handleRestrictionAlert(item)
                }
                else -> {
                    // 其它 AlertType ...
                }
            }
        }
    }

    private fun handleRestrictionAlert(item: AlertItem) {
        val restriction = item.restrictionInfo ?: return
        val id = item.basicInfo.id
        val type = item.basicInfo.type
        val severity = restriction.severity
        val vehicleCategoryRestriction = restriction.vehicleCategoryRestriction

        // Restriction 当前主要面向 RV 场景
        if (vehicleCategoryRestriction != VehicleCategory.RV.ordinal) return

        when (type) {
            AlertType.ACCESS_RESTRICTION -> {
                if (severity == AlertSeverity.CRITICAL) {
                    // 车辆不可通行：在地图上标注受限区域
                    showAlertIconOnMap(id, type, item.zoneInfo?.beginLocation, item.zoneInfo?.endLocation)
                    restriction.divergeLocation?.let { diverge ->
                        val distanceToDivergeLocation =
                            item.basicInfo.distanceToVehicle - diverge.distanceFromAlertPoint
                        showHintIconOnMap(id, type, diverge.location, distanceToDivergeLocation)
                    }
                }
            }
            AlertType.PHYSICAL_RESTRICTION -> {
                if (severity == AlertSeverity.CRITICAL) {
                    // 超限不可通行：可与车辆尺寸对比给出具体原因
                    showAlertIconOnMap(id, type, item.zoneInfo?.beginLocation, item.zoneInfo?.endLocation)
                    val dimensions = SDK.getInstance().vehicleInfoProvider.getDimensions()
                    if (dimensions != null) {
                        if (restriction.lengthRestriction != null && dimensions.length > restriction.lengthRestriction!!) {
                            showRestrictionReason("length exceeds restriction")
                        }
                        if (restriction.widthRestriction != null && dimensions.width > restriction.widthRestriction!!) {
                            showRestrictionReason("width exceeds restriction")
                        }
                        if (restriction.heightRestriction != null && dimensions.height > restriction.heightRestriction!!) {
                            showRestrictionReason("height exceeds restriction")
                        }
                        if (restriction.grossMassRestriction != null &&
                            dimensions.grossVehicleMass > restriction.grossMassRestriction!!
                        ) {
                            showRestrictionReason("gross mass exceeds restriction")
                        }
                    }
                } else if (severity == AlertSeverity.MEDIUM) {
                    showRestrictionReason("pass with caution")
                }
            }
            AlertType.TIMED_RESTRICTION -> {
                if (severity == AlertSeverity.CRITICAL) {
                    // 已处于禁行时段
                    showAlertIconOnMap(id, type, item.zoneInfo?.beginLocation, item.zoneInfo?.endLocation)
                } else if (severity == AlertSeverity.MEDIUM) {
                    // 预计将进入生效时段（通常用于提前提醒）
                    restriction.divergeLocation?.let { diverge ->
                        val distanceToDivergeLocation =
                            item.basicInfo.distanceToVehicle - diverge.distanceFromAlertPoint
                        showHintIconOnMap(id, type, diverge.location, distanceToDivergeLocation)
                    }
                }
            }
            AlertType.HAZARDOUS_MATERIAL_RESTRICTION -> {
                if (severity == AlertSeverity.CRITICAL) {
                    showAlertIconOnMap(id, type, item.zoneInfo?.beginLocation, item.zoneInfo?.endLocation)
                    restriction.hazardousMaterialTypes?.forEach { material ->
                        showHazardousMaterialTag(material)
                    }
                    restriction.tunnelCategory?.let { category ->
                        showTunnelCategoryTag(category)
                    }
                }
            }
        }
    }

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

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

注意事项

  • 仅处理 aheadAlertItems。behindAlertItems 已废弃，后续版本将移除。
  • 区间测速使用 AlertType.SECTION_SPEED_CAMERA 与 sectionSpeedCameraInfo。SECTION_START_CAMERA、SECTION_END_CAMERA 已废弃。
  • 勿读取 AlertEvent 内已 @Deprecated 的高速、车道字段。
  • distanceToVehicle 为 沿路距离，非直线距离。
  • 关闭检测：enableAlertDetection(false) 后不再收到 onAlertEventUpdated，但监听仍可注册。
  • 与高速出口、车道推荐分通道推送；高速/车道内容请使用对应回调（见第 3、4 节文档）。