teee-map-sdk

基于 maplibre-gl 封装的铁路 GIS 业务地图 SDK，面向太昌 GIS 业务流提供开箱即用的地图初始化、图层管理、要素状态控制、加密瓦片及离线包支持。

安装

npm install @taichina/map-sdk

快速开始

import { TeeeMap } from "@taichina/map-sdk";
import maplibregl from "maplibre-gl";

const teeeMap = new TeeeMap("map-container");

// CTC 施工推演图
teeeMap.createCTCMap("ST-001", "https://tiles.example.com/{z}/{x}/{y}", [
  "track",
  "signal",
  "switch",
]);

// 获取底层 maplibre 实例
const map = teeeMap.getMap();

引入方式

<!-- UMD -->
<script src="teee-sdk/teee-map-sdk.umd.js"></script>
<script>
  const map = new TeeeMapSDK.TeeeMap("map");
</script>

// ES Module
import { TeeeMap } from "@taichina/map-sdk";

API

构造函数

new TeeeMap(container: string | HTMLElement)

| 参数 | 说明 | |------|------| | container | DOM 元素 ID 或 HTMLElement |

地图创建方法

| 方法 | 说明 | |------|------| | createCTCMap(stcode, url, layers) | CTC 施工推演 / 站场平面图 | | createCTCEncryptedMap(stcode, url, layers) | 加密 CTC 图 | | createGraphMap(stcode, url, layers) | 普通站场平面图 | | createGraphEncryptedMap(stcode, url, layers) | 加密平面图 | | createGeomMap(stcode, url, layers) | 地理图（EPSG:4326 / 4490） | | createGeomEncryptedMap(stcode, url, layers) | 加密地理图 | | createRasterMap(url) | 影像 / 栅格底图 | | createEncryptedRasterMap(url) | 加密栅格图 | | createRSWPMap(url) | 人员定位图（栅格 + GeoJSON） | | createRAGEMap(url, subUrl, code) | 信息所综合业务图 | | createMbtilesMap(url, layers) | MBTiles 离线包 |

数据源管理

| 方法 | 说明 | |------|------| | addGeoJsonSource(id, data?) | 添加 GeoJSON 源 | | addVectorTileSource(id, url) | 添加矢量瓦片源 | | addRasterTileSource(id, url) | 添加栅格瓦片源 | | updateGeoJsonSource(id, data) | 更新 GeoJSON 数据 | | removeSource(id) | 移除数据源 |

图层管理

| 方法 | 说明 | |------|------| | addGeoJsonLayer(layerId, sourceId, type?, paint?, layout?) | 添加 GeoJSON 图层 | | updateLayerStyle(id, paint) | 动态修改图层 paint 样式 | | removeLayer(id) | 移除图层 |

要素状态管理（CTC 业务）

| 方法 | 说明 | |------|------| | stashAllFeature() | 缓存当前视口全部要素（首次 idle 自动执行） | | updateFeatureState(code, state) | 更新要素状态，如封锁、停电、选中等 | | initCTCFeatureState(feature) | 为单个要素初始化 CTC 业务状态 |

teeeMap.updateFeatureState("DG-102", {
  state: "1",     // 股道封锁
  select: true,   // 选中
});

交互事件

teeeMap.onFeatureClick("layer-id", (feature, lngLat) => {
  console.log(feature.properties.code);
});

绘制工具

地图 load 完成后，drawTool 会自动挂载：

const draw = teeeMap.drawTool;
draw.changeMode("polygon");        // 切换绘制模式
draw.onFinish((geojson) => {...}); // 绑定完成回调
draw.clear();                      // 清空画布

其他

| 方法 | 说明 | |------|------| | getMap() | 获取底层 maplibregl.Map 实例 | | getMapConfigs() | 获取当前 MapForgeConfig | | destroy() | 销毁地图实例 |

构建

npm run build          # 输出到 teee-sdk/

项目结构

├── src/
│   ├── index.ts          # SDK 入口，导出 TeeeMap
│   ├── teee-map/         # 核心 SDK（git 子模块，含详细设计文档）
│   └── map-const/        # 地图常量 & 枚举（git 子模块）
├── teee-sdk/             # 构建产物（.es.js / .umd.js / .css）
├── SDK/                  # 示例 HTML 页面 + SDK 副本
├── vite.config.ts        # Vite library mode 配置
└── tsconfig.json

核心 SDK 采用工厂模式：MapForge 生成配置 → SourceFactory 生成数据源 → LayerFactory 生成图层 → ToolFactory 注册交互工具。详见 src/teee-map/DESIGN.md。

依赖

| 包 | 版本 | 说明 | |------|------|------| | maplibre-gl | ^5.24.0 | peer，需自行安装 | | @turf/bbox | ^7.0.0 | GeoJSON 包围盒计算 | | @watergis/maplibre-gl-terradraw | ^1.13.1 | 绘制工具 | | pako | ^2.1.0 | MBTiles Gzip 解压 |