图层

createBaseLayer

按代号创建内置底图。高德/百度/海图返回 TileLayer，天地图（瓦片+注记两层）返回 LayerGroup，均带 properties.type = BASE_LAYER_TYPE 标记便于底图管理。

import { createBaseLayer } from 'geoverse';
map.addLayer(createBaseLayer('tiandi-w', { tiandituToken: 'xxx', zIndex: -2 }));

签名：createBaseLayer(reference: BaseLayerReference, config?: BaseLayerConfig): BaseLayer

BaseLayerReference：'gd-vec' 'gd-sat' 'bd-vec' 'bd-sat' 'ocean' 'tiandi-w' 'tiandi-c' 'tiandi-imgw' 'tiandi-imgc'。

BaseLayerConfig：

字段	类型	默认	说明
`urls`	`BaseLayerUrls`	—	自有/离线瓦片地址覆盖
`tiandituToken`	`string`	—	天地图 token（在线 tiandi-* 必填）
`zIndex`	`number`	—	图层 zIndex
`preload`	`number`	`Infinity`	瓦片预加载层级

BaseLayerUrls 键：gdVec gdSat bdVec bdSat ocean tiandiVecW tiandiCvaW tiandiVecC tiandiCvaC tiandiImgW tiandiCiaW tiandiImgC tiandiCiaC。

常量 BASE_LAYER_TYPE = 'geoverse:base'。

GVectorLayer

继承 ol/layer/Vector。setVisible / getVisible / setZIndex / setOpacity / getSource / setStyle / setMap / set / get 等基类方法可用。

通用矢量要素图层，默认自带空 VectorSource，维护 projection 属性：要素以 EPSG:3857 创建，加入图层时自动转换到图层当前投影（GMap 底图切换时同步重投影）。ClusterLayer / SuperClusterLayer / NameLayer 继承它。

const layer = new GVectorLayer({ zIndex: 5 });
map.addLayer(layer);
layer.addFeature(new Marker({ position: [118.18, 24.49] }));

方法	签名	说明
`addFeature` / `addFeatures`	`(feature)` / `(features)`	添加要素
`removeFeature`	`(feature)`	移除要素
`removeFeatureById`	`(id: string\|number)`	按 featureId 移除
`getFeatureById`	`(id) => Feature\|null`	按 featureId 获取
`getLinkFeatures`	`() => Feature[]`	全部要素
`refresh` / `clear`	`()`	刷新 / 清空

构造选项继承 ol/layer/Vector 的 Options（source / style / zIndex / visible / opacity / properties 等）。

HeatLayer

继承 ol/layer/Heatmap。setBlur / setRadius / setGradient / setVisible 等基类方法可用。

热力图层，支持以经纬度数组直接初始化。

new HeatLayer({
  coordinates: [
    [118.1, 24.4],
    [118.2, 24.5],
  ],
  radius: 12,
  blur: 18,
});

构造选项 HeatLayerOptions（继承 ol/layer/Heatmap 的 Options：blur / radius / gradient / weight 等），新增：

字段	类型	说明
`coordinates`	`Coordinate[]`	初始热力点（WGS-84，>5 万点告警）

属性 collection: Collection<Feature<Point>> \| undefined —— coordinates 方式初始化时的要素集合。

GImageLayer

继承 ol/layer/Image。

静态栅格图片图层。构造选项 GImageLayerOptions（继承 ol/layer/Image 的 Options），新增：

字段	类型	说明
`base`	`string`	图片地址
`projection`	`string`	图片投影
`bounds`	`number[]`	图片四至 `[minX, minY, maxX, maxY]`

MassLayer

继承 ol/layer/Image（数据源 MassSource 继承 ol/source/ImageCanvas）。

海量点图层，canvas 批量绘制，承载十万级点位。

const mass = new MassLayer({
  map,
  graphics: points.map((p) => new Graphic([p.lng, p.lat])),
  hitZoom: 15,
  onClick: (g) => console.log(g?.getAttributes()),
});
map.addLayer(mass);

构造选项 MassLayerOptions（继承 ol/layer/Image 的 Options），新增：

字段	类型	默认	说明
`graphics`	`Graphic[]`	—	初始海量点（WGS-84 经纬度）
`map`	`Map`	—	地图实例（命中交互/投影转换需要）
`hitZoom`	`number`	`15`	命中交互最小层级
`onClick`	`GraphicHitCallback`	—	点击回调 `(graphic, event) => void`
`onHover`	`GraphicHoverCallback`	—	悬浮回调 `(graphic, 'mouseover'\|'mouseout') => void`

方法	签名	说明
`setGraphics` / `addGraphics`	`(graphics)`	重置 / 追加海量点
`getGraphics`	`() => Graphic[]`	全部 graphic
`getGraphicById`	`(id) => Graphic\|null`	按 id 获取
`getGraphicsByAttribute`	`(key, value) => Graphic[]`	按属性筛选
`getGraphicsInExtent`	`(extent?) => Graphic[]`	范围内 graphic
`removeGraphic`	`(graphic)`	移除（需 graphic 有 id）
`clear`	`()`	清空

MassSource 额外提供 destroy() 回收地图监听；GMap 移除图层时自动调用。

ClusterLayer

继承 GVectorLayer（→ ol/layer/Vector）。

距离聚合图层（基于 ol/source/Cluster），适合万级以下、需要分档自定义图标的场景；十万级以上用 SuperClusterLayer。

