地图容器

GMap

继承 ol/Map。ol/Map 的全部方法（addLayer / removeLayer / getView / getLayers / addOverlay / addInteraction / getControls / on / once / un / forEachFeatureAtPixel / getFeaturesAtPixel / hasFeatureAtPixel / getCoordinateFromPixel / getPixelFromCoordinate / render / updateSize / dispose …）均原样可用。

GeoVerse 的地图容器，相对 ol/Map 增强四点：

构造时自动注册国内坐标系（GCJ-02 / BD-09 / EPSG:3395，幂等）
内置高德/百度/天地图/海图底图与底图切换（含图层重投影）
地图级 pointer 事件统一派发为要素级 click / mouseover / mouseout
一组以经纬度为参数的便捷视图方法

import { GMap } from 'geoverse';

const map = new GMap({
  target: 'map',
  base: 'gd-vec',
  center: [118.18, 24.49],
  zoom: 12,
});

构造选项 `GMapOptions`

继承 ol/Map 的 MapOptions（target / layers / controls / view / interactions / overlays 等仍可用），新增下列字段：

字段	类型	默认	说明
`base`	`BaseLayerReference \| false`	`'gd-vec'`	内置底图代号；`false` 不加底图。用 `tiandi-*` 需配 `baseConfig.tiandituToken`
`baseConfig`	`BaseLayerConfig`	—	底图配置：离线地址 `urls`、天地图 `tiandituToken`
`center`	`Coordinate`	`[118.15, 24.56]`	初始中心（WGS-84 经纬度）
`zoom`	`number`	`12`	初始层级
`minZoom` / `maxZoom`	`number`	按投影	GCJ 默认 min 3、BD 默认 max 19，其余 0/18
`scaleLine`	`boolean`	`false`	是否显示比例尺控件
`fullScreen`	`boolean`	`false`	是否显示全屏控件

视图投影由 base 推断：gd-* → GCJ:02，bd-* → BD:09，ocean → EPSG:3395，其余 → EPSG:3857。

视图方法（经纬度语义）

方法	签名	说明
`panTo`	`(options: PanToOptions) => void`	平滑移动到位置（视图投影坐标）
`getZoom` / `setZoom`	`() => number\|undefined` / `(zoom: number) => void`	当前层级
`getMinZoom` / `getMaxZoom`	`() => number`	层级范围
`getCenter` / `setCenter`	`() => Coordinate` / `(lonLat: Coordinate) => void`	中心点（WGS-84 经纬度）
`setZoomAndCenter`	`(zoom: number, lonLat: Coordinate) => void`	同时设置层级与中心
`getDistance`	`(c1: Coordinate, c2: Coordinate) => number`	两经纬度点球面距离（米）
`getBounds`	`() => number[]`	当前视野范围（视图投影坐标）
`isInBounds`	`(lonLat: Coordinate) => boolean`	经纬度点是否在视野内
`getContainer`	`() => HTMLElement\|undefined`	地图容器元素
`setCursor`	`(cursor: string) => void`	设置鼠标样式，`'default'` 视为恢复
`setUserProjection`	`(proj: string) => void`	透传 `ol/proj.setUserProjection`
`setFullScreen`	`(fullscreen: boolean) => void`	全屏切换（需开 `fullScreen` 控件）

PanToOptions：position?: Coordinate（视图投影坐标）、zoom?: number、offset?: [number, number]（像素偏移）、rotateAngle?: number（度）、duration?: number（默认 1000ms）。

底图管理

方法	签名	说明
`switchBase`	`(reference: BaseLayerReference, config?: BaseLayerConfig) => void`	切换底图，必要时切视图投影并重投影既有图层/弹窗，同步鹰眼
`getBaseLayers`	`() => BaseLayer[]`	全部底图图层
`removeBaseLayers`	`() => void`	移除全部底图
`getContentLayers`	`() => BaseLayer[]`	全部内容图层（不含底图）
`removeContentLayers`	`() => void`	移除全部内容图层（保留底图）
`resetOverview`	`() => void`	同步鹰眼的视图投影与底图（`switchBase` 内部已调用）
`showTraffic`	`(visible: boolean, opts?: { origin?: 'GD'\|'BD'; isDynamic?: boolean }) => void`	显隐实时路况，首次调用自动创建

