OpenLayers点要素聚合Cluster显示
OpenLayers 点要素聚合用 ol/source/Cluster 完成:把存放点要素的 VectorSource 作为底层 source 传入,按像素距离把邻近点合成一个聚合 Feature。聚合 Feature 带有 features 属性(原要素数组),样式函数里用其 length 画圆并标数字即可。开箱支持点几何;非点或需排除部分要素时,自定义 geometryFunction。截至 2026 年 11 月,文档与示例对应稳定版 v10.11.0。

基本实现步骤
要解决的问题很直接:点太多时重叠难辨,需要按屏幕像素距离合并显示。下面按可执行顺序写出核心链路(假设已有地图实例与投影一致的点数据,常用 EPSG:3857)。更细的代码逻辑与完整示例可对照本站OpenLayers点聚合怎么实现与代码逻辑说明。
- 准备底层 VectorSource,向其中添加点 Feature(几何为 Point)。
- 创建 Cluster,把上述 source 传入;按需设置 distance(默认 20)、minDistance(默认 0)。
- 用 Cluster 作为 VectorLayer 的 source,并写样式函数:读取 feature.get(‘features’).length,按数量选半径与文字。
- 把图层加到地图;用 styleCache 按 size 缓存 Style,避免重复创建。
- 验收:缩放/平移时簇会重算;单个点处 size 为 1;簇上数字等于合并前要素个数。
npm 项目中按模块引入即可:import Cluster from ‘ol/source/Cluster.js’。官方点聚合示例见 OpenLayers Cluster 官方示例,API 细节见 ol/source/Cluster 类文档。
distance、minDistance 与其它构造参数怎么选
聚合是否“好看、不糊在一起”,主要看像素距离配置;其它参数按数据几何与是否需要自定义簇对象来定。
| 参数 | 含义 | 默认 / 选用建议 |
|---|---|---|
| source | 底层矢量数据源 | 必需;传你的 VectorSource |
| distance | 多少像素内合并为一簇 | 默认 20;点密可略加大,点稀可减小 |
| minDistance | 簇与簇之间最少像素间隔 | 默认 0;图标易重叠时可设为图标宽高量级,但簇位置不再是精确几何中心 |
| geometryFunction | 从 Feature 取用于聚类的 Point(或返回 null 排除) | 默认取 feature 几何;多边形可用 getInteriorPoint |
| createCluster | 用中心 Point 与 features 数组生成渲染用 Feature | 一般用默认即可 |
| wrapX | 是否横向世界环绕 | 默认 true;按地图需求 |
运行时可调用 setDistance / setMinDistance 联动滑块或缩放级别。minDistance 会封顶在 distance 以内。投影要一致:数据若是地理坐标而视图是 Web 墨卡托,聚类表现会异常,先统一 CRS。

样式怎么写、点击簇怎么处理
聚合 Feature 上读 features 数组是关键:
- 用 const size = feature.get(‘features’).length; 决定圆半径、颜色深浅和文字内容。
- 官方示例用 styleCache 按 size 缓存 Circle + Text,数量变化大时能明显减负。
- 点击“放大到簇”:取该簇 features 的几何,用 boundingExtent 算范围再 view.fit;动态凸包、点击拆开重叠点等可参考官方高级示例思路,本篇只要求点聚合主路径可用。
交互上注意:Select 与 Cluster 常不兼容(簇内要素对象会被重建)。更稳妥的是 map.getFeaturesAtPixel() 或图层 getFeatures() 再解析 features 属性。需要展开逻辑时,可先按本站点聚合实现与代码逻辑核对数据结构,再接到点击回调。
性能、数据与几何上的注意点
- 无效几何(如纬度超出合理范围导致 NaN):点或整簇会“消失”。入库前校验坐标。
- 非点几何:仅依赖默认 geometryFunction 时,缩放中计算点可能离开视口导致“消失”;应用 geometryFunction 固定代表点,或在 style 里改回画原几何。
- 频繁增删:每次变动都会触发全量重聚类;用 Collection 单条推送更吃亏,宜批量替换 features。
- 超大规模(例如十几万、二十万点以上):内置 Cluster 可能不够用,需考虑仅对当前可视范围聚类或引入专用聚类库;本篇验收以中小规模点层流畅为准。
- 销毁 Cluster 时若未销毁底层 source,应先 setSource(null),去掉对底层的监听引用。
常见问题
聚合圆重叠、数字看不清怎么办?
先调大 distance,再设 minDistance(接近图标尺寸)减轻重叠;同时用 styleCache 按 size 加大半径、加深描边。注意 minDistance 会让簇中心偏离几何均值,标注锚点要跟着圆走。
点击簇后用 Select 选不中内部点?
Cluster 会重建聚合 Feature,Select 绑的对象容易失效。改用 getFeaturesAtPixel,从命中要素的 features 属性取原子点再处理。
缩放到某一级后部分多边形或点没了?
检查 geometryFunction 返回的点是否仍在视口内,以及坐标是否合法;多边形聚类务必返回稳定的内部点,并确认图层投影与视图一致。
distance 改了画面没反应?
确认改的是 Cluster 实例(setDistance),且该 Cluster 已是 VectorLayer 的 source;改底层 VectorSource 的 distance 无效。改完平移或缩放一次触发重绘做验收。
要点回顾:用 Cluster 包住 VectorSource,靠 distance/minDistance 控制合并与间距,样式读 features.length,交互优先像素拾取而非硬绑 Select。建议先按中等数据量跑通官方示例同款“圆+数字+点击 fit”,再按图标尺寸微调 minDistance;数据与 CRS 校验过关后,再考虑可视范围过滤或外部聚类方案。