集成参考

一、主题定制

各组件均支持自定义主题色，可在初始化时传入，也可在运行时热切换。

1.1 航线编辑组件

初始化时指定：

运行时热切换（mount() 后随时调用）：

ITheme 字段说明：

字段	说明
`primaryColor`	主色（按钮、链接、激活态）
`primaryHoverColor`	主色 hover 态
`primaryFocusColor`	主色 focus 态
`bgBasic`	基础背景色
`bgSub`	次级背景色（侧栏、卡片）
`bgModal`	弹窗背景色
`bgHighlight`	输入框/高亮区域背景色
`controlBg`	控件背景色
`controlHoverBg`	控件 hover 背景色
`borderColor`	边框色
`listActiveBg`	列表项激活态背景色
`listHoverBg`	列表项 hover 态背景色

1.2 飞行记录组件

SDK 内置 4 套预设主题，可按需使用或自定义：

主题名	主色	适用场景
`default`	`#1890ff`（蓝）	通用深色
`ocean`	`#00b4d8`（青）	海洋风
`violet`	`#9f67ff`（紫）	紫色风
`forest`	`#34d399`（绿）	绿色风

初始化时传入：

运行时热切换：

1.3 驾驶舱组件

驾驶舱主题基于约 90 个 snake_case 语义化 token，支持三种定制方式：

初始化时传入 theme 参数

运行时调用 FH2.setCockpitTheme() 等 API

驾驶舱内置可视化主题面板（调色 + 导出 JSON）

两种传入形态

形态	类型	说明
预设名	string	`'default'`（默认深色）、`'tech-blue'`（科技蓝）
扁平 token 对象	`Record<string, string>`	支持部分覆盖，只传需要修改的 key

初始化时指定：

运行时主题 API：

方法	说明
`FH2.setCockpitTheme(tokens)`	覆盖主题 token（部分覆盖，即时生效）
`FH2.setCockpitPreset(preset)`	切换内置预设：`'default'` / `'tech-blue'`
`FH2.resetCockpitTheme()`	重置为默认预设

Token 分组说明（按前缀）：

分组前缀	控制范围	示例
`bg_*`	各层级背景色	`bg_primary_default`
`border_*`	各层级边框色	`border_primary_default`
`component_*`	控件各状态填充色	`component_primary_enabled`
`function_*`	功能色：品牌色/危险/成功/警告	`function_brand_primary_enabled`
`icon_*`	图标色	`icon_primary_default`
`text_*`	文本色	`text_primary_default`

常用定制场景：

场景	覆盖的 token
换品牌主色	`function_brand_primary_enabled/hover/pressed/selected`
整体换背景	`bg_primary_default`、`bg_secondary_default`、`bg_tertiary_default`
调整文本对比度	`text_primary_default`、`text_secondary_default`

可视化调试（推荐）：

驾驶舱顶栏点击「🎨 主题切换」打开配置面板

逐个 token 调色，实时预览

点击「导出 JSON」得到扁平 token 键值对

将导出的 JSON 直接作为 theme / setCockpitTheme 的入参使用

1.4 设备管理组件

内置 'light'（默认）和 'dark' 两套主题，同时支持自定义 ThemeTokens 对象。

内置主题：

自定义主题（推荐流程）：

在已挂载页面调用 window.UranusDeviceManagerApp.showThemePanel() 打开配置面板

调整各 token 颜色，直到满意

点击「导出 JSON」，得到完整 ThemeTokens 对象

将导出的 JSON 作为 theme 传入 setupDeviceManager

注意：切换主题需重新调用 setupDeviceManager({ theme })，因为它是幂等的，后续调用只刷新主题与回调，不会重复初始化 HTTP/WebSocket。

二、完整示例

示例1：驾驶舱完整接入页面

示例2：设备管理完整接入页面

三、常见问题（FAQ）

Q1：地图不显示怎么办？

按以下顺序排查：

DOM 容器有正确的 ID 和尺寸（参考各组件的 DOM 骨架要求）

wssUrl 配置正确，且服务可访问

对于 WaylineEditor / FlyDataReplay：window.Cesium 是否已存在（Cesium 必须在 SDK 之前同步加载）

是否忘记调用 loadMap()（调用顺序：new SDK() → on('error') → await loadMap() → mount()）

Q2：报错 6002（MAP_INIT_ERROR）是什么原因？

99% 是忘记调用 loadMap() 或调用顺序错误。

Q3：鉴权报 401 / WebSocket 报 4001 怎么处理？

排查顺序：

authKeys 与 headers 对象的 key 是否完全一致（区分大小写）

Token 是否过期 → headers 改为函数形式，每次取最新值

