OpenLayers点聚合怎么实现?代码逻辑是什么?

wowwwai GIS研习社 · 工具流程与项目排障

很多 WebGIS 初学者搜索“OpenLayers点聚合怎么实现?代码逻辑是什么?”，其实真正要解决的是两个问题：一是如何把大量点要素在地图缩放时自动聚合，二是理解 OpenLayers 内部的聚合图层、聚合数据源和样式函数分别负责什么。

本文以 OpenLayers 6/7/8 常见写法为例，演示一个可直接改造到项目中的点聚合实现流程。示例使用 ol/source/Cluster、ol/source/Vector 和 ol/layer/Vector，适合 POI 点、设备点、事件点、巡检点等 WebGIS 场景。

引言：OpenLayers点聚合适合解决什么问题

OpenLayers点聚合主要用于解决“大量点同时显示导致地图卡顿、图面拥挤、点击困难”的问题。比如一个城市有几万条监测设备点，如果直接把所有点渲染在地图上，用户在小比例尺下看到的往往是一团重叠符号。

点聚合的思路是：地图缩小时，把相邻点合并成一个聚合圆点，并显示数量；地图放大后，聚合点逐步拆分，最后恢复为单个点。这样既能保留空间分布趋势，也能明显降低渲染压力。

背景：OpenLayers点聚合的典型业务场景

在 GIS 项目中，OpenLayers点聚合常见于以下场景：

• 城市 POI 点位展示，例如学校、医院、停车场、商铺。
• 物联网设备地图，例如摄像头、井盖传感器、气象站。
• 事件上图，例如报警点、工单点、巡查问题点。
• 轨迹停留点、采样点、用户签到点的概览展示。
• 后台管理系统中的海量点位快速浏览。

如果你的需求只是显示几十个点，通常不需要点聚合；如果点数量达到几千甚至几万，并且用户需要频繁缩放、平移和点击查看，那么点聚合就是比较合适的方案。

原理：OpenLayers点聚合代码逻辑是什么

理解 OpenLayers点聚合代码逻辑，关键要分清三个对象：

• VectorSource：保存原始点要素，每一个 Feature 对应一个真实业务点。
• ClusterSource：包裹 VectorSource，根据屏幕像素距离把相邻点合并成聚合要素。
• VectorLayer：负责把 ClusterSource 生成的聚合结果绘制到地图上。

也就是说，聚合并不是修改你的原始数据坐标，也不是把数据库中的点真的合并了。OpenLayers 的聚合是在前端渲染层完成的，随着地图缩放级别和视图分辨率变化，聚合结果会重新计算。

每一个聚合后的 Feature 都有一个特殊属性：

features

这个 features 是一个数组，里面保存了被聚合到一起的原始点 Feature。判断当前符号是“单点”还是“聚合点”，主要看这个数组长度。

const originalFeatures = clusterFeature.get('features');
const count = originalFeatures.length;

if (count === 1) {
  // 单点
} else {
  // 聚合点
}

步骤：OpenLayers点聚合怎么实现

步骤一：准备 HTML 容器和 OpenLayers 依赖

如果使用原生 HTML 页面测试，可以通过 CDN 引入 OpenLayers。生产项目中也可以使用 npm、Vite、Webpack 等方式安装。

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v8.2.0/ol.css">

<div id="map" style="width: 100%; height: 500px;"></div>

<script src="https://cdn.jsdelivr.net/npm/ol@v8.2.0/dist/ol.js"></script>

下面示例使用全局变量 ol 的写法，方便初学者直接复制运行。如果你的项目使用模块化导入，逻辑是一样的，只是 import 写法不同。

步骤二：创建地图底图和视图

const map = new ol.Map({
  target: 'map',
  layers: [
    new ol.layer.Tile({
      source: new ol.source.OSM()
    })
  ],
  view: new ol.View({
    center: ol.proj.fromLonLat([116.391, 39.907]),
    zoom: 11
  })
});

这里使用 OpenStreetMap 作为底图，视图中心设置在北京附近。注意 OpenLayers 默认地图投影通常是 EPSG:3857，所以经纬度坐标需要通过 ol.proj.fromLonLat 转换。

步骤三：构造原始点 Feature

真实项目中，点数据可能来自 GeoJSON、接口返回的 JSON、数据库查询结果或 WFS 服务。这里用模拟点来说明 OpenLayers点聚合的代码结构。

const features = [];

for (let i = 0; i < 500; i++) {
  const lon = 116.20 + Math.random() * 0.45;
  const lat = 39.75 + Math.random() * 0.35;

  const feature = new ol.Feature({
    geometry: new ol.geom.Point(ol.proj.fromLonLat([lon, lat])),
    name: '点位-' + i,
    id: i
  });

  features.push(feature);
}

const vectorSource = new ol.source.Vector({
  features: features
});

