Skip to content

地图状态监听

本指南：通过 MapDiagnosis 监听首帧绘制与地图运行状态，用于延迟初始化与调试。

功能介绍

MapDiagnosis 提供地图视图 运行状态查询 与 生命周期事件监听，用于首帧检测、性能分析、调试 HUD 等。适合在 onReady 之后、首帧绘制完成时进行首次地图配置，避免过早操作导致配置无效。

获取入口： 

1
val diagnosis = mapView.mapDiagnosis()

核心接口一览

方法 / 属性 说明
addMapViewListener(listener) 添加状态监听器
removeMapViewListener(listener) 移除监听器
mapViewStatus 当前地图状态快照（只读）

接口详细说明

1. addMapViewListener — 注册状态监听

1
2
3
fun addMapViewListener(
    listener: MapViewStatusListener?
)
参数 类型 说明
listener MapViewStatusListener? 状态监听器；传 null 不添加

MapViewStatusListener 回调：

回调 说明 典型用途
onDrawFirstFrame() 首帧绘制完成 推荐在此进行首次地图配置（特性开关、车辆位置等）
onMapSurfaceChanged() Surface 尺寸或结构变化 屏幕旋转、分屏、Surface 重建

示例代码： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
mapView.mapDiagnosis()?.addMapViewListener(object : MapViewStatusListener {
    override fun onDrawFirstFrame() {
        // 首帧后安全配置地图
        mapView.getFeaturesController()?.traffic()?.setEnabled()
        mapView.getVehicleController()?.setLocation(currentLocation)
        mapView.getCameraController()?.enableFollowVehicleMode(
            Camera.FollowVehicleMode.HeadingUp,
            useAutoZoom = true
        )
    }

    override fun onMapSurfaceChanged() {
        // Surface 变化，如旋转、分屏
        recomputeLayout()
    }
})

建议在 onDrawFirstFrame 中执行首次配置，而非仅在 onReady 中操作，避免首帧前配置无效。

2. removeMapViewListener — 移除监听

1
2
3
fun removeMapViewListener(
    listener: MapViewStatusListener?
)
参数 类型 说明
listener MapViewStatusListener? 需要移除的监听器实例

示例代码： 

1
mapView.mapDiagnosis()?.removeMapViewListener(myListener)

3. mapViewStatus — 读取当前状态快照

返回当前地图运行状态的一次性快照，适合调试面板轮询或日志输出。

字段 类型 说明
cameraLatitude / cameraLongitude Double 相机中心经纬度
cameraHeading — 相机朝向
carLatitude / carLongitude Double 车辆经纬度
zoomLevel — 当前缩放级别
isAnimating Boolean 是否正在执行相机动画
interactionMode InteractionMode 用户交互状态（手势 / 空闲等）
renderMode RenderMode 当前 2D / 3D 渲染状态
isAutoZoomAnimationRunning Boolean 自动缩放动画是否运行中

示例代码： 

1
2
3
4
5
val status = mapView.mapDiagnosis()?.mapViewStatus
status?.let {
    Log.d("MapDiag", "zoom=${it.zoomLevel}, animating=${it.isAnimating}, " +
        "interaction=${it.interactionMode}, render=${it.renderMode}")
}

InteractionMode / RenderMode 定义于 com.telenav.map.api.diagnosis 包，用于状态监控场景，与 Camera.RenderMode 概念相关但用途不同。

与其他监听的区别

监听器 回调频率 侧重
MapViewStatusListener（本指南） 生命周期事件 + 状态快照 首帧检测、Surface 变化、运行状态
MapViewListener（截图） 每帧 相机/车辆位置、缩放、可视范围
MapViewReadyListener（快速开始） 一次 地图就绪，可获取 Controller

注意事项

  • MapDiagnosis 接口主要用于集成调试与状态监控，量产逻辑勿强依赖内部字段语义变更。
  • mapViewStatus 可轮询，但高频轮询注意性能。
  • ClusterMapView 同样提供 mapDiagnosis()，用法一致。

相关指南