模块示例
一、Sample 简介
MSDK 5.20提供的SDK接口是按独立模块划分的,你可以通过他们接入Pilot平台:
- 在 Pilot 提供的悬浮窗上添加UI控件
- 在LiveView上标注信息
- 在 AR 视野中投射目标点
- 弹出对话框收集用户输入
- ......
Pilot 开放插件 Sample 以模块为单位开发演示用例,你可以逐个点开,在真机上看到实际效果。Sample 完整开源,每个用例都标出了对应的接口类与实现代码位置,你可以直接复制改造。 本文面向刚接触 Pilot 开放能力的开发者,按模块介绍每个用例演示了什么、你会看到什么效果,不涉及接口调用细节。
如需下载或查看工程源码,请跳转到文末的获取 Sample 工程源码。


二、使用前提
在体验模块用例之前,你需要先满足以下条件。
- 插件已联网注册
- 插件与 Pilot 服务端建立连接
- 飞行器已连接
- 权限获取(部分模块依赖文件访问等权限)
主界面的模块卡片只有在已连接且已注册时才可点击。如果状态未就绪,点击卡片会提示你先完成连接。



三、通用体验路径
除「航线任务」外,大部分模块都遵循同一条体验路径:
- 在主界面点击模块卡片,进入该模块的 Demo 页。
- 在 Demo 页左侧菜单选择一个用例,右侧显示该用例的说明与预览。
- 点击右侧的「查看效果」按钮,画面自动切换到 Pilot。
- 在 Pilot 界面上的悬浮窗中操作,实际效果直接呈现在 Pilot 的地图、图传或界面上。
- 点击悬浮窗底部的「返回插件 APP」回到插件,继续体验下一个用例。
悬浮窗的顶部导航条带有左右箭头,你可以在同一模块的不同用例之间快速切换,不必反复返回插件。


注意: 悬浮窗是全局唯一的。当你从一个模块切换到另一个模块时,悬浮窗内容会被新模块重绘覆盖,这是预期行为,不是异常。
四、如何找到对应代码
每个用例的右侧卡片上,「查看效果」按钮的正上方都会显示两行路径:
接口类:dji/open/pilot/client/interfaces/IARManager.java
参考代码:sampleitem/armanager/drawing/ARPointDrawer.kt
两行的含义是:
- 接口类:这个用例调用的开放接口所在位置,用于查阅接口定义与参数说明。「自定义 UI 组件」模块的控件不走接口类,这一行显示为封装类,指向该控件的封装实现。
- 参考代码:Sample 中真正实现这个用例的源码位置,相对于插件工程的源码根目录。
你在插件里看到某个效果、想知道它怎么做出来的,照着这两行路径去工程里找即可,不需要全局搜索。

五、模块速览
| 模块 | 能力 | 用例数 | 开发教程 |
|---|---|---|---|
| 自定义 UI 组件 | 在 Pilot 界面上叠加自己的控件,覆盖布局、文本、按钮、输入、开关、图片、列表等 11 类 | 25 | 自定义 UI 组件文档 |
| AR 投射 | 在 AR 视野中投射点、线、面、圆,并开启雷达扫描范围 | 5 | AR 投射文档 |
| 对话框 | 在 Pilot 弹出提示、确认、输入、单选、多选五类标准对话框 | 5 | 对话框文档 |
| 图传绘制 | 在图传画面上叠加检测框、多边形区域和实时文字 | 3 | 图传绘制文档 |
| 页面跳转 | 把 Pilot 跳转到主页、地图、航线、相册等指定页面 | 8 | 页面跳转文档 |
| 航线任务 | 把本地 KMZ 航线文件导入 Pilot | 1 | — |
六、自定义 UI 组件
这个模块演示如何在 Pilot 界面上叠加插件自己的控件。你可以像写 Android 布局一样组织这些远程控件,设置文字、颜色、尺寸、对齐方式,并在运行时更新它们的属性。模块共提供 11 类控件、25 个用例,按「基础组件 / 数据录入 / 数据展示」三组呈现在左侧菜单。
6.1 基础组件
| 控件 | 演示要点 | 用例数 |
|---|---|---|
| 布局 | 线性布局的权重分配与对齐方式,相对布局的四角与居中定位 | 5 |
| 文本 | 字号、加粗、斜体、颜色、下划线、删除线,以及截断与滚动 | 3 |
| 按钮 | 四种按钮样式、标签页式按钮组合、文字属性 | 3 |
6.2 数据录入
| 控件 | 演示要点 | 用例数 |
|---|---|---|
| 输入框 | 样式定制,以及数字、密码、自动分组、限制字数等输入控制 | 2 |
| 复选框 | 选中态、禁用态与配色 | 1 |
| 开关 | 开合状态、滑块与轨道配色、禁用态 | 1 |
| 下拉框 | 默认选中项、下拉面板配色 | 1 |
6.3 数据展示
| 控件 | 演示要点 | 用例数 |
|---|---|---|
| 图片 | 背景形状、六种缩放填充模式、着色 | 3 |
| 网页 | 在悬浮窗内加载真实网页 | 1 |
| 列表 | 多条数据、分割线、点击响应 | 1 |
| 进度条 | 水平与圆形两种形态,含进度、配色、文案与成功 / 失败状态 | 4 |
6.4 体验流程
- 在左侧菜单选择一类控件。
- 在右侧的用例列表中选择一个用例,卡片会展示该用例的效果预览。
- 点击「查看效果」,画面切换到 Pilot,悬浮窗中呈现该用例的实际渲染结果。
- 用悬浮窗顶部的左右箭头切换到其他控件,或点击「返回插件 APP」回到插件。


