import { MaritimeGisSDK } from "loongship-cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

const sdk = await MaritimeGisSDK.create({
  container: "map",
  baseLayer: {
    type: "shipdt-chart"
  },
  controls: {
    scale: true,
    navigation: true,
    baseLayer: true
  }
});

await sdk.setView({
  longitude: 121.8,
  latitude: 31.2,
  height: 90000
});

HTML 容器示例：

<div id="map" style="width: 100vw; height: 100vh;"></div>

Vue3 项目接入

下面示例为 Vue3 + JavaScript，包含组件挂载、SDK 初始化和销毁处理。

<template>
  <div ref="mapRef" class="map-view"></div>
</template>

<script setup>
import { onBeforeUnmount, onMounted, ref } from "vue";
import { MaritimeGisSDK } from "loongship-cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

const mapRef = ref(null);
let sdk;

onMounted(async () => {
  sdk = await MaritimeGisSDK.create({
    container: mapRef.value,
    baseLayer: {
      type: "shipdt-chart"
    },
    controls: {
      scale: true,
      navigation: true,
      baseLayer: true
    }
  });

  await sdk.setView({
    longitude: 122.2,
    latitude: 29.9,
    height: 120000
  });
});

onBeforeUnmount(() => {
  sdk?.destroy();
  sdk = undefined;
});
</script>

<style scoped>
.map-view {
  width: 100%;
  height: 100vh;
}
</style>

React 项目接入

下面示例为 React + JavaScript。

import { useEffect, useRef } from "react";
import { MaritimeGisSDK } from "loongship-cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

export default function MaritimeMap() {
  const mapRef = useRef(null);

  useEffect(() => {
    let sdk;
    let disposed = false;

    async function init() {
      sdk = await MaritimeGisSDK.create({
        container: mapRef.current,
        baseLayer: {
          type: "shipdt-chart"
        },
        controls: {
          scale: true,
          navigation: true,
          baseLayer: true
        }
      });

      if (disposed) {
        sdk.destroy();
        return;
      }

      await sdk.setView({
        longitude: 122.2,
        latitude: 29.9,
        height: 120000
      });
    }

    init();

    return () => {
      disposed = true;
      sdk?.destroy();
    };
  }, []);

  return <div ref={mapRef} style={{ width: "100%", height: "100vh" }} />;
}

核心场景

GlobalShipTileScene

GlobalShipTileScene 是全球船舶业务场景，适合接入真实船舶接口，按当前视野加载全球船舶数据。

特点：

业务接口驱动
BBox 请求
缓存
渐进加载
MMSI 去重
船舶搜索、选中、点击和悬停

示例：

const globalShips = sdk.createGlobalShipTileScene("global-ships", {
  url: "https://example.com/ship/getAreaShip",
  params: {
    shipStatus: "SAILING,STOP",
    nationalityType: "1,2,3"
  },
  renderer: "cesium",
  rendererOptions: {
    mode: "auto"
  }
});

await globalShips.refresh({ force: true });

const matches = globalShips.searchShips("413000000");
if (matches[0]) {
  globalShips.selectShip(String(matches[0].id ?? matches[0].mmsi));
}

MassiveShipScene

MassiveShipScene 是海量船舶渲染场景，适合验证或展示 10 万级船舶渲染能力。

特点：

10 万级船舶
GPU 渲染扩展
Worker 预处理
LOD 切换
AIS 批量更新

示例：

const massiveShips = sdk.createMassiveVesselLayer("massive-ships", {
  mode: "auto",
  worker: true,
  culling: {
    enabled: true
  }
});

await massiveShips.load([
  {
    id: "ship-1",
    mmsi: "413000000",
    name: "DEMO SHIP",
    longitude: 122.15,
    latitude: 29.92,
    heading: 90,
    speed: 12,
    vesselType: "cargo"
  }
]);

GlobalShipTileScene 与 MassiveShipScene 是独立场景。前者面向真实全球船舶业务接口，后者面向海量渲染能力验证。不要把两者混用，也不要为了修改一个场景而改动另一个场景。

AI / Vibe Coding 支持

SDK npm 包中包含 AI 友好文档：

ai/
├── AGENTS.md
├── API_INDEX.md
├── ARCHITECTURE.md
├── EXAMPLES.md
├── RULES.md
└── SDK_MANIFEST.json

AI Agent 推荐优先阅读：

ai/AGENTS.md
ai/API_INDEX.md
ai/ARCHITECTURE.md
ai/EXAMPLES.md

适用于：

Codex
Claude Code
Cursor
Gemini CLI
Windsurf

安装后可在以下目录直接访问：

node_modules/loongship-cesium/ai/