航线组件

一、航线编辑组件

WaylineEditor 是独立的 UMD bundle，同一个实例可完成创建航线、编辑航线、航线拼接三件事。

1. 引入 SDK 资源

加载完成后，SDK 类挂载在 window.WaylineEditor。

由于 SDK 用 defer 加载，请在 window.onload 之后再初始化：

2. DOM 骨架与必备样式

WaylineEditor 内部组件渲染到固定选择器，DOM 骨架与样式必须完整提供，所有 ID 与类名不可改。

DOM 结构

DOM 约束

#project-middle-container 与 .right-micro-app 必须相邻兄弟，不能在两者之间插入任何节点

.right-micro-app → .maps-micro-app → .map-app-placeholder 三层不能扁平化

editor.mount() 的目标是 #uranus-wayline-app（内层）

#wayline-header 必须在 render() 之前就存在于页面，否则顶栏不会显示

必备 CSS

3. 初始化

构造函数

IWaylineEditorOptions 参数

字段	类型	必需	说明
`api.baseUrl`	string	✓	后端服务地址，例如 `https://[服务器地址]:30812/gateway`（带 `/gateway`）
`api.auth`	IAuth	✓	HTTP 鉴权配置
`ws.url`	string	✗	WebSocket 推送地址，鉴权复用 `api.auth`
`map.topo`	object	✗	拓扑设备连线配置，不传则不加载拓扑插件
`runtimeDepsBasePath`	string	✗	运行时依赖资源根目录，默认取 SDK 脚本所在目录
`oss.objectKeyPrefix`	string	✗	OSS 对象 key 前缀，建议显式指定，不传则每次随机 UUID
`supportedDrones`	`Array<{ drone: number, payloadList: number[] }>`	✗	限制可选机型/负载，不传或传空数组 = 展示全部
`enabledWaylineTypes`	number[]	✗	限制可选航线类型，不传或传空数组 = 展示全部
`theme`	ITheme	✗	自定义主题色

IAuth 字段

字段	类型	说明
`authKeys`	string[]	鉴权 header 名称列表
`headers`	object \| `() => Record<string, string>`	推荐函数形式，每次请求实时取值

完整初始化示例

4. 创建航线

调用后弹出航线创建对话框，确认保存后 Promise resolve 返回新航线的 waylineId。

必须先 mount()，未挂载时 create() 会直接 reject。
取消操作也会 reject，请务必挂 .catch()，否则产生未捕获的 Promise 异常。

限制可选的航线类型（初始化时传 enabledWaylineTypes）

枚举值	名称	说明
0	Waypoint	航点航线
1	Area	面状航线
2	Facade	斜面航线
3	Solid	几何体航线
4	MappingStripe	带状航线
7	MappingObject	贴近摄影航线
8	TargetDetection	AI 巡逻航线

限制可选的机型/负载（初始化时传 supportedDrones）

5. 编辑航线

必须先 loadMap()，未加载地图时 render() 不会抛异常，只会派发 error 事件（code: 6002）后静默返回，请务必监听 error 事件。
必须先 mount()，未挂载时 render() 直接静默返回。

6. 航线拼接

把多条航线首尾合并成一条新航线，返回新航线的 UUID。

虽然是静态方法，但依赖已初始化的实例。请在 new WaylineEditor() → mount() → loadMap() 之后再调用。OSS 前缀取自构造参数 oss.objectKeyPrefix。

拼接校验规则

规则	失败提示
至少 2 条航线	`航线拼接至少需要 2 条航线`
仅支持航点航线	`仅支持航点航线拼接`
各航线的设备/负载类型必须一致	`航线设备/负载类型不一致`
使用相对起飞点高度模式时需有起飞点信息	`相对起飞点高度模式的航线缺少起飞点信息`
各航线的第三方 AI 算法必须一致	`第三方AI算法类型不一致`

合并后航线的全局参数（高度模式、飞行速度、偏航模式等）以第一条航线为准，其余航线的航点按第一条高度模式换算。

7. 设备拓扑连线

在地图上渲染设备（机场/飞机/中继/遥控器）及其连线关系。构造时传 map.topo 才启用，不传则完全不加载拓扑插件。

map.topo 字段

字段	类型	默认值	说明
`snList`	string[]	`[]`	初始显示的设备 SN 列表
`pollMs`	number	`0`	轮询间隔（ms），`0` 不轮询
`showFullTopo`	boolean	`false`	`true` 点击展开整条拓扑，`false` 仅显示单设备
`highlightMode`	string	`'show-related'`	点击设备后连线高亮方式
`deselectOnClickEmpty`	boolean	`true`	点击地图空白处是否取消选中

运行时接口

8. 事件监听与错误码

事件说明

