dji-wayline-map

解析大疆（DJI）航线 KMZ 文件，并在高德地图（AMap）上绘制航线：KML 解析 + WGS84↔GCJ02 坐标转换 + 航点倒三角标记 + SVG 航段连线 + 自动适配视野。

框架无关 —— 解析与坐标转换是纯函数；地图绘制接受一个高德地图实例即可工作，不绑定 React/Vue。高德 JSAPI 由调用方自行加载，本包不打包、不加载。

安装

npm install dji-wayline-map
# 或
pnpm add dji-wayline-map

依赖 jszip 作为常规依赖随包安装。高德地图 JSAPI 需由调用方加载（见下文）。

快速开始

import {
  parseWaylineToGcj02,
  createWaylineDrawer,
} from "dji-wayline-map";

// 1) 加载高德 JSAPI（由调用方负责，得到 window.AMap）
//    参考 https://lbs.amap.com/api/javascript-api/guide/abc/prepare
const AMap = window.AMap;
const map = new AMap.Map(container, { zoom: 15, center: [120.05, 30.28] });

// 2) 创建绘制控制器（持有整条航线的标记/连线/事件状态）
const drawer = createWaylineDrawer(map, AMap, {
  markerColor: "#00E5A8",
  lineColor: "#00E5A8",
});

// 3) 下载航线 KMZ -> 解析为 GCJ02 路径 -> 绘制
const res = await fetch(kmzUrl);
const buf = await res.arrayBuffer();
const path = await parseWaylineToGcj02(buf, { maxPoints: 3000 });
drawer.draw(path);

// 切换航线时再次 draw() 即可，会自动清理上一条
// drawer.clear();   // 仅清除
// drawer.destroy(); // 销毁控制器（解绑事件、释放 ResizeObserver）

API

解析

| 函数 | 说明 | | --- | --- | | parseKmzArrayBuffer(buf): Promise<LngLat[]> | 解析 KMZ（zip）ArrayBuffer，返回原始 WGS84 路径。内部用 JSZip 解压定位 .kml。 | | parseKmlToPath(kmlText): LngLat[] | 解析 KML 文本。优先级：① Placemark <Point> 航点（≥2）→ ② 最长 <coordinates>（LineString）→ ③ 兜底 <gx:coord> 轨迹点。 | | parseWaylinePath(buf): Promise<LngLat[]> | 等价于 parseKmzArrayBuffer，语义化别名。 | | parseWaylineToGcj02(buf, opts?): Promise<LngLat[]> | 一步到位：解析 → 抽稀（opts.maxPoints 默认 3000）→ WGS84→GCJ02 → 过滤非法点，结果可直接喂给高德地图。 |

LngLat = [longitude, latitude]。

坐标转换

| 函数 | 说明 | | --- | --- | | wgs84ToGcj02(lng, lat): { longitude, latitude } | WGS84 → GCJ02（火星坐标系）。境外坐标原样返回。 | | gcj02ToWgs84(lng, lat): { longitude, latitude } | GCJ02 → WGS84，迭代逼近反算（默认 30 次，约 1cm 量级）。 |

路径工具

| 函数 | 说明 | | --- | --- | | samplePath(path, maxPoints): LngLat[] | 等距抽稀，保留首尾点。 | | isValidLngLat(point): boolean | 经纬度合法性校验。 | | dedupeConsecutive(points): LngLat[] | 去除连续重复点。 |

高德地图绘制

createWaylineDrawer(map, AMap, options?): WaylineDrawer

创建一个有状态的航线绘制控制器。把原项目中散落在 React ref 里的绘制状态（标记数组、SVG 连线、拖拽/缩放事件、ResizeObserver）封装为框架无关对象。

参数

• map —— 高德地图实例（AMap.Map）
• AMap —— AMap 命名空间（通常即 window.AMap）
• options —— 可选样式与上限：

| 选项 | 默认值 | 说明 | | --- | --- | --- | | maxWorkingPoints | 2000 | 工作点上限，超过先抽稀以减轻计算量 | | maxMarkers | 120 | 地图上最多绘制的航点(倒三角)数量；连线段数 = min(点数, 上限) − 1 | | triangleSide | 28 | 倒三角边长(px) | | markerColor | '#00E5A8' | 航点倒三角填充色 | | markerTextColor | '#ffffff' | 航点编号文字色 | | lineColor | '#00E5A8' | SVG 航段连线颜色 | | lineWidth | 4 | SVG 航段连线宽度(px) | | zIndexMarker | 1000 | 航点 DOM 标记层级 | | zIndexLine | 100 | SVG 连线层级 | | fitViewPadding | [60,60,60,60] | 自动适配视野内边距 [top,right,bottom,left] 或单一值 | | fitViewMaxZoom | 18 | 自动适配视野最大缩放级别 | | pointZoom | 17 | 退化(单点)航线缩放级别 | | svgClassName | 'dji-wayline-svg-lines' | SVG 连线元素 className，便于样式覆盖 |

返回 WaylineDrawer

| 方法 | 说明 | | --- | --- | | draw(path) | 绘制/覆盖一条航线（坐标需为 GCJ02）。空数组等价于 clear()。 | | clear() | 清除标记与连线，保留控制器可再次 draw。 | | refresh() | 强制重绘 SVG 连线。内部已监听拖拽/缩放/resize 自动刷新，一般无需手动调用。 | | destroy() | 销毁：清除图形、解绑事件、释放 ResizeObserver。销毁后不可再用。 |

为什么用 SVG 画连线而不是高德 Polyline？ 避免在卫星/路网瓦片层下 GL Polyline 被遮挡而看不见。连线挂在 .amap-layers 下，与 .amap-markers 为兄弟节点，随 mapmove/zoomchange/rotatechange/resize 及 ResizeObserver 自动重绘。

其他导出

• waylineMarkerSvgContent(index, side?, fillColor?, textColor?) —— 生成航点倒三角 SVG 字符串。
• redrawWaylineSvgLines(map, AMap, displayPath, style) —— 低层级 SVG 重绘（一般无需直接使用）。

类型

export type LngLat = [number, number];
export interface WaylineDrawOptions { /* 见上表 */ }
export interface WaylineDrawer { draw; clear; refresh; destroy; }
export interface AMapLike { Marker; LngLat; Bounds? }
export interface AMapMapLike { add; remove; getContainer; resize?; lngLatToContainer?; on; off?; setFitView?; setBounds?; setCenter; setZoom; }

AMapLike / AMapMapLike 为结构化最小类型，任何满足形状的高德 JSAPI v2.0 实例均可通过类型检查。

与原 DJI 飞控项目链路的对应关系

本包提炼自一条「选中航线 → 地图显示」链路：

| 原项目逻辑 | 本包对应 | | --- | --- | | 下载 KMZ → Worker/主线程解析 KML | parseKmzArrayBuffer / parseKmlToPath | | 抽稀 3000 + WGS84→GCJ02 + 过滤 | parseWaylineToGcj02(buf, { maxPoints: 3000 }) | | 坐标系转换 | wgs84ToGcj02 / gcj02ToWgs84 | | drawWayline：标记点 + SVG 连线 + 自动适配 + 随拖拽刷新 | createWaylineDrawer(map, AMap).draw(path) |

原项目通过 window 自定义事件 wayline:draw 在页面与地图组件间通信，属应用层胶水代码，不在本包内。接入本包后，页面侧可直接调用 drawer.draw(path)，或保留事件桥接在监听处调用。

许可证

MIT