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>）

AlertItem

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

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

具体哪个可选字段有效，取决于 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。

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_END_CAMERA 5 区间测速终点摄像头
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 区间测速摄像头
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
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.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；勿读取 AlertEvent 内已 @Deprecated 的高速、车道字段。
  • distanceToVehicle 为 沿路距离，非直线距离。
  • 关闭检测：enableAlertDetection(false) 后不再收到 onAlertEventUpdated，但监听仍可注册。
  • 与高速出口、车道推荐分通道推送；高速/车道内容请使用对应回调（见第 3、4 节文档）。