@loongship-gis/core

LoongShip GIS 的引擎无关契约包，提供坐标、视图、XYZ/Canvas/GeoJSON 矢量/WMS/WMTS 图层、点线面图形、船舶、轨迹、台风、气象、DataApi、主题、能力声明、事件和资源生命周期类型。

第一方引擎通过可选的 createGlobalVesselLayer() 实现高容量船舶渲染，并用 vessel.global 声明能力。业务只共享 WGS84 数据、Provider、参数和选择状态；Leaflet/Cesium 渲染对象始终独立创建和销毁。Core 句柄的 click 仅派发事件，业务通过 selectVessel() 显式选择。

该包不依赖 Cesium 或 Leaflet，也不创建地图实例。可选的 createWeatherPanel() 只创建引擎无关 DOM，并通过注入的 createWeatherLayer() 端口工作。

MapEngine#addCanvasTileLayer() 接受 URL 模板并返回可显隐、可销毁的图层句柄；Leaflet 使用 Canvas TileLayer，Cesium 适配为 ImageryLayer，enableDpi 与 drawDelayMs 仅是 Leaflet 提示。MapEngine#addVectorTileLayer() 接受经过校验的 WGS84 GeoJSON 与静态公共样式；Leaflet 使用客户端 GeoJSON-VT，Cesium 使用 GeoJSON DataSource。两者不承诺相同原生对象、切片算法、拾取事件或 Popup。

统一控件配置

CommonMapControlsConfig 使用旧二维命名作为双引擎公共控件键，并同时接受 topright 与 top-right 两种位置写法。Core 只负责配置语义和归一化；二维、三维 分别创建和销毁自己的控件对象，不跨引擎传递 DOM 或原生 Control。

地图会话状态

MapSessionState 是二维/三维地图切换使用的版本化纯 JSON 快照，保存 WGS84 视图、图层、点线面、船舶、轨迹回放、台风、气象、筛选条件、时间、工具状态和统一控件配置。全球船舶图层用可选 selectedIdentifier 保存选择。它不保存 Leaflet/Cesium 对象、DOM、函数、请求凭证或 Provider 实例；远程数据源通过应用维护的 providerKey 在目标引擎中重新解析。

按有效时次直接加载气象 JSON：

import { createTimestampWeatherGridProvider } from "@loongship-gis/core";

const provider = createTimestampWeatherGridProvider({
  resolveUrl: ({ type, timestamp }) =>
    `${import.meta.env.VITE_WEATHER_JSON_BASE_URL}/${type}/${timestamp}.json`
});

const grid = await provider.loadGrid({
  type: "wind",
  time: {
    referenceTime: "2026-07-20T00:00:00Z",
    validTime: "2026-07-27T12:00:00Z"
  }
}, { signal: new AbortController().signal });

Provider 不请求基础时次文件；URL、鉴权和服务路径由应用持有。销毁地图或切换气象类型、时次时，应取消对应 AbortController。

import {
  assertMapSessionState,
  createMapSessionState
} from "@loongship-gis/core";

const session = createMapSessionState({
  activeEngine: "leaflet",
  baseLayer: "map",
  views: {
    leaflet: { center: { longitude: 121.5, latitude: 31.2 }, zoom: 8 }
  },
  filters: { vesselType: "cargo" }
});

const persisted = JSON.stringify(session);
const restored: unknown = JSON.parse(persisted);
assertMapSessionState(restored);

切换引擎时应先保存状态并销毁当前地图资源，再创建目标引擎、解析 providerKey 并恢复覆盖物。单个地图实例不支持运行中替换渲染引擎。

共同气象面板只使用公共入口。面板默认打开，默认使用 SDK 内置的公开 OSS 瓦片地址，并以风场瓦片模式初始化；不传配置即可使用默认值：

import {
  DEFAULT_WEATHER_TILE_URL_TEMPLATE,
  createWeatherLegend,
  createWeatherLegendControl,
  createWeatherPanel
} from "@loongship-gis/core";

const panel = createWeatherPanel({
  container: document.getElementById("map-shell")!,
  engine: map,
  gridProvider,
  switches: {
    ossTiles: true,
    scalarParticles: true
  },
  advancedControls: true
});
await panel.apply();

const legend = createWeatherLegendControl({
  container: document.getElementById("map-shell")!,
  legend: createWeatherLegend({
    type: "wind",
    unit: "m/s",
    stops: [{ value: 0, color: "#315ea2" }, { value: 20, color: "#e15c33" }],
    missingLabel: "缺测"
  })
});

console.log(DEFAULT_WEATHER_TILE_URL_TEMPLATE);
panel.destroy();
legend.destroy();

调用方可以通过 initiallyOpen、initialState 和 tileProviderOptions 覆盖默认打开 状态、初始叠加类型、URL 模板、预报小时、类型路径和请求头，也可以直接传入完整的 tileProvider；显式 Provider 优先。类型按钮支持多选叠加，时间按类型分别保存。 switches.ossTiles 与 switches.scalarParticles 控制两个开关是否显示。JSON 色斑和 粒子所需的 gridProvider 仍由业务侧提供。advancedControls: true 显示共享的 scalar/particle/combined、透明度、粒子来源、密度、速度和拖尾控件；默认关闭以兼容 既有面板。createWeatherLegendControl() 将 createWeatherLegend() 数据挂载为可更新、 可显隐、可销毁的共享 SDK 图例。

DataApi

DataApiClient 只提供通用请求能力，不恢复旧 SDK 中写死的地址、token、Axios 单例或 LoongShip.DataApi 对象身份。业务通过 baseUrl、鉴权头和可注入 Provider 提供数据；页面销毁时调用 destroy() 会取消仍在进行的请求。

TrackDataProvider 返回 WGS84 TrackProviderPoint。其中 courseDegrees 表示对地航向， headingDegrees 表示船首向，均为从真北顺时针的度数；不要用 course 覆盖 heading。 使用 toTrackPoint() 可将 Provider 字段标准转换为渲染契约的 time、speed、course、 heading 和 navigationStatus。

Core MapEngine#createTrackLayer() 在 Leaflet 与 Cesium 中统一呈现图片目标旋转、速度/状态 分段色和 selectedTrackId 高亮。分段颜色优先级为状态色、速度色、轨迹默认色； selectTrack() 会立即更新选择描边/光环。target.text 在 Cesium 仍以 Tooltip 适配，固定时长 批量回放仍会在 degradations 中声明精确时间轴重采样。

AI / Vibe Coding 支持

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

1. ai/AGENTS.md：包职责、硬边界、数据与生命周期规则。
2. ai/SDK_MANIFEST.json：机器可读的能力、事件和兼容信息。
3. ai/API_INDEX.md：公共 API 导航与用途。
4. ai/EXAMPLES.md：只使用公共包入口的最小示例。
5. dist/index.d.ts：精确 TypeScript 签名，遇到文档歧义时以此为准。

AI Agent 不应导入包内部文件，也不应从 source map 推断未导出的 API。

License

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