Leaflet.markercluster 中文文档 V1.5.4_leaflet中文文档

Leaflet.markercluster

对 Leaflet 库的标记（Marker）聚合提供美化的JS库。

最低支持 Leaflet 1.0.0 版本

写在翻译前

最近正好在用leaflet的这个插件 搜了一下，用的人不少，但是好像没人翻译过文档，就顺手处理下。

以下内容中，原文的Cluster本意为群、组，考虑其代码中的作用，为方便理解文档，以下统称聚合点。如有翻译错误，请在评论区指出，确认后我会及时修改。本文翻译时间为2022年7月21日，对应插件github版本为1.5.4。

修订记录：
2022.7.21 修正了文档中的锚点链接，以及部分外链指向leaflet中文网。
2022.10.18 修正了文档中部分外链指向最新版本的leaflet中文网。

如何使用本插件

在你的页面的leaflet库引入处之后，引入本插件的css及js文件。你可以选择如下几种引入方式：

译者注：此处存疑，虽然本文档写于1.5.4版本，但是项目中此处的链接写的就是1.4.1版本，请自行处理版本问题，如有争议，本文作者概不负责。

• 直接下载 v1.4.1 版本
• 使用unpkg的CDN: https://unpkg.com/leaflet.markercluster@1.4.1/dist/
• 通过npm命令安装: npm install leaflet.markercluster

对应自身情况,请斟酌引用 dist 目录下的文件:

• MarkerCluster.css
• MarkerCluster.Default.css (如果你要使用自定义的iconCreateFunction而不是默认的函数，则不需要引入)
• leaflet.markercluster.js (或者引入未压缩版本 leaflet.markercluster-src.js )

构建，测试及lint 脚本指令

安装 jake npm install -g jake 之后执行指令 npm install

• 想检查代码错误或者从源码构建leaflet，请运行 jake.
• 如果想运行测试，请执行 jake test.

范例

相关用法请参考范例

真实地图范例 是一个好的参考, 它用到了聚合点功能的所有默认配置.

或者参考 自定义范例 是如何自定义聚合点的样式和行为

用法

创建一个新的 标记聚合组（ MarkerClusterGroup）, 把你的标记添加进去, 然后将其添加到地图层中。

var markers = L.markerClusterGroup();
markers.addLayer(L.marker(getRandomLatLng(map)));
//此处省略，添加其他标记等 
map.addLayer(markers);
1
2
3
4

选项

默认配置

聚合点（Clusterer）将会开启下列好用的默认设置项：

• showCoverageOnHover: 当你的鼠标经过一个聚合点时，会显示他包含的标记围成的范围。

• zoomToBoundsOnClick: 当你点击一个聚合点时，会快捷缩放至一个其对应范围适合显示的zoom级别。

• spiderfyOnMaxZoom: 当你在最大缩放级别点击一个聚合点时，我们会将其蜘蛛化，以便你能看到其包含的所有标记。 (标注: 如果聚合点内的所有内容在最大的缩放级别或在 disableClusteringAtZoom 选项指定的缩放级别上仍有聚合点，则在当前缩放级别上进行蜘蛛化)

• removeOutsideVisibleBounds: 如果聚合点及标记处于你的显示区域外，则出于性能考虑将其从地图上移除。

• spiderLegPolylineOptions: 允许定义一个给蜘蛛脚一个多边形选项 PolylineOptions，默认情况下是 { weight: 1.5, color: '#222', opacity: 0.5 }.

你可以在创建MarkerClusterGroup时，你可以根据喜好禁用上述选项：

var markers = L.markerClusterGroup({
	spiderfyOnMaxZoom: false,
	showCoverageOnHover: false,
	zoomToBoundsOnClick: false
});
1
2
3
4
5

自定义聚合的标记

作为MarkerClusterGroup的一个选项，你可以定义你自己的函数来创建已聚合的标记的图标。
默认的实现方式是根据聚合数量判断，在10和100这两个边界值改变颜色，如果需要其他的使用方式，则需要自行定义。
如果你使用这种方式的话，则不需要引入MarkerCluster.Default.css文件。
方法会默认传入一个聚合点的实例对象，你可以通过 getChildCount() 或者 getAllChildMarkers()方法获取数据来计算和控制图标的展示。

