地图控件

2026-11-05评分加载中…

一、功能介绍

地图控件能把插件的地理信息实时绘制到 Pilot 的地图上:标出点位、勾画航迹、圈出区域,所有元素都以真实经纬度定位,随地图缩放平移自然贴合。配合图层分组,你可以把成百上千个标注按业务组织成不同图层(如 layer1、layer2),整层显隐、整层清空。

在 Pilot 上叠加空间信息有两条途径:地图控件(本文)把元素绘制到地图(俯视二维、可持久化);AR 投射把标注绘制到图传画面(第一人称视角、不持久化,见 AR 投射文档)。两者面向不同视图,可同时使用。本文聚焦地图控件,并在 2.6 介绍如何用一份「地图元素」同时投射到地图与 AR。

1.1 能力总览

地图能力描述
地图控件在地图上增删改查点、线、面、圆等标注
图层管理把控件按图层分组,整层显隐 / 清空
地图元素一份数据同时投射到地图与 AR 图传画面
地图状态监听地图就绪、缩放级别等状态

1.2 应用场景

  • 电力线巡检:把杆塔、巡检点位标注到地图
  • 边境巡逻:勾画巡逻航迹、圈出禁飞区域
  • 森林火情:按图层管理海量火点,整层显隐
  • 工地测绘:叠加实时地图元素并同步到 AR 图传画面

二、接口调用示例

以下示例假设你已完成 SDK 初始化,且插件与 Pilot 已连接就绪(连接状态获取见插件连接状态文档)。所有接口都通过管理器单例 MapWidgetManager.getInstance() 调用。

2.1 添加地图控件(addMapWidget)

一个地图控件由 MapWidget 表示:每个控件有一个自动生成的唯一 id,通过 drawerType(MapDrawerType)决定它是哪种图形,并填入对应的 Options。以标注点(Marker)为例:

val mapManager = MapWidgetManager.getInstance()                 // 获取管理器单例

val widget = MapWidget().apply {
    drawerType = MapDrawerType.MARKER                           // 控件类型:标注点
    name = "Tower-A12"                                          // 业务标识,不显示在地图上
    markerOptions = MapMarkerOptions().apply {
        setPoint(OpenLocation(0.0, 0.0, 0.0))                   // TODO: 替换为实际经纬度
        setTitle("杆塔 A12")                                     // 地图上显示的标题
        setNormalIConFileName("tower.png")                      // 图标文件名(需先上传,见下方说明)
        setClickable(true)
    }
}

mapManager.addMapWidget(widget, object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() { /* 保留 widget.id 供后续更新 / 删除 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

drawerType 与对应 Options 一一对应,换一种图形只需换 drawerType 并填对应 Options:

MapDrawerType对应 Options关键字段
MARKER / PINMapMarkerOptionspoint、title、normalIConFileName、clickable、draggable
POLYLINEMapPolylineOptionspoints、width、color、dashed
POLYGONMapPolygonOptionspoints、fillColor、strokeColor、width
CIRCLEMapCircleOptionscenter、radius、fillColor、strokeColor

说明: MapWidget.name 仅作业务标识(日志 / 查询用),不会显示在地图上;要在地图上显示文字,用 MapMarkerOptions.setTitle(...)。

Marker 的 normalIConFileName / clickedIConFileName 传的是文件名,图标需先通过文件传输上传到 Pilot 端,此处按文件名引用。

效果预览:

2.2 批量添加与查询(addMapWidgets / queryMapWidgets / queryMapWidgetsByLayer)

GIS 数据批量同步时用批量添加,一次 IPC 完成多个控件;查询用于「拿回对象再改 / 删」或页面重建时回显:

// 批量添加
mapManager.addMapWidgets(widgetList, object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() { /* 批量添加成功 */ }
    override fun onFailure(error: IDJIError) { /* 如 PAYLOAD_TOO_LARGE:拆小批次 */ }
})