七、AR 投射
这个模块演示如何把点、线、面、圆投射到 Pilot 的 AR 视野中,用于在真实画面上标注目标位置、作业边界和警戒范围。所有元素的位置都基于飞行器实时位置计算,因此需要飞行器已连接。
| 用例 | 你会看到的效果 |
|---|---|
| 点 | 在飞行器前方 40m 与 80m 处各投射 3 个 AR 点,共 6 个;更新后演示按距离分别隐藏文字与图标,再恢复全部可见 |
| 线 | 投射一条包含 6 个点的折线;更新后变为绿色虚线 |
| 面 | 投射一个等边三角形与 3 个顶点;更新后拉伸为高 80m 的三棱柱 |
| 圆 | 投射一个半径 20m 的绿色圆;更新后拉伸为高 80m 的绿色圆柱体 |
| 雷达 | 在画面上显示或隐藏 AR 雷达的扫描范围 |
左侧菜单把这五个用例分为「自定义投射」(点、线、面、圆)与「系统投射」(雷达)两组。
7.1 体验流程
- 在左侧菜单选择一个 AR 元素,点击「查看效果」切换到 Pilot。
- 悬浮窗为点、线、面、圆提供查询、上传、更新、删除四个按钮,为雷达提供显示、隐藏两个按钮。
- 按「上传 → 更新 → 删除」的顺序依次点击,观察 AR 视野中元素的出现、变化与消失,每一步的结果都会回显在悬浮窗中。


注意: 元素必须先上传才能更新或删除。重复上传同一类元素会提示你先删除已有元素;若提示「获取飞机位置失败」,请确认飞行器已连接。
八、对话框
这个模块演示如何让 Pilot 弹出标准样式的对话框。对话框由 Pilot 统一绘制和呈现,插件只负责提供标题、内容和选项,用户的操作结果会通过回调传回插件。
| 用例 | 你会看到的效果 |
|---|---|
| 提示框 | 弹出只有一个确认按钮的提示框,用于单向告知 |
| 确认框 | 弹出带「是 / 否」两个按钮的确认框,返回用户的选择 |
| 输入框 | 弹出带文本输入的对话框,返回用户输入的内容 |
| 单选框 | 弹出选项列表,用户只能选择其中一项 |
| 多选框 | 弹出选项列表,用户可以同时选择多项 |
8.1 体验流程
- 在左侧菜单选择一种对话框类型,点击「查看效果」切换到 Pilot。
- 在悬浮窗中点击对应按钮,Pilot 立即弹出该类型的对话框。
- 完成操作后,悬浮窗的「回调结果」区域会显示你点了哪个按钮、输入了什么、选中了哪些项。


同一时刻只能存在一个对话框。前一个对话框未关闭时再次弹出,会提示「对话框已存在」。
九、图传绘制
这个模块演示如何在 Pilot 的图传画面上叠加图形和文字,常用于把目标检测、障碍识别等算法结果可视化地呈现给飞手。
| 用例 | 你会看到的效果 |
|---|---|
| 矩形框 | 在图传画面上叠加检测矩形框,用于框出识别到的目标 |
| 多边形 | 在图传画面上叠加实心多边形区域,并附带距离文案,用于标注障碍或作业区 |
| 文字 | 在图传画面的指定位置叠加自定义文字,用于展示实时状态 |
9.1 体验流程
- 在左侧菜单选择一种绘制元素,点击「查看效果」切换到 Pilot。
- 悬浮窗提供「更新」和「清除」两个按钮:点击「更新」在图传画面上绘制出对应图形,点击「清除」移除全部内容。
- 用悬浮窗顶部的左右箭头切换到其他绘制元素。


