@loongship-gis/leaflet

LoongShip GIS 的 Leaflet 二维地图引擎包。

可选统一视觉主题通过 @loongship-gis/leaflet/unified.css 引入，并在地图容器或其祖先元素添加 loongship-theme-unified。不引入时继续使用冻结的旧二维默认视觉。

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

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

const baseLayer = await map.addRasterTileLayer({
  url: "https://tiles.example.com/{z}/{x}/{y}.png"
});
const canvasTiles = await map.addCanvasTileLayer({
  url: "https://tiles.example.com/{z}/{x}/{y}.png",
  enableDpi: true
});
const vectorTiles = await map.addVectorTileLayer({
  data: geojson,
  style: { color: "#0f766e", weight: 3, fillOpacity: 0.25 }
});
const point = await map.addPoint(
  { longitude: 121.5, latitude: 31.2 },
  { radiusPixels: 6 }
);

point.destroy();
vectorTiles.destroy();
canvasTiles.destroy();
baseLayer.destroy();
map.destroy();

新版右键菜单默认关闭；显式启用后使用共享菜单项模型：

const mapWithMenu = await createMap({
  engine: "leaflet",
  container: "map",
  center: { longitude: 121.5, latitude: 31.2 },
  zoom: 8,
  contextMenu: true
});

默认菜单提供从当前位置测距、绘点/线/面和清理结果。测距与线/面绘制都以右键位置作为首点；默认绘制动作会按需安装 Geoman，并为已经创建的地图补齐插件初始化。动作初始化失败时菜单保持打开并显示错误。自定义 contextMenu 可配置地图、图形和业务对象的同步或异步动作；地图销毁会移除菜单 DOM、地图事件和文档事件。旧 LoongShip.mapView() 不启用这项新版能力。

Leaflet 作为 peer dependency，由应用提供 leaflet@^1.9.4。所有内置插件必须通过本包的 getLeafletRuntime() 使用同一、可扩展的 Leaflet runtime；禁止自行导入第二份 Leaflet，或在业务项目中复制插件后手工替换全局 L。

普通 Leaflet 插件由业务应用作为 npm 依赖安装，并通过 map.getNativeMap() 接入。该方法是 Leaflet 引擎包专用扩展点，不属于双引擎统一 API，也不保证在 Cesium 中可用。

createGlobalVesselLayer() 的 startPolling(intervalMs) 同时覆盖低于 detailZoom 的瓦片 LOD 与详细视域 LOD；stopPolling() 和图层销毁会终止两档定时刷新及进行中的请求。 其 Core click 事件只报告命中的船舶，不隐式改变选择；调用方应显式调用 selectVessel()。这与 Cesium 适配器一致。

业务修改版 TrackPlayback 由独立子路径按需加载：

import { createAreaTrackPlayback } from "@loongship-gis/leaflet/track-playback";

const playback = await createAreaTrackPlayback(data, map.getNativeMap(), {
  tooltipFormatter: (point) => String(point.time)
});
playback.start();

playback.dispose();

TrackPlayback 坐标默认为 WGS84 经纬度，时间单位为秒。旧业务的 COEFF 数据必须显式传入 createTrackCoordinateScaleAdapter(COEFF)，不再隐式修改坐标。未提供 tooltipFormatter 时，旧版 info: [{ key, value }] 会继续生成默认置顶表格 Tooltip。地图卸载会自动停止动画并销毁回放资源。

普通 <script> 标签可使用自包含全局产物，无需另行加载 Leaflet：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@loongship-gis/[email protected]/dist/loongship-leaflet.css">
<script src="https://cdn.jsdelivr.net/npm/@loongship-gis/[email protected]/dist/loongship-leaflet.global.js"></script>
<script>
  const map = LoongShip.mapView("map");
</script>

执行后 window.L 与 window.LoongShip 使用同一套 Leaflet 构造器。全局 CSS 已包含 Leaflet 基础样式、默认图片和 SDK 兼容样式；模块化应用仍应使用包根入口或 ./legacy 子路径，避免加载全局产物。

旧二维调用通过独立子路径按需加载，不进入默认包体：

import "leaflet/dist/leaflet.css";
import "@loongship-gis/leaflet/legacy.css";
import LoongShip from "@loongship-gis/leaflet/legacy";

LoongShip.Default.MAP_CONFIG.STREET.url = "https://tiles.example.com/{z}/{x}/{y}.png";
const legacyMap = LoongShip.mapView("map", { mapType: "STREET" });
legacyMap.changeMap("SAT");
legacyMap.remove();

旧 Canvas 瓦片同样只在兼容子入口中按需提供：

const canvasLayer = LoongShip.canvasTileLayer("https://tiles.example.com/{z}/{x}/{y}.png", {
  enableDpi: true,
  timeout: 0
}).addTo(legacyMap);

canvasLayer.remove();

旧数据工具默认读取兼容命名空间的 COEFF：

LoongShip.COEFF = 1_000_000;
const ship = LoongShip.Tool.shipDataFormat({
  mmsi: "413000001",
  lat: 31_200_000,
  lng: 121_500_000
});
const gcj02 = new LoongShip.CoordConver().gps84_To_gcj02(
  ship.longitude,
  ship.latitude
);

经纬度输入输出均为度；gps84_To_gcj02 为兼容旧版保留 [lat, lng] 顺序。距离工具 haversineDistance 返回米。

