Skip to content

截图

本指南：截取当前地图画面、生成离屏截图，并监听每帧地图状态。

功能介绍

MapView 支持两种截图方式：

方式 接口 适用场景
当前视图截图 generateSnapshot(callback) 截取屏幕上正在显示的地图
离屏区域截图 generateOffscreenSnapshot(config) 截取指定尺寸/缩放级别的地图区域（不影响主视图）

此外，addMapViewListener 可在每帧回调中读取相机、车辆位置与缩放级别，适合 HUD 更新或截图前状态确认。

核心接口一览

分类 接口 说明
截图 generateSnapshot(callback) 当前视图截图
截图 generateOffscreenSnapshot(config) 离屏截图（推荐）
帧监听 addMapViewListener(listener) 每帧地图状态回调
帧监听 removeMapViewListener(listener) 移除监听
视图尺寸 getViewWidth() / getViewHeight() 当前 MapView 宽高

接口详细说明

1. generateSnapshot — 当前视图截图

截取 MapView 当前正在渲染的画面，结果通过回调异步返回。

效果示意：

离屏截图示例（建筑区域）

1
2
3
fun generateSnapshot(
    callback: SnapshotReadyCallback
)
参数 类型 说明
callback SnapshotReadyCallback 截图完成回调

SnapshotReadyCallback： 

1
2
3
fun onSnapshotReady(
    bitmap: Bitmap
)

参数 类型 说明
bitmap Bitmap 截图结果；注意内存占用

示例代码： 

1
2
3
4
5
mapView.generateSnapshot { bitmap ->
    saveToGallery(bitmap)
    // 不再使用时及时释放
    // bitmap.recycle()
}

建议在地图已渲染后调用（如 onDrawFirstFrame 或 MapViewStatusListener.onDrawFirstFrame 之后）。

2. generateOffscreenSnapshot — 离屏截图

在不影响主 MapView 的情况下，生成指定尺寸和缩放级别的截图。推荐用于分享卡片、缩略图预览等场景。

效果示意：

离屏截图

1
2
3
fun generateOffscreenSnapshot(
    config: OffscreenSnapshotInitParams
)
参数 类型 说明
config OffscreenSnapshotInitParams 离屏截图配置

OffscreenSnapshotInitParams 字段：

字段 类型 默认 说明
width Int — 截图宽度（像素）
height Int — 截图高度（像素）
zoomLevel Float Camera.DEFAULT_ZOOM_LEVEL 截图缩放级别
readyListener MapViewReadyListener<MapSubView?>? — 离屏渲染就绪监听；无定制需求传 null
callback SnapshotReadyCallback — 截图完成回调

示例代码： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
mapView.generateOffscreenSnapshot(
    OffscreenSnapshotInitParams(
        width = 800,
        height = 600,
        zoomLevel = 14f,
        readyListener = null,
        callback = object : MapView.SnapshotReadyCallback {
            override fun onSnapshotReady(bitmap: Bitmap) {
                showPreview(bitmap)
            }
        }
    )
)

仅可从 主 MapView 调用；MapSubView 不支持离屏截图。

3. addMapViewListener — 帧更新监听

每帧地图渲染完成后回调，可读取当前相机、车辆位置与缩放信息。 

1
2
3
fun addMapViewListener(
    listener: MapViewListener
)

参数 类型 说明
listener MapViewListener 帧更新监听器 
1
2
3
fun removeMapViewListener(
    listener: MapViewListener
)
参数 类型 说明
listener MapViewListener 移除监听

MapViewListener 回调： 

1
2
3
4
5
6
mapView.addMapViewListener { mapViewData ->
    val zoom = mapViewData.zoomLevel
    val cameraLoc = mapViewData.cameraLocation
    val carLoc = mapViewData.carLocation
    val rangeH = mapViewData.rangeHorizontal  // 水平可视范围（米）
}

MapViewData 字段 说明
cameraLocation 相机位置
carLocation 车辆位置
zoomLevel 缩放级别
rangeHorizontal 水平可视范围（米）

示例代码： 

1
2
3
mapView.addMapViewListener { data ->
    updateHud(data.carLocation, data.zoomLevel)
}

与 MapDiagnosis 的区别：MapViewListener 每帧 回调位置数据；MapViewStatusListener 侧重 生命周期事件（首帧、Surface 变化）。详见 地图状态监听。

4. getViewWidth / getViewHeight — 视图尺寸

接口方法 返回值 说明
getViewWidth() Int 当前 MapView 宽度（像素）
getViewHeight() Int 当前 MapView 高度（像素）

示例代码： 

1
2
val w = mapView.getViewWidth()
val h = mapView.getViewHeight()

注意事项

  • 截图需在地图已渲染后进行，建议在 onDrawFirstFrame 之后调用。
  • Bitmap 注意内存占用，大图及时释放。
  • 离屏截图仅主 MapView 支持，不可从 MapSubView 调用。
  • 高频 addMapViewListener 回调注意性能，避免在回调中做重计算。

相关指南