主题
API 版本对比与选型指南
GMap SDK 提供三套 API 层级，面向不同团队规模和技术栈偏好。
三套 API 定位
| 特性 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 包名 | @gmap/simple | @gmap/standard | @gmap/advanced |
| 编程范式 | 工厂函数 + 链式调用 | ES 模块 + 类体系 | 门面模式 + 子门面 |
| 类型安全 | 弱 | 强 | 强 |
| Tree-shaking | 一般 | 好 | 好 |
| 代码量 | 少 | 中 | 多 |
| 灵活性 | 低 | 中 | 高 |
| 二三维共存 | enterCoexistence | G.coexist | facade.engine.enterCoexistence |
使用场景对比
简易版 G
适合以下场景：
- 业务逻辑简单的地图展示页面
- 后端开发人员快速集成地图功能
- 地图作为辅助功能而非核心功能的系统
- 需要最少代码量的场景
典型用法：
ts
import G from "@gmap/simple";
G.use("ol", () => new OlAdapter(), { default: "2d" });
const map = G.map({ target: "map", engine: "ol" });
G.tileLayer({ url: "..." }).addTo(map);
G.marker({ coord: [116, 39] }).addTo(map);标准版
适合以下场景：
- 以地图为核心功能的 Web 应用
- 需要精细控制图层、符号、渲染器的业务
- 需要完整 TypeScript 类型提示的团队
- 需要 Tree-shaking 优化包体积的项目
- 多人协作的中大型项目
典型用法：
ts
import {
createMap,
FeatureLayer,
GeoJsonSource,
SimpleRenderer,
MarkerSymbol,
} from "@gmap/standard";
const map = await createMap({ target: "map", engine: "ol" });
const src = new GeoJsonSource({ data: geojson });
const layer = new FeatureLayer({
source: src,
renderer: new SimpleRenderer({ symbol: new MarkerSymbol({ color: "red" }) }),
});
map.addLayer(layer);专业版
适合以下场景：
- 需要关注点分离的大型系统
- 多团队协作、模块化开发的项目
- 需要运行时切换引擎（2D/3D 切换）
- 需要统一管理相机、数据、交互、样式等子系统
- 有架构师角色参与的企业级项目
典型用法：
ts
import { createMapFacade } from "@gmap/advanced";
const app = await createMapFacade({ target: "map", engines: "ol" });
app.camera.flyTo({ center: [121, 31], zoom: 12 });
app.layers.addTile({ url: "..." });
app.data.loadGeoJson(geojson);
app.interactions.draw("polygon");
app.selection.pick([116, 39]);功能对比
地图与视图
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 创建地图 | G.map() | createMap() | createMapFacade() |
| 设置中心 | map.setCenter() | map.setCenter() | app.camera.setCenter() |
| 设置缩放 | map.setZoom() | map.setZoom() | app.camera.setZoom() |
| 飞行到目标 | map.flyTo() | map.flyTo() | app.camera.flyTo() |
| 适应范围 | map.fitBounds() | map.fitBounds() | app.camera.fit() |
| 设置方位角 | map.setBearing() | map.setBearing() | app.camera.setBearing() |
| 设置俯仰角 | map.setPitch() | map.setPitch() | app.camera.setPitch() |
| 视图状态 | map.getView() | map.getView() | app.camera.getState() |
| 坐标转换 | map.toCoord() | map.toCoord() | app.camera.toCoord() |
| 像素转换 | map.toPixel() | map.toPixel() | app.camera.toPixel() |
图层管理
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 栅格瓦片 | G.tileLayer() | new RasterTileLayer() | app.layers.addTile() |
| 矢量瓦片 | G.vectorTileLayer() | new VectorTileLayer() | app.layers.addVectorTile() |
| GeoJSON | G.geoJsonLayer() | new FeatureLayer() | app.layers.addGeoJson() |
| 热力图 | G.heatmapLayer() | new HeatmapLayer() | app.layers.addHeatmap() |
| 聚合图层 | G.clusterLayer() | new ClusterLayer() | app.layers.addCluster() |
| 3D 瓦片 | G.tileset3d() | new Tileset3DLayer() | app.layers.addTileset3D() |
| 点云 | G.pointCloud() | new PointCloudLayer() | app.layers.addPointCloud() |
| 添加图层 | .addTo(map) | map.addLayer() | app.layers.add*() |
| 移除图层 | -- | map.removeLayer() | app.layers.remove() |
| 图层列表 | map.getLayers() | map.getLayers() | app.layers.list() |
| 切换可见 | -- | layer.setVisible() | app.layers.setVisible() |
| 清空图层 | -- | -- | app.layers.clear() |
数据源
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| GeoJSON | G.geojson() | new GeoJsonSource() | app.data.loadGeoJson() |
| 矢量瓦片源 | G.vectorTileSource() | new VectorTileSource() | -- |
| 栅格瓦片源 | G.rasterSource() | new RasterTileSource() | -- |
| WMS 源 | G.wms() | new WmsSource() | -- |
| WMTS 源 | G.wmts() | new WmtsSource() | -- |
| 地形源 | G.terrainSource() | new TerrainSource() | -- |
| 添加源 | -- | map.addSource() | app.data.addSource() |
| 移除源 | -- | map.removeSource() | app.data.removeSource() |
| 查询要素 | -- | layer.query() | app.data.query() |
| 导出 GeoJSON | -- | -- | app.data.toGeoJson() |
几何类型
| 类型 | 简易版 | 标准版 |
|---|---|---|
| Point | G.geom.point() | new Point() |
| MultiPoint | G.geom.multiPoint() | new MultiPoint() |
| LineString | G.geom.lineString() | new LineString() |
| MultiLineString | G.geom.multiLineString() | new MultiLineString() |
| Polygon | G.geom.polygon() | new Polygon() |
| MultiPolygon | G.geom.multiPolygon() | new MultiPolygon() |
| Circle | G.geom.circle() | new Circle() |
| BoundingBox | G.geom.boundingBox() | new BoundingBox() |
| Ellipse | G.geom.ellipse() | new Ellipse() |
| Box3D | G.geom.box3d() | new Box3D() |
| Sphere3D | G.geom.sphere3d() | new Sphere3D() |
| Cylinder3D | G.geom.cylinder3d() | new Cylinder3D() |
| Cone3D | G.geom.cone3d() | new Cone3D() |
| GeometryCollection | G.geom.geometryCollection() | new GeometryCollection() |
符号类型
| 类型 | 简易版 | 标准版 |
|---|---|---|
| FillSymbol | G.fillSymbol() | new FillSymbol() |
| LineSymbol | G.lineSymbol() | new LineSymbol() |
| MarkerSymbol | G.markerSymbol() | new MarkerSymbol() |
| TextSymbol | G.textSymbol() | new TextSymbol() |
| PictureSymbol | G.pictureSymbol() | new PictureSymbol() |
| IconSymbol | G.iconSymbol() | new IconSymbol() |
| GradientFillSymbol | -- | new GradientFillSymbol() |
| CompositeSymbol | G.compositeSymbol() | new CompositeSymbol() |
| ModelSymbol | G.modelSymbol() | new ModelSymbol() |
| BillboardSymbol | G.billboardSymbol() | new BillboardSymbol() |
| DivIconSymbol | -- | new DivIconSymbol() |
渲染器
| 类型 | 简易版 | 标准版 |
|---|---|---|
| SimpleRenderer | G.simpleRenderer() | new SimpleRenderer() |
| UniqueValueRenderer | G.uniqueValueRenderer() | new UniqueValueRenderer() |
| ClassBreaksRenderer | G.classBreaksRenderer() | new ClassBreaksRenderer() |
| GraduatedSymbolRenderer | -- | new GraduatedSymbolRenderer() |
| DotDensityRenderer | -- | new DotDensityRenderer() |
| HeatmapRenderer | -- | new HeatmapRenderer() |
| MeshRenderer | -- | new MeshRenderer() |
| CustomRenderer | -- | new CustomRenderer() |
控件
| 控件 | 简易版 | 标准版 |
|---|---|---|
| ZoomControl | G.zoomControl() | new ZoomControl() |
| CompassControl | G.compassControl() | new CompassControl() |
| ScaleBarControl | G.scaleBarControl() | new ScaleBarControl() |
| AttributionControl | G.attributionControl() | new AttributionControl() |
| LayerSwitcherControl | G.layerSwitcherControl() | new LayerSwitcherControl() |
| BasemapSwitcherControl | G.basemapSwitcherControl() | new BasemapSwitcherControl() |
| FullscreenControl | G.fullscreenControl() | new FullscreenControl() |
| GeolocationControl | G.geolocationControl() | new GeolocationControl() |
| NavigationControl | G.navigationControl() | new NavigationControl() |
| OverviewMapControl | G.overviewMapControl() | new OverviewMapControl() |
| MousePositionControl | G.mousePositionControl() | new MousePositionControl() |
| SearchControl | G.searchControl() | new SearchControl() |
| ContextMenuControl | G.contextMenuControl() | new ContextMenuControl() |
| Legend | G.legendControl() | new Legend() |
| HashStateControl | G.hashStateControl() | new HashStateControl() |
交互
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 绘制 | G.draw() | new DrawInteraction() | app.interactions.draw() |
| 编辑 | G.edit() | new EditInteraction() | app.interactions.edit() |
| 量算 | G.measure() | new MeasureInteraction() | app.interactions.draw() |
| 弹窗 | G.popup() | new Popup() | app.interactions.popup() |
| 提示 | G.tooltip() | new Tooltip() | app.interactions.tooltip() |
| 拖拽平移 | -- | map.enableDragPan() | app.interactions.setInput() |
| 滚轮缩放 | -- | map.enableScrollZoom() | app.interactions.setInput() |
| 双击缩放 | -- | map.enableDoubleClickZoom() | app.interactions.setInput() |
| 旋转 | -- | map.enableRotate() | app.interactions.setInput() |
样式
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| Mapbox 样式 | -- | new Style() | app.style.apply() |
| 设置绘制属性 | -- | style.setPaintProperty() | app.style.setPaint() |
| 设置布局属性 | -- | style.setLayoutProperty() | app.style.setLayout() |
| 设置过滤 | -- | style.setFilter() | app.style.setFilter() |
| 添加图片 | -- | map.addImage() | app.style.addImage() |
| 设置地形 | -- | map.setTerrain() | app.style.setTerrain() |
事件
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 监听事件 | map.on() | map.on() | app.on() |
| 一次性监听 | map.once() | map.once() | app.once() |
| 移除监听 | map.off() | map.off() | app.off() |
引擎
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 注册引擎 | G.use() | EngineRegistry.register() | -- |
| 切换引擎 | -- | map.switchEngine() | app.engine.switch() |
| 当前引擎 | -- | map.getEngine() | app.engine.current() |
| 获取原生 | -- | map.getNative() | app.getNative() |
工具
| 功能 | 简易版 | 标准版 | 专业版 |
|---|---|---|---|
| 距离量算 | G.utils.distance() | Measurement.distance() | app.measure.distance() |
| 面积量算 | -- | Measurement.area() | app.measure.area() |
| 方位角 | -- | Measurement.bearing() | app.measure.bearing() |
| 缓冲区 | -- | Analysis.buffer() | app.analysis.buffer() |
| 凸包 | -- | GeomUtils.convexHull() | -- |
| 简化 | -- | GeomUtils.simplify() | -- |
| 坐标转换 | G.utils.projection.transform() | ProjectionUtils.transform() | -- |
选型建议
按团队规模
| 团队规模 | 推荐版本 | 理由 |
|---|---|---|
| 1-3 人小团队 | 简易版 | 代码量少，上手快，维护成本低 |
| 5-10 人中型团队 | 标准版 | 完整类型系统，多人协作友好 |
| 10+ 人大型团队 | 专业版 | 模块化架构，关注点分离 |
按技术栈
| 技术栈 | 推荐版本 | 理由 |
|---|---|---|
| 后端开发为主 | 简易版 | API 简洁，无需深入前端地图概念 |
| 前端开发为主 | 标准版 | 符合前端工程化习惯 |
| 架构师主导 | 专业版 | 门面模式便于架构设计 |
按项目类型
| 项目类型 | 推荐版本 | 理由 |
|---|---|---|
| 数据可视化大屏 | 简易版 | 快速搭建，功能够用 |
| GIS 业务系统 | 标准版 | 需要精细控制图层和符号 |
| 多引擎切换系统 | 专业版 | 内置引擎管理子门面 |
| 2D/3D 一体化系统 | 专业版 | 完整的引擎切换和视图同步能力 |
按功能需求
| 功能需求 | 推荐版本 |
|---|---|
| 只需要展示地图 | 简易版 |
| 需要自定义符号和渲染 | 标准版 |
| 需要空间分析和量算 | 标准版或专业版 |
| 需要运行时切换引擎 | 专业版 |
| 需要 3D 场景效果 | 专业版 |
版本迁移
简易版 → 标准版
ts
// 简易版
import G from "@gmap/simple";
const map = G.map({ target: "map", engine: "ol" });
G.tileLayer({ url: "..." }).addTo(map);
// 标准版
import { createMap, RasterTileLayer } from "@gmap/standard";
const map = await createMap({ target: "map", engine: "ol" });
map.addLayer(new RasterTileLayer({ url: "..." }));标准版 → 专业版
ts
// 标准版
import { createMap, RasterTileLayer } from "@gmap/standard";
const map = await createMap({ target: "map", engine: "ol" });
map.addLayer(new RasterTileLayer({ url: "..." }));
await map.flyTo({ center: [121, 31], zoom: 12 });
// 专业版
import { createMapFacade } from "@gmap/advanced";
const app = await createMapFacade({ target: "map", engines: "ol" });
app.layers.addTile({ url: "..." });
app.camera.flyTo({ center: [121, 31], zoom: 12 });