驾驶舱和设备小窗

一、前置准备

已部署好上云 API 2 私有化安装包，部署方式请参考部署上云 API 2 应用运行与设备管控底座

Demo 已集成到上云 API 底座镜像（frontend）中，部署完成后可直接访问：

http://[服务器地址]/paasjs-demo/index.html

例如：http://[服务器地址]/paasjs-demo/index.html。各组件的初始化代码均已放在对应 HTML 文件中，可直接参考。

二、引入 paas.js

驾驶舱与设备小窗均依赖 paas.js，需要在页面中引入。

加载完成后，全局对象挂载在 window.FH2。

初始化配置

初始化 SDK 时需要填写以下 3 项配置：

1. 前端服务地址（frontHost）

输入前端部署资源的地址，该地址需能访问到 paas.js 文件。例如在浏览器中访问 http://[服务器地址]/paas.js 能成功加载，则填写 http://[服务器地址]。如果前端指定了端口，如 https://[服务器地址]:10443，则需完整填写含端口的地址。注意当前 HTML 页面的访问协议需与此地址协议一致，避免跨域。

2. 后端接口地址（serverHost）

提供的后端服务接口地址，一般为服务器地址加 30812 端口。例如：http://[服务器地址]:30812

3. WebSocket 地址（wssHost）

提供 WebSocket 服务的地址，仅替换为你的服务器域名/IP 即可，路径部分保持不变。例如：ws://[服务器地址]:30812/openapi/v0.9/notification/ws/v1/notifications

1.
如果页面使用 HTTPS，所有服务地址必须使用 https:// 和 wss://，以避免浏览器跨域（Mixed Content）问题。
2.
frontHost 必须能够访问到 paas.js 文件。
3.
SDK 初始化必须在页面组件加载前执行。

四、鉴权配置（非必须）

如果您的项目需要开启鉴权，可参考如下方式配置：

字段	类型	说明
`authKeys`	string[]	鉴权 header 名称列表，用于网关识别 `auth_keys` 头
`headers`	`() => Record<string, string>`	必须为函数形式，每次请求实时取值，适配 token 刷新

重要：headers 必须写成函数形式（闭包），否则 token 过期后无法自动更新。

五、驾驶舱组件

驾驶舱提供实时视频直播、飞行状态监控与飞行控制功能，支持模块显隐配置（cockpitConfig）与主题定制（theme）。

1. DOM 骨架与必备样式

驾驶舱内部多个微应用通过固定选择器投递渲染，DOM 骨架与 CSS 必须完整提供，ID 与类名均不可改。

DOM 结构

必备 CSS

2. 完整初始化流程

调用顺序严格：initConfig → initNotifyCenter → loadMap → loadCockpit

3. loadCockpit 参数说明

参数	类型	必需	说明
`domId`	string	✓	驾驶舱挂载容器 ID（不带 `#`）
`params.gateway_sn`	string	✓	机场/基站序列号
`params.drone_sn`	string	✓	无人机序列号
`params.map`	boolean	✗	是否显示地图，默认 `true`
`params.theme`	string \| object	✗	主题：内置预设名（`'default'`/`'tech-blue'`）或扁平 token 对象

返回对象方法：

方法	说明
`getVideoType()`	获取当前视频类型
`captureVideoFrame(params?)`	捕获视频帧

4. 卸载驾驶舱

`self` 值	行为
`true`	仅卸载驾驶舱应用，保留地图和 project-app
`false`（默认）	同时卸载驾驶舱、地图和 project-app

六、设备小窗组件

设备小窗以 SDK 方式拉起无人机/机场/基站设备的直播小窗浮层，调用方自行维护设备列表 UI，SDK 负责展示地图底图 + 设备位置标记 + 设备直播小窗浮层（视频流、飞行状态、任务栏、天气等）。

依赖说明：设备小窗依赖 paas.js + FH2.initConfig + FH2.initNotifyCenter + FH2.loadMap，与驾驶舱共享 window.FH2 / mapAppState 全局单例，驾驶舱与设备小窗不能在同一个 HTML 页面（同一浏览器 Tab）中同时使用，需分别放在独立页面中。