注意: 每种元素的绘制都是整表替换。「更新」提交的是当前要显示的全部内容,不在提交列表中的旧图形会一并消失;「清除」相当于提交一个空列表。
十、页面跳转
这个模块演示如何从插件控制 Pilot 的页面切换,让插件与 Pilot 的操作流程衔接起来。模块覆盖全部 8 个跳转目标。
| 用例 | 跳转结果 |
|---|---|
| Pilot 主页 | 切换到 Pilot 的主页 |
| Pilot 地图页 | 切换到 Pilot 的地图页 |
| Pilot 航线页 | 切换到 Pilot 的航线展示页 |
| Pilot 相册页 | 切换到 Pilot 的相册页 |
| Pilot 当前页 | 切换到 Pilot,停留在它当前所处的页面 |
| 「插件 APP」 | 从 Pilot 跳回插件的首页 |
| 自定义插件页 | 从 Pilot 跳回插件当前所处的页面 |
| 自定义远程页 | 跳转到插件自定义的远程页面 |
10.1 体验流程
- 在左侧菜单选择一个跳转目标,点击「查看效果」切换到 Pilot。
- 在悬浮窗中点击对应按钮,Pilot 立即跳转到目标页面。
- 通过悬浮窗的「返回插件 APP」按钮回到插件,继续尝试其他目标。


十一、航线任务
这个模块演示如何把本地的 KMZ 航线文件导入 Pilot,导入后你可以在 Pilot 的航线页中看到这条航线。
| 用例 | 你会看到的效果 |
|---|---|
| 导入 KMZ 航线 | 从本地存储选择一个 KMZ 文件推送给 Pilot,页面实时显示导入进度与最终结果 |
11.1 体验流程
- 在主界面进入「航线任务」模块。
- 点击「选择 KMZ 并导入航线」,在系统文件选择器中选中一个 KMZ 文件。
- 页面显示导入进度百分比,完成后提示导入成功或失败。

说明: 航线任务是唯一不使用悬浮窗的模块,全部操作都在插件页面内完成,不会切换到 Pilot。
十二、常见问题
| 现象 | 原因与处理 |
|---|---|
| 主界面的模块卡片点不动 | 连接或注册未完成。检查顶部徽章是否同时显示「已连接」和「已注册」 |
| 悬浮窗里的内容不是我刚选的用例 | 悬浮窗全局唯一,切换模块时会被新模块重绘。返回插件重新点击「查看效果」即可 |
| AR 模块提示「获取飞机位置失败」 | AR 元素的位置基于飞行器实时位置计算。确认飞行器已连接后重试 |
| AR 模块提示需要先删除再上传 | 同一类 AR 元素不能重复上传。先点「删除」清空,再重新上传 |
| 对话框提示「对话框已存在」 | 上一个对话框尚未关闭。在 Pilot 中关闭它后再弹出新的对话框 |
| 航线任务提示缺少权限 | 未授予全部文件访问权限。按提示前往系统设置授权后重试 |
十三、获取 Sample 工程源码
Pilot 开放插件 Sample 及相关场景工程位于 Mobile SDK V5 仓库的 dev-sdk-main 分支下,源码总目录为 SampleCode-V5。
| 工程源码 | 用途 |
|---|---|
| open-pilot-plugin-sample | 按模块演示自定义 UI 组件、AR 投射、地图控件、对话框、图传绘制、页面跳转和航线任务等能力,便于在 Pilot 中体验效果并参考接口调用实现。 |
| open-pilot-flighttask-sample | 演示从 Web 下发任务、遥控器接收工单、执行 KMZ 航线到回传资源的完整流程,提供 Pilot 开放插件与 Node.js 演示后端作为任务管理、航线执行和数据同步的开发参考。 |
| open-pilot-gasdetection-sample | 通过 PSDK 载荷数据通道接入气体测量,演示检测任务下发、实时监测与告警、船舶识别与跟随以及检测记录回传,并提供可复用的 Android 侧 PSDK 通信库。 |
| open-pilot-patrol-sample | 演示任务下发、航线巡检、目标识别与拍照、地图与 AR 标记以及资源回传,提供 Pilot 开放插件与 Node.js 演示后端作为智能巡检业务编排的开发参考。 |