图层 / 要素 / 弹窗检索

方法	签名	说明
`getLayerById`	`(id: string\|number) => BaseLayer\|undefined`	按 `id` 属性获取内容图层
`removeLayerById`	`(id: string\|number) => void`	按 id 移除图层
`getFeatureById`	`(id: string\|number) => Feature\|undefined`	全矢量图层中按 id 检索要素
`getAllFeatures`	`() => Feature[]`	全部矢量要素
`removeFeature`	`(feature: Feature) => void`	从所有矢量图层移除要素
`removeFeatureById`	`(id: string\|number) => void`	按属性 id 或 featureId 移除要素
`getInfoWindowById`	`(id: string\|number) => Overlay\|undefined`	按 id 获取弹窗
`getAllInfoWindows`	`() => Overlay[]`	全部弹窗
`removeInfoWindow` / `removeInfoWindowById`	`(overlay\|id) => void`	移除弹窗
`unEventByKey`	`(key: EventsKey \| EventsKey[]) => void`	解绑 on/once 注册的监听
`clearDrawSource`	`() => void`	清空绘制与测量痕迹

海量点命中检测

方法	签名	说明
`forEachSmFeatureAtPixel`	`(pixel, callback, options?, event?) => unknown`	同时检测普通要素与海量点 graphic
`hasGraphicAtPixel`	`(pixel, options?, event?) => boolean`	像素是否命中海量点 graphic

导出与销毁

方法	签名	说明
`exportPng`	`(options?: ExportPngOptions) => void`	导出当前画面为 PNG 并触发下载
`destroy`	`() => void`	解绑容器并释放资源（替代有递归 bug 的 `dispose`）

ExportPngOptions：filename?: string（默认 map.png）、callback?: (dataUrl: string) => void。

要素级事件

GMap 在地图层面监听 pointer 事件，向命中的要素派发 FeaturePointerEvent，业务侧通过要素订阅（见 GFeature.onPointer）。聚合点点击自动放大、双击散开。

InfoWindow

继承 ol/Overlay。setElement / getElement / setPosition / getPosition / setOffset / getId / setPositioning 等基类方法可用。

信息弹窗，位置统一使用 WGS-84 经纬度。

import { InfoWindow } from 'geoverse';

const win = new InfoWindow({
  content: '<div class="popup">你好</div>',
  map,
  position: [118.18, 24.49],
});
win.open(map, [118.18, 24.49]);

构造选项 `InfoWindowOptions`

继承 ol/Overlay 的 Options（offset / positioning / stopEvent / insertFirst / autoPan / className 等），新增：

字段	类型	说明
`content`	`string \| HTMLElement`	内容：HTML 字符串、元素 id 或 DOM 元素
`map`	`Map`	创建后立即挂载到该地图

方法

方法	签名	说明
`open`	`(map: Map, lonLat?: Coordinate) => void`	打开弹窗（可选传入新经纬度），派发 `open` 事件
`close`	`() => void`	关闭并从地图移除，派发 `close` 事件
`getContent`	`() => string`	获取内容 HTML 字符串
`setContent`	`(content: string \| HTMLElement) => void`	设置内容
`setLonLatPosition`	`(lonLat: Coordinate) => void`	以经纬度设置位置（按当前视图投影换算）
`getZIndex` / `setZIndex`	`() => string\|undefined` / `(z: string\|number) => void`	弹窗容器 zIndex

常量 INFO_WINDOW_HIDDEN_CLASS（'geoverse-overlay-hidden'）—— 隐藏态 class，样式见包内 style.css。

FeaturePointerEvent

继承 ol/events/Event。

要素级交互事件对象，由 GMap 派发给命中要素。

成员	类型	说明
`type`	`'click' \| 'mouseover' \| 'mouseout'`	事件类型
`mapEvent`	`MapBrowserEvent \| undefined`	触发它的原始地图事件（含 `coordinate` / `pixel`）

地图容器 ​

GMap ​

构造选项 GMapOptions ​

视图方法（经纬度语义） ​

底图管理 ​

图层 / 要素 / 弹窗检索 ​

海量点命中检测 ​

导出与销毁 ​

要素级事件 ​

InfoWindow ​

构造选项 InfoWindowOptions ​

方法 ​

FeaturePointerEvent ​