这里每个点都创建为一个 ol.Feature，几何类型是 ol.geom.Point。业务字段如 name、id 可以直接挂在 Feature 属性上，后续点击聚合点时仍然可以取到。

步骤四：创建 ClusterSource

OpenLayers点聚合最关键的一步是创建 ol.source.Cluster。它接收原始 vectorSource，并通过 distance 控制聚合距离。

const clusterSource = new ol.source.Cluster({
  distance: 40,
  minDistance: 10,
  source: vectorSource
});

• distance：聚合距离，单位是屏幕像素。值越大，越容易聚合。
• minDistance：聚合符号之间的最小显示距离，可减少聚合圆点重叠。
• source：原始点数据源。

需要注意，distance 不是米，也不是经纬度单位，而是屏幕像素。因此地图缩放后，聚合结果会发生变化。

步骤五：设置聚合样式函数

聚合图层通常需要一个样式函数，根据聚合数量显示不同颜色、半径和文字。

const styleCache = {};

function getClusterStyle(feature) {
  const clusteredFeatures = feature.get('features');
  const size = clusteredFeatures.length;

  if (styleCache[size]) {
    return styleCache[size];
  }

  let radius = 14;
  let fillColor = '#3399CC';

  if (size >= 10 && size < 50) {
    radius = 18;
    fillColor = '#ff9900';
  } else if (size >= 50) {
    radius = 24;
    fillColor = '#ff3333';
  }

  const style = new ol.style.Style({
    image: new ol.style.Circle({
      radius: radius,
      stroke: new ol.style.Stroke({
        color: '#ffffff',
        width: 2
      }),
      fill: new ol.style.Fill({
        color: fillColor
      })
    }),
    text: new ol.style.Text({
      text: size.toString(),
      fill: new ol.style.Fill({
        color: '#ffffff'
      }),
      font: 'bold 13px sans-serif'
    })
  });

  styleCache[size] = style;
  return style;
}

这里使用了 styleCache 缓存样式对象。因为样式函数会在地图渲染过程中频繁执行，如果每次都 new 一个样式对象，点数量大时会增加前端压力。

步骤六：创建聚合图层并添加到地图

const clusterLayer = new ol.layer.Vector({
  source: clusterSource,
  style: getClusterStyle
});

map.addLayer(clusterLayer);

到这一步，一个基础的 OpenLayers点聚合效果就完成了。缩放地图时，近距离点会自动合并或拆分。

步骤七：点击聚合点查看原始点信息

实际业务中，用户点击聚合点后通常需要知道里面包含哪些原始点。可以通过 forEachFeatureAtPixel 获取点击位置的聚合 Feature。

map.on('singleclick', function (evt) {
  map.forEachFeatureAtPixel(evt.pixel, function (feature) {
    const clusteredFeatures = feature.get('features');
    const count = clusteredFeatures.length;

    if (count === 1) {
      const originalFeature = clusteredFeatures[0];
      console.log('单点名称：', originalFeature.get('name'));
      console.log('单点ID：', originalFeature.get('id'));
    } else {
      console.log('这是一个聚合点，包含数量：', count);

      clusteredFeatures.forEach(function (item) {
        console.log(item.get('id'), item.get('name'));
      });
    }
  });
});

这段逻辑是 OpenLayers点聚合交互的重点：点击的不是原始 Feature，而是 ClusterSource 生成的聚合 Feature。必须先通过 feature.get('features') 拿到原始点数组。

步骤八：点击聚合点自动放大

很多地图产品会在用户点击聚合点时自动放大到该聚合范围。可以计算聚合中所有原始点的范围，然后调用 view.fit。

map.on('singleclick', function (evt) {
  map.forEachFeatureAtPixel(evt.pixel, function (feature) {
    const clusteredFeatures = feature.get('features');

    if (clusteredFeatures.length > 1) {
      const extent = ol.extent.createEmpty();

      clusteredFeatures.forEach(function (item) {
        ol.extent.extend(extent, item.getGeometry().getExtent());
      });

      map.getView().fit(extent, {
        duration: 300,
        padding: [60, 60, 60, 60],
        maxZoom: 17
      });
    }
  });
});

如果聚合点中的原始点坐标完全相同，范围可能非常小，这时 fit 后看起来变化不明显。可以结合弹窗列表或蜘蛛展开效果处理重叠点。

常见坑：OpenLayers点聚合不显示或效果不对

坑一：坐标没有转换到地图投影

如果你的点数据是经纬度，比如 [116.391, 39.907]，而地图视图使用的是 EPSG:3857，必须进行投影转换。

const point = new ol.geom.Point(
  ol.proj.fromLonLat([116.391, 39.907])
);

如果忘记转换，点可能显示在错误位置，甚至看起来像“点聚合不生效”。

坑二：把 ClusterSource 和 VectorSource 混用

