@loongship-gis/sdk

LoongShip GIS 完整安装入口，同时安装 Core、Leaflet、Cesium 与兼容层。适用于需要二维、三维或二维/三维切换的浏览器应用。

安装

npm install @loongship-gis/sdk

leaflet 与 cesium 已由本包作为直接依赖安装，不需要再次手工安装。只需要单一引擎的高级用户仍可直接安装相应子包。

统一地图

新项目从根入口创建一个地图。默认使用二维 Leaflet，需要三维时通过同一个对象切换：

import {
  createMap
} from "@loongship-gis/sdk";

const map = await createMap({
  container: "map",
  center: { longitude: 121.5, latitude: 31.2 },
  zoom: 9
});

const point = await map.addPoint(
  { longitude: 121.5, latitude: 31.2 },
  { radiusPixels: 8, style: { color: "#dc2626" } }
);
const chart = await map.addRasterTileLayer({
  url: "https://tiles.example.com/{z}/{x}/{y}.png",
  opacity: 0.8
});

await map.switchEngine("cesium");
point.setVisible(false).setVisible(true);
chart.setOpacity(0.6);

point.destroy();
chart.destroy();
map.destroy();

切换会优先把目标引擎恢复到原 WGS84 可视范围；map.getBounds() 可读取该范围，Cesium 相机未与地球相交时返回 undefined。Raster、Canvas、WMS、WMTS、WGS84 GeoJSON Vector 以及点、线、面句柄会随引擎重建；图形点击/悬停订阅也会重绑。需要完整的引擎专属命名导出时，使用命名空间或公开子路径：

import { leaflet, cesium } from "@loongship-gis/sdk";
import { createMap as createLeafletMap } from "@loongship-gis/sdk/leaflet";
import { createMap as createCesiumMap } from "@loongship-gis/sdk/cesium";

同时提供 @loongship-gis/sdk/core 与 @loongship-gis/sdk/compat。

高级二维/三维会话

UnifiedMap 内部使用 MapSessionController，不是同时运行两种渲染器。需要 Provider registry、船舶、轨迹、台风、气象或自定义 portable feature 时，可以直接使用控制器：

import {
  MapSessionController,
  createMapSessionState,
  leaflet,
  cesium
} from "@loongship-gis/sdk";

const center = { longitude: 121.5, latitude: 31.2 };
const controller = new MapSessionController({
  container: "map",
  state: createMapSessionState({
    activeEngine: "leaflet",
    views: {
      leaflet: { center, zoom: 9 },
      cesium: { center, zoom: 9, bearing: 0, pitch: -45 }
    }
  }),
  engines: {
    leaflet: (container, options) => leaflet.createMap({
      engine: "leaflet",
      container,
      center: options.center === undefined
        ? center
        : { longitude: options.center[1], latitude: options.center[0] },
      zoom: options.zoom ?? 9,
      controls: options.controls
    }),
    cesium: (container, options) => cesium.createMap({
      engine: "cesium",
      container,
      center: options.center === undefined
        ? center
        : { longitude: options.center[1], latitude: options.center[0] },
      zoom: options.zoom ?? 9,
      controls: options.controls
    })
  }
});

await controller.start();
await controller.switchEngine("cesium");
await controller.switchEngine("leaflet");

// 页面卸载时释放活动引擎、图层、订阅和控制器持有的资源。
controller.destroy();

Provider、凭据、DOM、Popup、Tooltip 和引擎原生对象不进入会话状态。它们应由应用持有，并在每次切换完成后通过 controller.getEngine() 重新挂载。

样式

样式仍从拥有它的引擎包导入，避免完整包复制或合并引擎资源：

import "@loongship-gis/leaflet/unified.css";
import "@loongship-gis/cesium/unified.css";

AI / Vibe Coding 支持

从 ai/AGENTS.md 开始阅读。聚合清单用于选包、选引擎和定位文档；精确 TypeScript 签名始终以本包及四个依赖包的 dist/*.d.ts 为准。

License

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