1. DOM 骨架与必备样式

2. 完整初始化流程

3. API 说明

FH2.loadDeviceWindow(domId, params?)

loadDeviceWindow 异步返回，await 后保证 micro-app 已挂载、设备拓扑已就绪，后续实例方法同步生效。

4. 小窗实例方法

方法	说明
`setTask({ status, label? })`	设置任务栏状态/标签。任务名称由 SDK 自动取机场名称填充，无需传入；不调用则显示"无任务"
`setHmsUrl(url?)`	HMS 健康告警入口跳转链接；传空字符串或不调用则隐藏该入口
`setCockpitUrl(url?)`	驾驶舱入口跳转链接；传空字符串或不调用则隐藏该入口
`setOnlineWeather(data)`	推送在线天气快照，立即生效；不调用时天气字段显示 `--`

WeatherOnlineData 字段说明

字段	类型	说明
`windSpeed`	number	风速（m/s）：≥10 黄色警告，超阈值红色阻飞
`precip`	number	降水量（mm/h）：0=无雨, (0,2)=小雨, [2,4)=中雨, ≥4=大雨
`temp`	number	温度（°C）：≤-20 黄色；≤-20 且湿度≥90% 联合黄色
`humidity`	number	相对湿度 0-100
`icon`	number	天气状态码（沿用心知天气 icon 编码，如 100=晴，300=阵雨，500=薄雾）
`wns`	number	风向角度 0-360（0=北, 90=东, 180=南, 270=西）
`ionosphereLevel`	string（可选）	电离层活跃度：`-1`=无数据 `0`=平静 `1`=中等 `2`=强 `3`=剧烈

5. 动态更新设备列表

⚠️ 注意：updateDeviceWindow 会返回新的 windows 数组，必须用返回值替换旧数组，否则对旧实例的操作将失效。

优先用 updateDeviceWindow，不要先 destroyDeviceWindow 再重新 loadDeviceWindow，避免不必要的卸载重挂载开销和潜在的 unmount 报错。

6. 销毁小窗

`self` 值	行为
`true`	仅销毁小窗浮层，保留地图和 project-app
`false`（默认）	同时销毁地图、project-app 和小窗浮层

七、已知限制

组件	限制说明
驾驶舱	`deviceList` 模块在 KOC3 阶段默认隐藏，待后续版本放开
驾驶舱	`topBar` 的 `layout`、`shortcutKey`、`settings` 标注"待实施"，当前配置无效但不报错
设备小窗	当前 WebSocket 通知使用 `initMock()` 空实现，DRC/摇杆/PSDK 等实时通知暂不可用
设备小窗	没有暴露 `on('error', ...)` 事件，运行时问题只能通过 Console 和 Network 面板排查
两者共用	共享 `window.FH2` 全局单例，驾驶舱与设备小窗不能在同一 HTML 页面（同一浏览器 Tab）中同时使用

目录#

一、前置准备#

二、引入 paas.js#

初始化配置#

四、鉴权配置（非必须）#

五、驾驶舱组件#

1. DOM 骨架与必备样式#

2. 完整初始化流程#

3. loadCockpit 参数说明#

4. 卸载驾驶舱#

六、设备小窗组件#

1. DOM 骨架与必备样式#

2. 完整初始化流程#

3. API 说明#

4. 小窗实例方法#

5. 动态更新设备列表#

6. 销毁小窗#

七、已知限制#

目录

一、前置准备

二、引入 paas.js

初始化配置

四、鉴权配置（非必须）

五、驾驶舱组件

1. DOM 骨架与必备样式

2. 完整初始化流程

3. loadCockpit 参数说明

4. 卸载驾驶舱

六、设备小窗组件

1. DOM 骨架与必备样式

2. 完整初始化流程

3. API 说明

4. 小窗实例方法

5. 动态更新设备列表

6. 销毁小窗

七、已知限制