引擎适配器概览

GMap SDK 通过 EngineAdapter 接口抽象底层地图引擎，支持运行时切换。

支持的引擎

引擎	包名	维度	特点
OpenLayers	@gmap/shim-openlayers	2D	功能全面，投影丰富
MapLibre	@gmap/shim-maplibre	2D	矢量瓦片，Mapbox 样式
Cesium	@gmap/shim-cesium	3D	地形、3D Tiles、场景效果

注册引擎

import { EngineRegistry } from '@gmap/core';
import OlAdapter from '@gmap/shim-openlayers';

// 静态注册
EngineRegistry.register('ol', () => new OlAdapter(), { default: '2d' });

// 懒加载注册（大体积引擎推荐）
EngineRegistry.registerLazy('cesium', () => import('@gmap/shim-cesium'), { default: '3d' });

运行时切换

const map = await createMap({ engine: 'ol', mode: '2d' });
// ... 添加图层、数据 ...

// 切换到 3D 引擎（保留视图和数据）
await map.switchEngine('cesium', { keepView: true, keepLayers: true });

能力声明

每个引擎通过 capabilities 声明支持范围：

const adapter = new OlAdapter();
console.log(adapter.capabilities);
// {
//   dimensions: ['2d'],
//   raster: true,
//   vectorTile: true,
//   geojson: true,
//   terrain: false,      // ← 不支持
//   tiles3d: false,      // ← 不支持
//   ...
// }

不支持的能力自动降级为 no-op + warnOnce。

EngineAdapter 接口

生命周期

• load(options) — 加载引擎资源
• mount(container, options) — 挂载到容器
• isMounted() — 是否已挂载
• resize() — 调整大小
• destroy(options) — 销毁
• getNative(options) — 获取原生对象

视图/相机

• getViewState() — 获取视图状态
• setViewState(state, options) — 设置视图状态
• flyTo(target, options) — 飞行到目标
• fitExtent(extent, options) — 适应范围
• project(coord) — 坐标转像素
• unproject(pixel) — 像素转坐标
• getResolution() — 获取分辨率
• getScale() — 获取比例尺
• setConstraints(options) — 设置约束

数据源

• createSource(spec) — 创建数据源
• updateSource(handle, patch) — 更新数据源
• removeSource(handle) — 移除数据源
• refreshSource(handle) — 刷新数据源

图层

• createLayer(spec, options) — 创建图层
• updateLayer(handle, patch) — 更新图层
• removeLayer(handle) — 移除图层
• reorderLayer(handle, options) — 重排序图层
• setLayerVisibility(handle, visible) — 设置可见性
• setLayerOpacity(handle, opacity) — 设置透明度

要素

• addFeatures(layer, features, options) — 添加要素
• updateFeatures(layer, features) — 更新要素
• removeFeatures(layer, ids) — 移除要素
• clearFeatures(layer) — 清空要素
• setFeatureState(layer, id, state) — 设置要素状态
• queryFeatures(layer, options) — 查询要素

样式

• applySymbol(layer, symbol, options) — 应用符号
• applyRenderer(layer, renderer) — 应用渲染器
• applyMapboxStyle(style, options) — 应用 Mapbox 样式
• setPaintProperty(layerId, name, value) — 设置绘制属性
• setLayoutProperty(layerId, name, value) — 设置布局属性
• addImage(id, image, options) — 添加图片
• removeImage(id) — 移除图片
• hasImage(id) — 是否有图片

交互/事件

• on(type, handler, options) — 监听事件
• off(type, handler) — 移除监听
• pick(at, options) — 拾取要素
• enableInteraction(kind, options) — 启用交互
• disableInteraction(handle) — 禁用交互
• setCursor(style) — 设置光标
• setInputEnabled(input, enabled) — 设置输入启用

覆盖物/控件

• createOverlay(spec) — 创建覆盖物
• updateOverlay(handle, patch) — 更新覆盖物
• removeOverlay(handle) — 移除覆盖物
• createControl(spec) — 创建控件
• removeControl(handle) — 移除控件

三维

• setTerrain(source, options) — 设置地形
• setLighting(options) — 设置光照
• addSceneEffect(spec) — 添加场景效果
• removeSceneEffect(handle) — 移除场景效果
• setClippingPlanes(planes) — 设置裁剪平面

诊断

• exportImage(options) — 导出图片
• getStats() — 获取统计

扩展

• extensions — 扩展对象
• invoke(method, ...args) — 调用扩展方法

共存接口

所有适配器实现了以下共存接口：

方法	用途
setInputEnabled(input, enabled)	暂停/恢复交互（dragPan、scrollZoom 等）
view:change 事件	相机变化时发射，供 CameraSync 监听
createOverlay/updateOverlay/removeOverlay	DOM overlay 管理