legacy 子入口同步提供 MapView、MapChange、旧底图配置、Leaflet 原型扩展、GPS/坐标转换和纯工具 API，并将同一 Leaflet runtime 同步到全局 L 与 LoongShip。旧底图默认地址按兼容要求保留为 HTTP；HTTPS 页面应在创建地图前覆盖地址，避免浏览器 mixed-content 拦截。

旧平铺控件字段继续原样兼容，也可增量使用与三维一致的嵌套配置；嵌套配置仍创建原迁移控件，不替换其 DOM：

const map = LoongShip.mapView("map", {
  controls: {
    zoomChange: true,
    fullscreen: true,
    mapChange: true,
    distance: true,
    position: "bottomright",
    layout: "vertical"
  }
});

createLeafletMap() 作为阶段 0 的兼容入口继续保留。新版 LeafletMapEngine 通过 addCanvasTileLayer() 提供 URL 驱动的公共 Canvas 瓦片契约，通过 addVectorTileLayer() 提供 WGS84 GeoJSON、静态样式、显隐与销毁契约。属性驱动样式、命中、Popup 和动态 setData() 仍属于 @loongship-gis/leaflet/geojson-vt 专属入口；legacy canvasTileLayer() 的同步对象身份和 timeout 参数保持不变。

Core createMap() 收到 controls 时会按需使用迁移后的 MapView 作为二维底座，供 MapSessionController 在切换引擎后重建同一控件配置；未传 controls 时仍走轻量 Leaflet 创建路径。模块化项目使用该能力时应引入 @loongship-gis/leaflet/legacy.css。

船舶和区域查询不再使用旧 DataApi。应用通过公开配置入口注入自己的数据实现，并在不再使用时清除：

LoongShip.configureMaritimeDataProvider({
  getShipInfo: async (mmsi, { signal } = {}) => loadShip(mmsi, signal),
  getShipVesselTrack: async (mmsi, start, end, { signal } = {}) => loadTrack(mmsi, start, end, signal),
  getShipStatus: async (mmsi, { signal } = {}) => loadStatus(mmsi, signal),
  getAreaWkt: async (name, { signal } = {}) => loadAreaWkt(name, signal)
});

LoongShip.configureMaritimeDataProvider();

海量船舶通过 CanvasOverlayLayer 与 Provider 驱动的 worldShipTileLayer() 提供；调用 destroy() 会取消请求、停止轮询并移除 Canvas、监听和对象池。

插件均从独立子路径按需加载，不进入根入口：

import { getLeafletRuntime } from "@loongship-gis/leaflet";
import { createGeoJsonVtLayerWithRuntime } from "@loongship-gis/leaflet/geojson-vt";
import { installMarkerCluster } from "@loongship-gis/leaflet/marker-cluster";
import { migrationLayer } from "@loongship-gis/leaflet/migration";
import { cloneLayer } from "@loongship-gis/leaflet/clone-layer";
import { installVendorPlugins } from "@loongship-gis/leaflet/vendor-plugins";

const vectorTiles = createGeoJsonVtLayerWithRuntime(getLeafletRuntime(), geojson, options);

await installVendorPlugins({
  antPath: true,
  geoman: true,
  polylineDecorator: true,
  trackPlayer: true
});

const vessels = await map.createVesselLayer({
  vessels: [{ mmsi: "412000001", name: "Demo", longitude: 121.5, latitude: 31.2 }]
});

vessels.on("click", ({ vessel }) => vessels.selectVessel(vessel.mmsi ?? vessel.id));

Core map.createTrackLayer() 与 Cesium 共享图片目标旋转、状态优先/速度其次的分段色和 selectedTrackId / selectTrack() 选择高亮契约。二维实现的选择描边和分段 Polyline 均由 返回句柄管理，隐藏、数据替换或 destroy() 时一并移除；legacy TrackPlayback 对象仍只在 专属子入口提供。

使用 Geoman 时另行引入 @loongship-gis/leaflet/geoman.css，MarkerCluster 使用对应两个 CSS 子路径。直接使用 map.pm 的调用方应在创建地图前安装 Geoman；新版默认右键绘制动作会为其已经创建的地图执行受控初始化。GeoJSON-VT、Migration 和 CanvasOverlay 调用 destroy()；MarkerCluster、克隆图层及第三方插件图层使用 Leaflet 的 remove() 生命周期。

受控 npm 插件版本与许可证：Geoman 2.20.0、AntPath 1.3.0、PolylineDecorator 1.6.0、TrackPlayer 2.0.2、MarkerCluster 1.5.3 均为 MIT；GeoJSON-VT 4.0.3 为 ISC。完整第三方声明见 THIRD_PARTY_NOTICES.md。

AI / Vibe Coding 支持

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

1. ai/AGENTS.md：包职责、入口选择、Leaflet runtime 与生命周期边界。
2. ai/SDK_MANIFEST.json：机器可读的入口、导出和稳定性分类。
3. ai/API_INDEX.md：根入口及各子路径的公共 API 导航。
4. ai/EXAMPLES.md：只使用公开入口的最小示例。
5. 对应的 dist/*.d.ts：各入口的精确 TypeScript 签名，遇到文档歧义时以此为准。

AI Agent 不应导入内部 chunk、依赖 Leaflet 私有字段或创建第二份 Leaflet runtime。

License

Copyright (c) 2026 LoongShip. 本包依据随包提供的 LoongShip GIS SDK Commercial License 授权，详见 LICENSE；第三方组件继续适用各自许可证。