地图控件
一、功能介绍
地图控件能把插件的地理信息实时绘制到 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 / PIN | MapMarkerOptions | point、title、normalIConFileName、clickable、draggable |
POLYLINE | MapPolylineOptions | points、width、color、dashed |
POLYGON | MapPolygonOptions | points、fillColor、strokeColor、width |
CIRCLE | MapCircleOptions | center、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恢复),不影响地图上的显示。
效果预览:

三、API 参考
以下接口方法的完整定义(含入参数据模型、枚举)请查看 API 文档:IMapWidgetManager。
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 源码获取
五、常见问题(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 已赋值 |