@loongship-gis/compat

旧版 LoongShip 二维 SDK 的公开 API 兼容层。它提供同步返回、可链式调用的句柄，并把实际地图创建委托给注册的二维或三维引擎。

兼容承诺覆盖公开 API 和链式调用，不覆盖 Leaflet 私有字段或 Leaflet 对象身份。

首批双引擎入口

MapView/mapView、tileLayer、tileLayer.wms、circleMarker、polyline、 polygon、shipMarker 和 fleetShipMarker 已通过 Core MapEngine 分发到 Leaflet 或 Cesium。业务代码仍使用旧二维名称，只在地图初始化时选择 engine。

WorldShipTileLayer / worldShipTileLayer 保留旧名称、Provider、参数更新、轮询、 显隐、选中和销毁方法。Leaflet 复用迁移后的 WorldShipTileLayer、Canvas 瓦片和 高层级真实船舶模式；Cesium 适配到 GlobalShipTileScene。Compat 不承诺 Leaflet GridLayer 身份、Canvas 私有字段或 Cesium Primitive 身份。

CoordConver、GPS、INIT_OPTIONS、initOption、lsUtils、Tool 和 COEFF 保留旧同步名称与行为，使用这些工具不会加载 Leaflet 地图引擎。

LegacyTrackHandle 和 LegacyTyphoonHandle 为统一轨迹、台风能力提供同步链式句柄， 只分发到引擎真实声明的能力。它们不伪造 Leaflet Layer、AntPath 或 Cesium Entity； 引擎未实现时会返回明确的 UnsupportedCapabilityError。

import { createLoongShipNamespace } from "@loongship-gis/compat";
import { createMap as createLeafletMap } from "@loongship-gis/leaflet";

const LoongShip = createLoongShipNamespace();
LoongShip.registerEngine("leaflet", (container, options) => createLeafletMap({
  engine: "leaflet",
  container,
  center: options.center === undefined
    ? { longitude: 121.5, latitude: 31.2 }
    : { longitude: options.center[1], latitude: options.center[0] },
  zoom: options.zoom ?? 9
}));

const map = new LoongShip.MapView("map", { engine: "leaflet" });
LoongShip.polyline([[31.2, 121.5], [30.8, 122.2]], { color: "#0284c7" })
  .addTo(map);

兼容句柄同步返回并保持链式调用。remove() 释放当前引擎对象后仍可再次 addTo()；destroy() 是不可恢复的终态。异步初始化可通过 whenReady() 观察。 地图销毁会释放引擎和事件订阅，各覆盖物仍应由业务在离页时显式 destroy()。

完整状态、参数差异和降级说明见发布包 ai/API_INDEX.md，逐项分类以仓库中的 docs/fusion/dual-engine-legacy-api-matrix.json 为准。

引擎切换

MapSessionController 使用 Core 的纯 JSON MapSessionState 执行引擎切换。它不在 单个实例中热切换，而是保存当前视图、销毁全部句柄和引擎、动态创建目标引擎， 再恢复底图、图层、点线面、普通船舶、全球船舶、选择、统一控件配置和 Provider key。全球船舶图层的 selectedIdentifier 会在点击时更新，并在二维/三维重建时显式恢复；底层 Core click 本身仍不隐式选择。地图、卫星图、海图和无底图状态会双向恢复；引擎专属 custom 底图跨引擎时明确降级为地图。快速连续 请求会合并，目标引擎创建失败时会回建原引擎。

await controller.start() 或 await controller.switchEngine() 完成后，可通过只读 controller.getEngine() 取得当前 ready 的 Core MapEngine，用于重挂不进入序列化状态的 临时 Popup、Tooltip 或应用 UI；切换进行中、失败释放后及 destroy() 后返回 undefined。 这些临时 UI 仍由 Consumer 在每次目标引擎 ready 后重建，不写入 MapSessionState。

Leaflet 与 Cesium 的扩展字段分别存放在 extensions 和各自 views 中。二维不会 应用 Cesium 的 bearing、pitch、roll 或模型参数，但这些字段会保留供切回三维时 恢复。Provider 函数不进入 JSON，运行时通过稳定的 providerKey 注册。

AI / Vibe Coding 支持

npm 包内的统一阅读入口如下：

1. ai/AGENTS.md：兼容层职责、坐标、异步和生命周期边界。
2. ai/SDK_MANIFEST.json：机器可读的能力、兼容和引擎切换规则。
3. ai/API_INDEX.md：支持、适配、降级和不支持项导航。
4. ai/EXAMPLES.md：只使用公开入口的最小示例。
5. dist/index.d.ts：精确 TypeScript 签名，遇到文档歧义时以此为准。

AI Agent 不应假设 Leaflet 私有字段、原生对象身份或未声明的静默降级。

License

Copyright (c) 2026 LoongShip. 本包依据随包提供的 LoongShip GIS SDK Commercial License 授权，详见 LICENSE。