聚合图层的 source 应该是 clusterSource，不是原始 vectorSource。

const clusterLayer = new ol.layer.Vector({
  source: clusterSource,
  style: getClusterStyle
});

如果图层仍然使用 vectorSource，地图只会显示原始点，不会产生聚合效果。

坑三：不知道 features 属性的含义

聚合 Feature 的 features 属性不是普通字符串，也不是数量，而是原始 Feature 数组。数量应该这样取：

const size = feature.get('features').length;

很多点击查询失败，都是因为直接从聚合 Feature 上读取业务字段，例如 feature.get('name')。正确做法是先进入 features 数组，再读取原始点属性。

坑四：distance 设置过大或过小

distance 设置太小，点位仍然密密麻麻；设置太大，明明相隔较远的点也会被聚合。一般可以从 30 到 60 像素之间试起，再根据业务地图比例尺调整。

坑五：海量点直接一次性加载到前端

OpenLayers点聚合能改善渲染效果，但它不是万能的数据库优化方案。如果一次性向浏览器加载几十万点，网络传输、JSON 解析和内存占用仍然会成为瓶颈。

点数特别大时，建议结合后端瓦片化、矢量瓦片、服务端聚合或按视图范围分页加载。

方法比较：OpenLayers点聚合、热力图和服务端聚合怎么选

方法	适合场景	优点	限制
OpenLayers前端点聚合	几千到数万点的交互展示	实现简单，交互灵活，可读取原始点属性	数据量过大时前端压力明显
热力图	展示空间密度趋势	视觉直观，适合表达热点区域	不适合查看单个点属性和精确数量
服务端聚合	几十万到百万级点数据	减少前端数据传输，性能更稳定	后端实现复杂，需要按比例尺或网格聚合
矢量瓦片	大范围、多层级点数据发布	适合高性能 WebGIS 平台	数据生产和样式管理成本更高

如果你的项目刚开始做点位上图，优先使用 OpenLayers点聚合是比较稳妥的；如果数据规模持续增长，再考虑服务端聚合或矢量瓦片。

检查清单：实现OpenLayers点聚合前后要确认什么

• 原始点坐标是否与地图投影一致，是否需要 fromLonLat 转换。
• 聚合图层使用的 source 是否为 ol.source.Cluster。
• ClusterSource 中的 source 是否指向原始 VectorSource。
• 样式函数中是否通过 feature.get('features').length 获取聚合数量。
• 点击事件中是否先取出 features 数组，再读取原始点属性。
• distance 是否根据地图显示效果调整到合适范围。
• 是否对样式对象做了缓存，避免频繁创建样式影响性能。
• 数据量是否过大，是否需要后端分页、按范围加载或服务端聚合。

FAQ：OpenLayers点聚合常见问题

OpenLayers点聚合的 distance 单位是什么？

distance 的单位是屏幕像素，不是米，也不是经纬度。它表示屏幕上两个点距离小于多少像素时可以被聚合。因此同一个 distance 值，在不同缩放级别下会产生不同聚合结果。

OpenLayers点聚合后还能获取原始点属性吗？

可以。聚合 Feature 的 features 属性保存了原始 Feature 数组。单点时数组长度为 1，聚合点时数组长度大于 1。业务属性需要从数组中的原始 Feature 上读取。

OpenLayers点聚合适合十万级点数据吗？

不建议无条件把十万级点一次性加载到前端。虽然 OpenLayers点聚合能减少视觉拥挤，但无法消除网络传输、浏览器内存和 JSON 解析成本。十万级以上数据应优先考虑服务端聚合、矢量瓦片或按当前视图范围加载。

为什么点聚合后所有点都显示成一个大圆？

常见原因是 distance 设置过大，或者地图当前缩放级别太小。可以减小 distance，或者限制初始 zoom，让点在更合适的比例尺下展示。

为什么点击聚合点取不到 name 字段？

因为点击到的是聚合 Feature，不是原始点 Feature。不要直接写 feature.get('name')，而应先写 feature.get('features')，再从数组中的原始 Feature 读取 name。

结论：掌握 source、cluster、style 三层逻辑即可

OpenLayers点聚合的实现并不复杂，核心就是三层逻辑：原始点放在 VectorSource，聚合规则放在 ClusterSource，显示效果放在 VectorLayer 的样式函数中。

真正容易出错的地方不是代码行数，而是没有理解聚合 Feature 与原始 Feature 的关系。只要记住 feature.get('features') 这个关键入口，就能正确处理聚合数量、点击查询、弹窗展示和自动放大。

对于普通 WebGIS 点位展示，前端 OpenLayers点聚合已经能覆盖大多数需求；对于更大规模的数据，应尽早把聚合计算、范围过滤或瓦片化能力放到服务端，避免浏览器承担过重的数据处理压力。