如果用了 Webhook 鉴权，确认 Webhook 服务是否在 3 秒内响应

Q4：驾驶舱的 deviceList 模块为什么不显示？

deviceList（设备列表）模块在 KOC3 阶段默认隐藏，即使配置 modules.deviceList.visible: true 也不会显示。待后续版本放开后，调用代码无需修改即可生效。

Q5：同一页面能同时加载驾驶舱和飞行记录吗？

不能同时挂载，两者共享全局单例。飞行记录（KOC3 新版）已不依赖 paas.js，但仍依赖 Cesium 全局实例，同一页面同一时刻只能有一个活跃实例。

例外：DJILivePlayer（直播大屏）完全独立，可以与任何组件共存于同一页面，且支持同时多实例。

Q6：切换飞行任务（FlyDataReplay）怎么做？

必须先销毁旧实例再创建新实例：

Q7：HTTPS 页面出现 Mixed Content 报错？

如果页面使用 HTTPS，所有服务地址必须统一为 https:// 和 wss://：

serverUrl → https://

wssUrl → wss://

hostUrl → https://

Cesium 和 SDK 资源路径 → https://

Q8：设备小窗的 updateDeviceWindow 调用后部分小窗没生效？

updateDeviceWindow 有返回值，必须保存返回的新 windows 数组：

Q9：航线编辑器取消创建/编辑时为什么报错？

editor.create() 在取消操作时会以 Error('User cancelled') reject，这是正常行为，不是 bug。必须挂 .catch() 处理：

四、API 速查表

FH2 全局 API（`window.FH2`）

方法	说明	返回值
`initConfig(config)`	初始化 SDK 基础配置（serverUrl/wssUrl/hostUrl）	void
`initNotifyCenter(wssUrl, auth)`	初始化推送中心 WebSocket	void
`loadMap(serverUrl, auth, wssUrl?)`	加载地图（第3个参数为地图推送 ws）	void
`loadCockpit(domId, params)`	加载驾驶舱（支持 `cockpitConfig` / `theme`）	Object
`setCockpitConfig(config)`	运行时更新驾驶舱模块显隐配置	void
`getCockpitConfig()`	读取最近一次写入的驾驶舱配置	Object
`setCockpitTheme(tokens)`	运行时覆盖驾驶舱主题 token	void
`setCockpitPreset(preset)`	切换驾驶舱内置主题预设	void
`resetCockpitTheme()`	重置驾驶舱主题至默认	void
`destroyCockpit(self?)`	卸载驾驶舱（`self=true` 保留地图）	Promise
`loadDeviceWindow(domId, params?)`	加载设备小窗	Promise<实例数组>
`updateDeviceWindow(params)`	更新设备小窗设备列表（有返回值！）	DeviceWindowInstance[]
`destroyDeviceWindow(self?)`	卸载设备小窗	Promise

航线编辑组件（`WaylineEditor`）

方法	说明	返回值
`new WaylineEditor(options)`	创建实例	实例
`editor.loadMap(container?, position?)`	加载地图，可指定起图后定位坐标	Promise
`editor.mount(container)`	挂载编辑器到 DOM	void
`editor.create(options?)`	打开创建航线弹窗，取消操作时 reject	Promise<{ waylineId }>
`editor.render('edit', params)`	进入航线编辑	void
`editor.showDeviceTopo(sns)`	显示/清除拓扑设备连线（传空数组清除）	void
`editor.setTheme(theme)`	热切换主题	void
`editor.on(event, cb)`	事件监听	void
`editor.off(event, cb)`	取消事件监听	void
`editor.destroy()`	销毁实例	void
`editor.selectedDeviceSn`	getter，当前选中拓扑设备 SN	string \| null
`WaylineEditor.concatWayline(name, waylineIds)`	静态，航线拼接，返回新航线 UUID	Promise<string>
`WaylineEditor.getTopoList()`	静态，拉取全量设备拓扑列表	Promise

航线预览组件（`WaylineView`）

方法	说明	返回值
`new WaylineView(options)`	创建实例	实例
`view.loadMap(container?)`	加载地图	Promise
`view.mount(container)`	挂载预览组件	void
`view.render({ waylineIds })`	渲染一组航线	Promise
`view.recenter(waylineId?)`	地图回中	Promise
`view.clear()`	清空已渲染航线	void
`view.showDeviceTopo(sns)`	显示/清除拓扑设备连线	void
`view.destroy()`	销毁实例	void
`WaylineView.getTopoList()`	静态，拉取全量设备拓扑列表	Promise

飞行记录组件（`FlyDataReplay`）