var markers = L.markerClusterGroup({
	iconCreateFunction: function(cluster) {
		return L.divIcon({ html: '<b>' + cluster.getChildCount() + '</b>' });
	}
});
1
2
3
4
5

可以参考这个 自定义范例。

如果你需要更新聚合点的图标（例如一些和现实时间数据相关的标记）,可以使用refreshClusters()方法。

自定义蜘蛛状标记样式及位置

你也可以定义一个自定义函数，使用MarkerClusterGroup的spiderfyShapePositions选项来覆盖蜘蛛化图形的位置信息。下面的例子实现了一个呈线性的蜘蛛化方案，覆盖了默认的圆形方案。

var markers = L.markerClusterGroup({
	spiderfyShapePositions: function(count, centerPt) {
                var distanceFromCenter = 35,
                    markerDistance = 45,
                    lineLength = markerDistance * (count - 1),
                    lineStart = centerPt.y - lineLength / 2,
                    res = [],
                    i;
                res.length = count;
                for (i = count - 1; i >= 0; i--) {
                    res[i] = new Point(centerPt.x + distanceFromCenter, lineStart + markerDistance * i);
                }
                return res;
            }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

所有的配置项

默认开启的选项 (boolean类型)

• showCoverageOnHover:当你的鼠标经过一个聚合点时，会显示他包含的标记围成的范围。
• zoomToBoundsOnClick: 当你点击一个聚合点时，会快捷缩放至一个其对应范围适合显示的zoom级别。
• spiderfyOnMaxZoom: 当你在最大缩放级别点击一个聚合点时，我们会将其蜘蛛化，以便你能看到其包含的所有标记。 (标注: 如果聚合点内的所有内容在最大的缩放级别或在 disableClusteringAtZoom 选项指定的缩放级别上仍有聚合点，则在当前缩放级别上进行蜘蛛化)
• removeOutsideVisibleBounds: 如果聚合点及标记处于你的显示区域外，则出于性能考虑将其从地图上移除。
• animate: 当地图缩放或显示蜘蛛化的过程中，平滑的拆分/合并聚合点的子项。如果 L.DomUtil.TRANSITION为false，则该选项的值不会产生任何影响（即没有动画过渡效果）

其他选项

• animateAddingMarkers: 如果设置为true (animate 选项也需要设置为true)，在MarkerClusterGroup被添加到地图上之后，如果将单个标记添加到MarkerClusterGroup中，则也会添加动画并聚合。默认是false，因为这样会获得更好的性能表现。不支持使用 addLayers 批量添加标记, 只支持通过 addLayer单个添加标记。
• disableClusteringAtZoom: 如果设置，在指定缩放级别以及更高级别，标记将不会被聚合。默认是禁用的。 参考范例. （标注: 当你使用disableClusteringAtZoom时，你可能会对 spiderfyOnMaxZoom 选项感兴趣。）
• maxClusterRadius: 一个聚合点的最大影响半径（单位为像素px），默认值是80。减小这个值，将可能会产生更多数值小的聚合点 。你也可以定义一个函数，根据当前地图的缩放等级，返回一个单位为像素的聚合点最大影响半径。
• polygonOptions: 这个选项通过创建一个多边形L.Polygon(points, options) ，来显示一个聚合点的边界。默认为空，则leaflet会使用 默认路径选项.
• singleMarkerMode:如果设置为true，所有的标记的图标将会被覆盖，并且为同一尺寸。（标注: 标记本身不会被聚合点的实例对象替换，仅仅是图标被覆盖，因此，他们仍然对正常的事件有反应，选项 disableClusteringAtZoom并不能恢复他们之前的图标。 (查阅 issue#391).）
• spiderLegPolylineOptions: 允许你自定义 PolylineOptions 来改变蜘蛛腿的样式， 默认样式是 { weight: 1.5, color: '#222', opacity: 0.5 }.
• spiderfyDistanceMultiplier: 从1开始增加，以此增加蜘蛛化的标记距离中心点的距离。如果你使用较大的标记图标，请使用这个选项。默认值为1。
• iconCreateFunction:可定义一个函数去创建聚合点的图标。 参考 默认实现 或者 自定义范例.
• spiderfyShapePositions: 可定义一个函数去覆盖蜘蛛化图形的位置信息。
• clusterPane: 聚合点的图标将被添加到指定图层，默认则是添加到leaflet地图的标记所在图层 参考范例.

批量添加图层的配置项

这些选项用于使用 addLayers 方法的情况. 详见 issue#357 是如何解释批量处理的运作方式。

• chunkedLoading: Boolean类型的值，用于将 addLayers 的处理流程拆分成小间隔时间去处理，这样页面不会看起来静止不动。
• chunkInterval: 每个addLayers任务开始前，为了缓解页面性能压力所设置的时间间隔，单位为毫秒（ms）。这样做，一定程度上可以防止在添加大量标记的时候，页面陷入未响应状态。默认值是200（ms）。
• chunkDelay: 在连续处理 addLayers任务期间设置的时间延迟（单位为毫秒）。默认值为50（ms）。
• chunkProgress: 每一个chunkInterval结束后会调用此参数绑定的回调方法，通常被用于显示进度，例如 现实地图加载5万个标记，默认值为空，其回调参数为:
  1. 已处理完成的标记数量
  2. 总共要被添加的标记数量
  3. 已经消耗的时间 (单位：毫秒)
  4. 译者注：此项存疑，官方文档没写，但是官方范例中有此入参，推测为本批次添加的layer的数组，未实践

事件

Leaflet事件，类似 click, mouseover 等等，只要能绑定在标记上的，都能添加到聚合点上。
如果只需要聚合点触发的事件，请监听 'cluster' + '<eventName>' 事件, 例如: clusterclick, clustermouseover, clustermouseout.

你可以像下边这些例子一样，去给事件绑定回调方法：

markers.on('click', function (a) {
	console.log('marker ' + a.layer);
});
markers.on('clusterclick', function (a) {
	// a.layer 实际上是一个聚合点
	console.log('cluster ' + a.layer.getAllChildMarkers().length);
});
1
2
3
4
5
6
7

MarkerClusterGroup的其余事件

• animationend: 标记聚合或者取消聚合的动画完成时触发
• spiderfied: 当重叠的标记完成蜘蛛化时触发 (包含cluster和markers属性)
• unspiderfied: 当重叠的标记取消蜘蛛化时触发 (包含cluster和markers属性)

方法

MarkerClusterGroup的方法

新增或删除标记

支持addLayer, removeLayer 和clearLayers 的使用，它们应该能满足大多数场景下的使用。

批量添加或删除标记

addLayers and removeLayers 是用于批量添加或删除标记的方法，在批量添加或删除标记时，应当优于逐个添加。 每次使用都需要一个标记汇总的数组。你可以使用 专用选项 来微调 addLayers 的行为。

这些方法可以从图层组类型的数据中提取出非组的图层子对象，即使是深度嵌套的数据也可以。然而，需要注意的是：

• chunkProgress在addLayers找到一个组的时候进度会向后跳跃（因为将其子层追加到输入数组中会使总数增加）。
• 组实际上没有被添加到MarkerClusterGroup中，渲染图层内只有它们的非组子层。因此，map对象的hasLayer方法对非组的子层将返回true，但对任何（可能是父对象）层组类型都会返回false。

如果你想删除很多标记，几乎可以肯定，先调用clearLayers，再调用addLayers，将你不想删除的标记加回去会更好，详见 issue#59 。

获取一个标记可见的父对象

如果你在MarkerClusterGroup中拥有一个标记，并且你想获得它的可见父对象（要么是它自己，要么是它在地图上包含它的当前可见的聚合点），你可以这么做：

var visibleOne = markerClusterGroup.getVisibleParent(myMarker);
console.log(visibleOne.getLatLng());
1
2

但是需要注意，如果标记或包含它的聚合点目前不可见（即它们不在可见的视点附近），这个方法会返回null。

刷新聚合点的图标

如果你已经 自定义 了聚合点的图标，并且使用了其包含的标记的一些数据，如果后来这些数据发生了变化，则可以使用这个方法可以强制刷新聚合点的图标。
对于这个方法你可以使用下列用法:

• 不传入参数，则会强制重绘该MarkerClusterGroup的所有聚合点的图标。
• 传入一个数组或者一个类似map的对象，则只重绘这些标记归属的聚合点。
• 传入一个层组（L.LayerGroup）对象，这个方法将遍历其包含的所有标记。请确保该层组（L.LayerGroup）对象只包含标记，并且同时也在MarkerClusterGroup之中。
• 传入一个单独的标记。

markers.refreshClusters();
markers.refreshClusters([myMarker0, myMarker33]);
markers.refreshClusters({id_0: myMarker0, id_any: myMarker33});
markers.refreshClusters(myLayerGroup);
markers.refreshClusters(myMarker);
1
2
3
4
5

本插件还给标记（L.Marker）上添加了一个方法refreshIconOptions，以便更新其图标选项或者刷新图标样式。
如果第二个参数传入"true"，该方法也将触发对该标记从属的聚合点的 refreshCluster。

// Use as many times as required to update markers,
// then call refreshClusters once finished.
for (i in markersSubArray) {
	markersSubArray[i].refreshIconOptions(newOptionsMappingArray[i]);
}
markers.refreshClusters(markersSubArray);
// If updating only one marker, pass true to
// refresh this marker's parent clusters right away.
myMarker.refreshIconOptions(optionsMap, true); 
1
2
3
4
5
6
7
8
9

MarkerClusterGroup的其余方法

• hasLayer(layer): 如果该MarkerClusterGroup中包含传入的layer对象（标记）则返回true，否则返回false。
• zoomToShowLayer(layer, callback): 会自动缩放地图，以合适的大小去显示传入的layer对象（标记），如有必要，还会对其蜘蛛化。第二个参数则可以绑定一个回调方法，当标记在地图上可见时调用。

聚合点的方法

以下方法可用于聚合点（而不是MarkerClusterGroup），它们通常用于事件处理。

获取一个聚合点的影响范围

当你接收到一个聚合点的事件后，你就可以通过如下方式获取其边界范围。

markers.on('clusterclick', function (a) {
	var latLngBounds = a.layer.getBounds();
});
1
2
3

你同样也可以查询边界并构造一个凸多边形。
详见范例 example/marker-clustering-convexhull.html

markers.on('clusterclick', function (a) {
	map.addLayer(L.polygon(a.layer.getConvexHull()));
});
1
2
3

缩放到一个聚合点的影响范围

当你接收到一个聚合点的事件时，你可以通过一个简单的步骤中缩放地图到符合它的边界大小。
如果所有的标记都将在一个更高的缩放级别出现，那么地图的缩放级别会被其替代。
zoomToBounds 可以传入一个可选的参数 该选项会对 fitBounds 产生调用

详见范例 marker-clustering-zoomtobounds.html

markers.on('clusterclick', function (a) {
	a.layer.zoomToBounds({padding: [20, 20]});
});
1
2
3

聚合点的其余方法

• getChildCount: 返回该聚合点中包含的标记总数。
• getAllChildMarkers(storage: array | undefined, ignoreDraggedMarker: boolean | undefined): 返回一个包含了此聚合点中所有标记的数组（如果传入了storage参数，则会使用该数组）。如果ignoreDraggedMarker设置为true，并且当前有一个标记刚好被拖动过，那么被拖动的标记将不会被包含在数组中。
• spiderfy: 蜘蛛化这个聚合点的子标记
• unspiderfy: 取消蜘蛛化这个聚合点的子标记 (与 spiderfy 方法相反)

处理大量的标记

该插件可以处理10,000 甚至 50,000 个标记 (在chrome浏览器下). IE9 在 50,000 数量下会存在一些问题。

• 真实地图 10,000 标记案例
• 真实地图 50,000 标记案例

标注: 这两个例子都将 chunkedLoading 选项设置为了true，以避免浏览器长时间陷入假死状态

授权

Leaflet.markercluster 是一个免费的软件, 可以在遵守MIT协议下重新发布。

子插件

Leaflet.markercluster插件很受欢迎。因此，有了一些更高或者不一样的期望，希望增加一些功能。

如果你是这种情况，请一定要先看一下资料库 issues，也许你要找的东西已经被讨论过了，而且还提出了一些解决方法。

请先查看下面的子插件：