架构概览

分层架构

┌─────────────────────────────────────────────┐
│              应用层 (Application)            │
├──────────┬──────────┬───────────────────────┤
│ 简易版    │ 标准版    │ 专业版                 │
├──────────┴──────────┴───────────────────────┤
│              核心层 (@gmap/core)             │
│   MapModel | Layer | Source | Feature       │
│   EngineAdapter | EngineRegistry | Events   │
├─────────────────────────────────────────────┤
│              引擎层 (Shim)                   │
│   OpenLayers | MapLibre | Cesium            │
└─────────────────────────────────────────────┘

三套 API 设计

简易版 (@gmap/simple)

• 全局 G 命名空间
• 工厂函数，零 new
• 链式调用 .addTo(map)

标准版 (@gmap/standard)

• ES 模块导入
• 完整类型系统
• 15 种几何、12 种符号、8 种渲染器

专业版 (@gmap/advanced)

• 门面模式
• 子门面隔离关注点
• Ref 类型安全引用

引擎适配器

每个引擎实现 EngineAdapter 接口：

interface EngineAdapter {
  readonly id: string;
  readonly capabilities: EngineCapabilities;

  // 生命周期
  mount(container, options): Promise<void>;
  destroy(): void;

  // 视图
  getViewState(): ViewState;
  setViewState(state): void;
  flyTo(target): Promise<void>;

  // 数据
  createSource(spec): EngineSourceHandle;
  createLayer(spec): EngineLayerHandle;
  addFeatures(layer, features): EngineFeatureHandle[];

  // ... 更多方法
}

能力声明通过 capabilities 对象，不支持的方法自动降级为 no-op + warnOnce。

依赖图

@gmap/core ─────────────────── 零依赖
  │
  ├── @gmap/geo ────────────── 零依赖
  │
  ├── @gmap/style-mapbox ───── 零依赖
  │
  ├── @gmap/standard ───────── 依赖 core, geo
  │     │
  │     ├── @gmap/simple ───── 依赖 core, geo, standard, services
  │     │
  │     └── @gmap/advanced ─── 依赖 core, geo, standard, services
  │
  ├── @gmap/shim-openlayers ── 依赖 core（peer: ol）
  │
  ├── @gmap/shim-maplibre ──── 依赖 core, style-mapbox（peer: maplibre-gl）
  │
  ├── @gmap/shim-cesium ────── 依赖 core（peer: cesium）
  │
  └── @gmap/services ───────── 零依赖

包作用域

层级	包名	说明
核心层	@gmap/core	核心抽象，零外部依赖
核心层	@gmap/geo	量算/分析/投影，零依赖
核心层	@gmap/style-mapbox	Mapbox 样式引擎，零依赖
API 层	@gmap/standard	标准版 API
API 层	@gmap/simple	简易版 API
API 层	@gmap/advanced	专业版 API
引擎层	@gmap/shim-openlayers	OpenLayers 2D 适配器
引擎层	@gmap/shim-maplibre	MapLibre 2D 适配器
引擎层	@gmap/shim-cesium	Cesium 3D 适配器
插件层	@gmap/services	地图服务 API

二三维共存架构

OneMap 支持在一个地图实例中同时运行 2D 和 3D 引擎，通过 CoexistenceManager 实现：

• CameraSync — 通过 ViewState 中间态双向同步相机
• LayerSync — 自动将主引擎的图层/数据源/要素同步到辅助引擎
• OverlaySync — 将 2D DOM Overlay 投影到 3D 场景

所有三个引擎适配器（OpenLayers、Cesium、MapLibre）都实现了共存所需的接口： setInputEnabled()、view:change 事件、overlay 管理方法。

详见 引擎适配器概览。