const cluster = new ClusterLayer({ map, markers, distance: 80, zIndex: 6 });
map.addLayer(cluster);

构造选项 ClusterLayerOptions：

字段	类型	默认	说明
`map`	`Map`	—	地图实例（层级联动/getMaxZoom 需要）
`distance`	`number`	`100`	触发聚合的最大像素间距
`markers`	`Feature<Point>[]`	`[]`	初始标注点
`styles`	`ClusterStyleRule[]`	`[]`	分档样式；空则用内置三档图标
`maxZoom`	`number`	`23`	超过该层级取消聚合显示散点
`showMarker`	`boolean`	`true`	单点是否显示原始 marker 样式
`isZoom`	`boolean`	`true`	点击聚合点是否放大
`zIndex` / `visible`

ClusterStyleRule：minNum? / maxNum?（点数区间）、url（图标）、textColor、size?、offset?、textSize?。

方法	签名	说明
`addFeature` / `addFeatures`	`(feature)` / `(features)`	新增标注点
`removeFeature` / `removeFeatures`	`(feature)` / `(features)`	移除
`removeFeatureById`	`(id)`	按 id 移除
`getFeatureById`	`(id) => Feature\|null`	按 id 获取
`getAllFeatures`	`() => Feature[]`	全部原始标注点
`getMarkersInBounds`	`(bounds: Coordinate[]) => Feature[]`	多边形范围内的点
`clearFeatures`	`()`	清空
`getMaxZoom`	`() => number`	估算"全部点不再聚合"的层级

属性 rawSource（散点源）、clusterSource（聚合源）。

SuperClusterLayer

继承 GVectorLayer（数据源 SuperClusterSource 继承 ol/source/Vector）。

supercluster 空间索引聚合，适合十万级点位。

new SuperClusterLayer({ view: map.getView(), markers, sradius: 60 });

构造选项 SuperClusterLayerOptions：

字段	类型	默认	说明
`view`	`View`	必填	地图视图（聚合层级范围依据它）
`markers`	`Feature[]`	`[]`	初始标注点
`sradius`	`number`	`60`	聚合像素半径
`styles`	`ClusterStyleRule[]`	`[]`	分档样式
`zIndex` / `visible`

方法	签名	说明
`addFeature` / `addFeatures`		新增标注点
`removeFeature`		移除
`removeFeatureById` / `getScFeatureById`	`(id)`	按 featureId 移除 / 获取
`getAllFeatures` / `clearFeatures`		全部 / 清空
`getClusterExpansionZoom`	`(feature) => number`	聚合点散开所需层级

属性 clusterSource: SuperClusterSource。

ClusterStyleResolver —— 聚合分档样式计算器（SuperClusterLayer 内部使用，也可单独用）：new ClusterStyleResolver({ styles?, featureSum? })，方法 calStyle(feature) => Style | undefined。

TrafficLayer

继承 ol/layer/Tile。

实时路况图层（高德/百度路况瓦片）。

new TrafficLayer({ origin: 'BD', isDynamic: true, rate: 90 });

构造选项 TrafficLayerOptions（继承 ol/layer/Tile 的 Options），新增：

字段	类型	默认	说明
`origin`	`'GD' \| 'BD'`	`'GD'`	路况来源
`isDynamic`	`boolean`	`false`	是否定时刷新
`rate`	`number`	`90`	刷新间隔（秒）
`urlTemplate`	`string`	公网地址	自定义路况地址（`{x}/{y}/{z}/{time}` 占位）

方法	签名	说明
`getDynamic`	`() => boolean`	是否定时刷新
`setDynamic`	`(flag: boolean) => void`	启停定时刷新

dispose() 时定时器一定被清理。

CustomBaseLayer

继承 ol/layer/Tile。

自定义底图：接入 XYZ / WMS / ArcGIS REST / 超图 iServer。带 BASE_LAYER_TYPE 标记，参与 GMap 底图管理。

new CustomBaseLayer({
  serverType: 'WMSSERVER',
  url: 'http://host/geoserver/wms',
  layers: 'ws:layer',
  projection: 'EPSG:3857',
});

构造选项 CustomBaseLayerOptions（继承 ol/layer/Tile 的 Options），新增：

字段	类型	默认	说明
`serverType`	`CustomBaseServerType`	`'TILESERVER'`	服务类型
`url`	`string`	`''`	服务地址（XYZ 模板或服务根）
`projection`	`string`	`'EPSG:3857'`	投影（XYZ 时 BD:09/GCJ:02 走纠偏网格）
`layers`	`string`	`''`	WMS 图层名

CustomBaseServerType：'TILESERVER' 'WMSSERVER' 'ARCGISDYNAMIC' 'ARCGISTILE' 'SUPERMAPREST'。

其他导出

isInPolygon(checkPoint: Coordinate, polygonPoints: Coordinate[]) => boolean —— 射线法判断点是否在多边形内。
CLUSTER_ICON_SMALL / CLUSTER_ICON_MEDIUM / CLUSTER_ICON_LARGE —— 内置三档聚合图标（base64）。

图层 ​

createBaseLayer ​

GVectorLayer ​

HeatLayer ​

GImageLayer ​

MassLayer ​

ClusterLayer ​

SuperClusterLayer ​

TrafficLayer ​

CustomBaseLayer ​

其他导出 ​

图层