事件名	参数	说明
`wayline-save`	`waylineId`	航线保存成功
`wayline-back`	`waylineId`	点击返回按钮
`collision-back`	`waylineId`	航线存在碰撞时的返回，此时不再派发 `wayline-back`
`wayline-cancel`	`waylineId`	取消编辑
`jump-to-wayline-list`	无	请求返回航线列表，可据此关闭编辑器
`wayline-device-selected`	`{ deviceSn: string }`	拓扑设备被点选
`set-router-destroy-confirm-tips`	`boolean`	编辑器脏状态变更，可用于拦截页面离开
`click-to-user-manual`	`{ action: string }`	点击「使用说明」按钮
`error`	`{ code: number, message: string, data?: any }`	SDK 运行时错误

⚠️ 碰撞航线只发 collision-back，若只监听了 wayline-back，存在碰撞时会漏收返回事件。请两个事件都监听。

错误码

错误码	名称	说明
4001	`WS_AUTH_ERROR`	WebSocket 鉴权失败
4002	`WS_DISCONNECTED`	WebSocket 连接断开
5000	`API_ERROR`	API 请求失败（网络错误或服务端 5xx）
5001	`API_AUTH_ERROR`	API 鉴权失败（401/403）
6000	`PARSE_ERROR`	航线数据解析失败（KMZ 格式异常）
6001	`WASM_LOAD_ERROR`	WASM 模块加载失败
6002	`MAP_INIT_ERROR`	地图初始化失败（Cesium 加载异常）
7000	`UPLOAD_ERROR`	OSS 上传失败

9. 主题热切换

只传需要变更的字段，未传字段保持当前值。可在 mount() 之后随时调用。

完整主题字段见「集成参考」文档。

10. 销毁编辑器

释放所有资源（同时清除拓扑并停止轮询），销毁后需重新 new WaylineEditor() 才能使用。

二、航线预览组件

WaylineView SDK 用于只读预览一组航线（只渲染，不编辑），支持多航线同时渲染、拓扑设备连线叠加、地图回中。完全自包含，不依赖 paas.js。

1. 引入 SDK 资源

加载完成后，SDK 类挂载在 window.WaylineView。

DOM 骨架（与 FlyDataReplay 同结构）

2. 初始化与使用

WaylineViewOptions 参数

字段	类型	必需	说明
`api.baseUrl`	string	✓	后端服务地址（带 `/gateway`）
`api.auth`	AuthConfig	✓	HTTP 鉴权配置
`map.notifyWsUrl`	string	✗	推送中心 WebSocket 地址
`map.topo`	object	✗	拓扑设备连线配置（不传则不加载拓扑插件）
`runtimeDepsBasePath`	string	✗	运行时依赖库资源目录
`autoRecenter`	boolean	✗	渲染后是否自动回中，默认 `true`
`onlyShowMapElements`	boolean	✗	多航线时是否只渲染地图元素，默认 `true`

3. 核心方法与事件

核心方法

方法	说明	返回值
`view.loadMap(container?)`	加载地图	Promise
`view.mount(container)`	挂载预览组件到 DOM	void
`view.render({ waylineIds, autoRecenter? })`	渲染一组航线	Promise
`view.recenter(waylineId?)`	地图回中（不传则全部）	Promise
`view.clear()`	清空已渲染航线	void
`view.showDeviceTopo(sns)`	显示/清除拓扑设备连线	void
`view.destroy()`	销毁实例，释放所有资源	void
`WaylineView.getTopoList()`	静态方法，拉取全量设备拓扑列表	Promise
`view.selectedDeviceSn`	getter，当前选中的设备 SN	string \| null
`view.state`	getter，`{ mounted, renderedWaylineIds }`	object

事件说明

事件名	参数	说明
`ready`	`{ waylineIds: string[] }`	全部航线渲染完成
`wayline-rendered`	`{ waylineId, startWaypoints, total }`	单条航线渲染完成
`recentered`	无	地图回中完成
`device-selected`	`{ deviceSn: string }`	拓扑设备 marker 被点击
`error`	`{ code, message, data }`	SDK 内部错误

错误码

错误码	说明
`5000`	API 请求失败
`5001`	API 鉴权失败
`6000`	航线 KMZ 下载失败
`6001`	航线 KMZ 解析失败
`6002`	运行时依赖（WASM）加载失败
`6003`	地图初始化失败

目录#

一、航线编辑组件#

1. 引入 SDK 资源#

2. DOM 骨架与必备样式#

3. 初始化#

4. 创建航线#

5. 编辑航线#

6. 航线拼接#

7. 设备拓扑连线#

8. 事件监听与错误码#

9. 主题热切换#

10. 销毁编辑器#

二、航线预览组件#

1. 引入 SDK 资源#

2. 初始化与使用#

3. 核心方法与事件#

4. 销毁#

目录

一、航线编辑组件

1. 引入 SDK 资源

2. DOM 骨架与必备样式

3. 初始化

4. 创建航线

5. 编辑航线

6. 航线拼接

7. 设备拓扑连线

8. 事件监听与错误码

9. 主题热切换

10. 销毁编辑器

二、航线预览组件

1. 引入 SDK 资源

2. 初始化与使用

3. 核心方法与事件

4. 销毁