方法	说明	返回值
`new FlyDataReplay(options)`	创建实例	实例
`player.loadMap(container?)`	加载地图（internal 模式起 Cesium）	Promise
`player.mount(container)`	挂载回放组件	void
`player.showDeviceTopo(sns)`	显示/清除拓扑设备连线	void
`player.setTheme(theme)`	热切换主题	void
`player.on(event, cb)`	事件监听	void
`player.destroy()`	销毁实例	void
`FlyDataReplay.getTopoList()`	静态，拉取全量设备拓扑列表	Promise

直播大屏组件（`DJILivePlayer`）

方法	说明	返回值
`initLivePlayer(options)`	全局初始化（一次性，多路共用）	void
`new DjiLivePlayer(options)`	创建单路播放器实例	实例
`player.refresh()`	重新查询设备 + 尝试开播	void
`player.retry()`	手动重试	void
`player.stop()`	停止播放，回到 idle	void
`player.switchQuality(q)`	切换画质	void
`player.switchCamera(camera)`	切换摄像头（地面站多摄像头场景）	void
`player.destroy()`	销毁播放器（幂等）	void
`player.getState()`	获取当前状态快照	Object

设备管理组件（`UranusDeviceManagerApp`）

方法	说明	返回值
`setupDeviceManager(conf)`	全局初始化（幂等，一次即可）	Promise<void>
`mountDeviceList({ container, props, on })`	挂载设备列表模块	MountHandle
`showThemePanel()`	打开可视化主题配置面板	void
`handle.unmount()`	卸载已挂载的模块	void

错误码汇总

数字错误码（WaylineEditor / FlyDataReplay / WaylineView 共用）

错误码	说明
`4001`	WebSocket 鉴权失败
`4002`	WebSocket 连接断开
`5000`	API 请求失败（网络错误或服务端 5xx）
`5001`	API 鉴权失败（401/403）
`6000`	航线数据解析失败（KMZ 格式异常）
`6001`	WASM 模块加载失败
`6002`	地图初始化失败（最常见：忘记 loadMap）
`6003`	运行时依赖加载失败（WaylineView 专用）
`7000`	OSS 上传失败（WaylineEditor 专用）

字符串错误码（DJILivePlayer 独立体系）

错误码	说明
`NOT_INITIALIZED`	未调用 `initLivePlayer()`
`DEVICE_OFFLINE`	设备离线
`TOKEN_EXPIRED`	Token 过期
`AUTH_FAILED`	认证失败
`DUPLICATE_INSTANCE`	同 SN/Camera/Video 重复实例
`CAMERA_NEED_AUTH`	摄像头需要验密
`START_LIVE_FAILED`	开播失败

各组件依赖关系速查

组件	依赖 paas.js	多实例	备注
驾驶舱（Cockpit）	✅ 依赖	❌ 单例	依赖 initConfig + initNotifyCenter + loadMap
设备小窗（Device Window）	✅ 依赖	❌ 单例	与驾驶舱不能同时挂
航线编辑（WaylineEditor）	❌ 独立	❌ 单例	需要 Cesium
航线预览（WaylineView）	❌ 独立	❌ 单例	需要 Cesium
飞行记录（FlyDataReplay）	❌ 独立	❌ 单例	需要 Cesium，KOC3 不再依赖 paas.js
直播大屏（DJILivePlayer）	❌ 独立	✅ 多实例	可与任何组件共存于同一页面
设备管理（UranusDeviceManagerApp）	❌ 独立	❌ 单例	KOC3 新入口 setupDeviceManager

目录#

一、主题定制#

1.1 航线编辑组件#

1.2 飞行记录组件#

1.3 驾驶舱组件#

两种传入形态#

1.4 设备管理组件#

二、完整示例#

示例1：驾驶舱完整接入页面#

示例2：设备管理完整接入页面#

三、常见问题（FAQ）#

Q1：地图不显示怎么办？#

Q2：报错 6002（MAP_INIT_ERROR）是什么原因？#

Q3：鉴权报 401 / WebSocket 报 4001 怎么处理？#

Q4：驾驶舱的 deviceList 模块为什么不显示？#

Q5：同一页面能同时加载驾驶舱和飞行记录吗？#

Q6：切换飞行任务（FlyDataReplay）怎么做？#

Q7：HTTPS 页面出现 Mixed Content 报错？#

Q8：设备小窗的 updateDeviceWindow 调用后部分小窗没生效？#

Q9：航线编辑器取消创建/编辑时为什么报错？#

四、API 速查表#

FH2 全局 API（window.FH2）#

航线编辑组件（WaylineEditor）#

航线预览组件（WaylineView）#

飞行记录组件（FlyDataReplay）#

直播大屏组件（DJILivePlayer）#

设备管理组件（UranusDeviceManagerApp）#

错误码汇总#

各组件依赖关系速查#

目录