专业版 API 概览

专业版 API (@gmap/advanced) 采用门面模式（Facade Pattern），将地图功能组织为子门面。

创建门面

import { createMapFacade } from '@gmap/advanced';

const app = await createMapFacade({
  target: 'map',                // 容器元素或 DOM ID
  engines: 'ol',                // 引擎（字符串 / 数组 / 对象）
  center: [116, 39],            // 初始中心
  zoom: 10,                     // 初始缩放
  mode: '2d',                   // 维度模式
  basemap: 'osm',               // 底图标识
  projection: 'EPSG:3857',      // 坐标系
  theme: 'light',               // 主题
  strict: false,                // 是否禁止原生访问
  lazyEngines: {},              // 延迟加载引擎
  onError: (err) => {},         // 错误处理
});

也可通过 new MapFacade(options) 构造后调用 await app.whenReady()。

子门面

子门面	属性	职责
相机	app.camera	视图/相机控制
图层	app.layers	图层管理
数据	app.data	数据源/要素管理
样式	app.style	Mapbox 样式
交互	app.interactions	绘制/编辑/交互
选择	app.selection	要素选择
分析	app.analysis	空间分析
量算	app.measure	距离/面积量算
效果	app.effects	3D 场景效果
引擎	app.engine	引擎管理
动画	app.animation	动画控制

Ref 类型

每个子门面的增删操作返回轻量级的 Ref 对象：

类型	属性	说明
LayerRef	id, setVisible, setOpacity, setZIndex, remove	图层引用
FeatureRef	id, getAttributes, setAttributes, flyTo, remove	要素引用
SourceRef	id, update, refresh, remove	数据源引用
InteractionRef	id, stop	交互引用
PopupRef	id, setContent, open, close, remove	弹窗引用
EffectRef	id, setEnabled, remove	效果引用

顶层方法

方法	返回值	说明
app.on(type, handler, options?)	Disposable	事件订阅
app.once(type, handler, options?)	Disposable	一次性事件订阅
app.off(type, handler?)	void	取消事件订阅
app.whenReady()	Promise<MapFacade>	就绪 Promise
app.resize()	void	调整大小
app.exportImage(options?)	Promise<string>	导出图片（base64）
app.setTheme(theme)	this	设置主题（'light' / 'dark'）
app.getStats()		获取性能统计
app.getNative(options?)	unknown	获取底层引擎对象
app.destroy()	void	销毁所有资源

属性

属性	类型	说明
app.id	string	门面实例唯一标识
app.mode	'2d' | '3d'	当前维度模式
app.ready	boolean	是否就绪
app.services	Record<string, unknown>	地图服务集合

完整示例

import { createMapFacade } from '@gmap/advanced';

const app = await createMapFacade({
  target: 'map',
  engines: 'ol',
  center: [116.397, 39.908],
  zoom: 12,
  theme: 'light',
});

// 相机控制
app.camera.setZoom(15).setCenter([121, 31]);

// 添加图层
const ref = app.layers.addTile({ id: 'osm', url: 'https://...' });
ref.setVisible(false).setOpacity(0.5);

// 绘制交互
const draw = app.interactions.draw('polygon');
// ... 停止
app.interactions.stop(draw);

// 样式
app.style.apply({ version: 8 }).setTheme('dark');

// 选择
app.selection.set([feature1, feature2]);

// 清理
app.destroy();