// 查询当前插件添加的所有控件
mapManager.queryMapWidgets(object : CommonCallbacks.CompletionCallbackWithParam<List<MapWidget>> {
    override fun onSuccess(widgets: List<MapWidget>) {
        // 每个 widget 的 id 均为服务端有效 id,可直接用于后续 update / remove
    }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

只查某一图层时用 queryMapWidgetsByLayer(layerId, callback),回调同样返回 List<MapWidget>。

注意: 受 Android Binder 传输限制,单次批量数据不应超过 512KB,超限回调 PAYLOAD_TOO_LARGE。建议单次不超过约 500 个简单 Marker,或 200 个含坐标列表的折线 / 多边形;超限时拆小批次重试。

效果预览:

批量查询

2.3 更新与删除(updateMapWidgets / removeMapWidgetsByIds)

推荐「query → 改字段 → update」:从 query 拿到对象,改可变字段后传回。服务端按 id 匹配就地更新:

// widget 来自 queryMapWidgets 的返回,改标题后更新
widget.markerOptions.setTitle("杆塔 A12(已巡检)")
mapManager.updateMapWidgets(listOf(widget), object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() { /* 更新成功 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

// 按 id 批量移除
mapManager.removeMapWidgetsByIds(listOf(widget.id), object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() { /* 已移除 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

id / source / layerId 是不可变字段,更新时不能修改。

注意: 修改了不可变字段会回调 WIDGET_FIELD_IMMUTABLE。需要把控件换到其他图层时,请先 removeMapWidgetsByIds 移除,再用新的 layerId 重新 addMapWidgets。

效果预览:

更新删除

2.4 图层管理(addLayer / setLayerVisible / clearLayer / removeLayer)

图层(MapWidgetLayer)是控件的逻辑分组容器。给 MapWidget.setLayerId(...) 指定图层后,就能对整层做显隐、清空。不设置 layerId 的控件归入默认层。

// 1. 建图层,回调成功后 layer.id 即该图层 id
val layer = MapWidgetLayer("layer1")
mapManager.addLayer(layer, object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() {
        val layerId = layer.id
        // 2. 添加控件时归入该图层
        val w = MapWidget().apply {
            drawerType = MapDrawerType.MARKER
            setLayerId(layerId)
            markerOptions = MapMarkerOptions().apply { setPoint(OpenLocation(0.0, 0.0, 0.0)) }
        }
        mapManager.addMapWidget(w, object : CommonCallbacks.CompletionCallback {
            override fun onSuccess() { /* 已加入 layer1 */ }
            override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
        })
    }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

// 整层显隐 / 清空整层(保留图层本身)/ 删除图层(连同层下所有控件)
mapManager.setLayerVisible(layerId, false, callback)
mapManager.clearLayer(layerId, callback)
mapManager.removeLayer(layerId, callback)

注意: 默认层(layerId 为空)只读——不能删除、不能设可见性、不能清空,否则回调 LAYER_READONLY;对不存在的图层操作回调 LAYER_NOT_FOUND。

效果预览:

图层绘制

建层并绘制

图层隐藏

整层隐藏

2.5 监听地图状态(addMapStateListener)

地图状态监听用于在批量绘制前确认地图已就绪。注册后会立即回调一次当前缓存状态,之后地图就绪或缩放变化时再次回调:

private val mapStateListener = IMapStateListener { mapState ->
    val ready = mapState.isMapReady                             // 地图是否就绪
    val zoom = mapState.zoom                                   // 当前缩放级别
    if (ready) { /* 地图就绪,可开始批量绘制控件 */ }
}

mapManager.addMapStateListener(mapStateListener)               // 同一监听重复添加会自动去重
// 页面销毁时移除
mapManager.removeMapStateListener(mapStateListener)

2.6 地图元素与 AR 同步(insertMapElement / updateMapElement / deleteMapElement / queryMapElement)

前面的地图控件只画在地图上。如果你希望一份数据同时出现在地图和 AR 图传画面里,用「地图元素」MapElement——它带一个 isArShow 开关(默认 true),开启后同一元素会同步投射为 AR 标注。这是叠加 AR 的另一条路径,与 AR 投射文档 的独立 AR 体系相比,胜在「地图 + AR 一份数据双端呈现」。

地图元素同样构成完整的增删改查:

// 增:构造元素并插入,成功回调返回服务端 UUID
val element = MapElement().apply {
    drawerType = MapDrawerType.POLYLINE                         // 元素类型:折线
    points = listOf(                                            // TODO: 替换为实际坐标列表
        OpenLocation(0.0, 0.0, 50.0),
        OpenLocation(0.0, 0.0, 50.0)
    )
    color = MapElementColor.YELLOW                              // 元素颜色(枚举)
    name = "element1"
    isArShow = true                                            // 同步投射到 AR 图传画面
}
mapManager.insertMapElement(element, object : CommonCallbacks.CompletionCallbackWithParam<UUID> {
    override fun onSuccess(id: UUID) { /* 服务端赋予的 UUID,已同步到 element.id */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

// 查:拉取当前所有地图元素
mapManager.queryMapElement(object : CommonCallbacks.CompletionCallbackWithParam<List<MapElement>> {
    override fun onSuccess(list: List<MapElement>) {
        val target = list.firstOrNull { it.name == "element1" } ?: return
        // 改:改字段后传回(服务端按 id 匹配)
        target.color = MapElementColor.RED
        mapManager.updateMapElement(target, object : CommonCallbacks.CompletionCallback {
            override fun onSuccess() { /* 更新成功 */ }
            override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
        })
        // 删:按 id 定位,整体传回即可
        mapManager.deleteMapElement(target, object : CommonCallbacks.CompletionCallback {
            override fun onSuccess() { /* 删除成功 */ }
            override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
        })
    }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

常见变体:

  • 只想画在地图、不投 AR:把 isArShow 设为 false。
  • 临时隐藏 / 恢复服务端所有 AR 标注:mapManager.hideARAnnotations(true, callback)(传 false 恢复),不影响地图上的显示。

效果预览:

地图元素同步 AR


三、API 参考

以下接口方法的完整定义(含入参数据模型、枚举)请查看 API 文档:IMapWidgetManageropen in new window。

IMapWidgetManager 是服务端地图操作接口总入口,对外开放以下方法:

项说明
IMapWidgetManager地图操作接口总入口
addMapWidget添加单个地图控件
addMapWidgets批量添加地图控件
updateMapWidgets批量更新地图控件(按 id 匹配)
removeMapWidget移除单个地图控件
removeMapWidgetsByIds按 id 批量移除地图控件
queryMapWidgets查询本插件添加的所有控件
queryMapWidgetsByLayer按图层查询控件
addLayer添加图层
removeLayer删除图层(连同层下控件)
setLayerVisible设置图层可见性
clearLayer清空图层(保留图层本身)
insertMapElement新增地图元素(可同步 AR),返回 UUID
updateMapElement更新地图元素
deleteMapElement删除地图元素
queryMapElement查询地图元素
hideARAnnotations隐藏 / 显示服务端 AR 标注
addMapStateListener添加地图状态监听
removeMapStateListener移除地图状态监听

四、Sample 源码获取

地图控件 Sampleopen in new window


五、常见问题(FAQ)

Q1:updateMapWidgets 回调 WIDGET_FIELD_IMMUTABLE?

你修改了不可变字段。id / source / layerId 不能通过更新修改。需要把控件移到其他图层时,请先 removeMapWidgetsByIds 移除,再用新的 layerId 重新 addMapWidgets。

Q2:批量添加回调 PAYLOAD_TOO_LARGE?

受 Android Binder 传输限制,单次批量数据不应超过 512KB。请拆成更小的批次多次提交(建议单次不超过约 500 个简单 Marker,或 200 个含坐标列表的折线 / 多边形)。

Q3:删除 / 显隐 / 清空图层回调 LAYER_READONLY 或 LAYER_NOT_FOUND?

  • LAYER_READONLY:对默认层(layerId 为空)做了删除 / 设可见 / 清空操作,默认层只读。请只对自建图层操作。
  • LAYER_NOT_FOUND:图层 id 不存在,确认该图层已通过 addLayer 创建成功。

Q4:Marker 图标不显示?

normalIConFileName / clickedIConFileName 传的是文件名,图标需先通过文件传输上传到 Pilot 端。确认文件已上传、文件名大小写完全一致。

Q5:注册地图状态监听后为什么立刻收到一次回调?

这是设计行为。addMapStateListener 注册成功后会立即用当前缓存的地图状态回调一次,方便你拿到初始状态;之后地图就绪或缩放变化时再次回调。同一监听重复添加会自动去重,不会收到多份通知。

Q6:地图元素(MapElement)和地图控件(MapWidget)怎么选?

  • 只画在地图上、需要点击弹窗 / 图层分组等丰富交互,用 MapWidget(2.1 ~ 2.5)。
  • 希望一份数据同时出现在地图和 AR 图传画面,用 MapElement 并把 isArShow 设为 true(2.6)。
  • 若只做 AR、不需要地图,用独立的 AR 体系更合适,见 AR 投射文档。

附录:错误码速查

以下错误码来自 dji.open.pilot.base.error.RemoteError:

错误码常量触发场景处理建议
REMOTE_DISCONNECTED连接未就绪时调用等连接状态就绪后重试
WIDGET_FIELD_IMMUTABLE更新时修改了 id / source / layerId换层请先移除再重新添加;见 Q1
WIDGET_NOT_FOUND控件 id 在服务端不存在确认 id 来源于已添加 / 查询返回的控件
PAYLOAD_TOO_LARGE单次批量数据超过 512KB拆小批次;见 Q2
LAYER_READONLY操作了只读的默认层只对自建图层操作;见 Q3
LAYER_NOT_FOUND图层 id 不存在确认图层已创建;见 Q3
NO_SUCH_ELEMENT地图元素在服务端不存在确认元素来源于 insert / query 返回的实例
NOT_SUPPORTED_MAP_DRAWER_TYPE使用了不支持的 drawerType改用受支持的类型(MARKER / POLYLINE / POLYGON / CIRCLE / PIN)
ELEMENT_POINTS_MUST_NOT_BE_NONE元素坐标点为空插入前确保 points 已赋值
最近修改: