中文文档 V1.5.4"/>
Leaflet.markercluster 中文文档 V1.5.4
文档目录
- Leaflet.markercluster
- 写在翻译前
- 如何使用本插件
- 构建,测试及lint 脚本指令
- 范例
- 用法
- 选项
- 默认配置
- 自定义聚合的标记
- 自定义蜘蛛状标记样式及位置
- 所有的配置项
- 默认开启的选项 (boolean类型)
- 其他选项
- 批量添加图层的配置项
- 事件
- MarkerClusterGroup的其余事件
- 方法
- MarkerClusterGroup的方法
- 新增或删除标记
- 批量添加或删除标记
- 获取一个标记可见的父对象
- 刷新聚合点的图标
- MarkerClusterGroup的其余方法
- 聚合点的方法
- 获取一个聚合点的影响范围
- 缩放到一个聚合点的影响范围
- 聚合点的其余方法
- 处理大量的标记
- 授权
- 子插件
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:
.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);
选项
默认配置
聚合点(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
});
自定义聚合的标记
作为MarkerClusterGroup的一个选项,你可以定义你自己的函数来创建已聚合的标记的图标。
默认的实现方式是根据聚合数量判断,在10和100这两个边界值改变颜色,如果需要其他的使用方式,则需要自行定义。
如果你使用这种方式的话,则不需要引入MarkerCluster.Default.css
文件。
方法会默认传入一个聚合点的实例对象,你可以通过 getChildCount()
或者 getAllChildMarkers()
方法获取数据来计算和控制图标的展示。
var markers = L.markerClusterGroup({iconCreateFunction: function(cluster) {return L.divIcon({ html: '<b>' + cluster.getChildCount() + '</b>' });}
});
可以参考这个 自定义范例。
如果你需要更新聚合点的图标(例如一些和现实时间数据相关的标记),可以使用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;}
});
所有的配置项
默认开启的选项 (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万个标记,默认值为空,其回调参数为:- 已处理完成的标记数量
- 总共要被添加的标记数量
- 已经消耗的时间 (单位:毫秒)
- 译者注:此项存疑,官方文档没写,但是官方范例中有此入参,推测为本批次添加的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);
});
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());
但是需要注意,如果标记或包含它的聚合点目前不可见(即它们不在可见的视点附近),这个方法会返回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);
本插件还给标记(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);
MarkerClusterGroup的其余方法
- hasLayer(layer): 如果该MarkerClusterGroup中包含传入的layer对象(标记)则返回true,否则返回false。
- zoomToShowLayer(layer, callback): 会自动缩放地图,以合适的大小去显示传入的layer对象(标记),如有必要,还会对其蜘蛛化。第二个参数则可以绑定一个回调方法,当标记在地图上可见时调用。
聚合点的方法
以下方法可用于聚合点(而不是MarkerClusterGroup),它们通常用于事件处理。
获取一个聚合点的影响范围
当你接收到一个聚合点的事件后,你就可以通过如下方式获取其边界范围。
markers.on('clusterclick', function (a) {var latLngBounds = a.layer.getBounds();
});
你同样也可以查询边界并构造一个凸多边形。
详见范例 example/marker-clustering-convexhull.html
markers.on('clusterclick', function (a) {map.addLayer(L.polygon(a.layer.getConvexHull()));
});
缩放到一个聚合点的影响范围
当你接收到一个聚合点的事件时,你可以通过一个简单的步骤中缩放地图到符合它的边界大小。
如果所有的标记都将在一个更高的缩放级别出现,那么地图的缩放级别会被其替代。
zoomToBounds
可以传入一个可选的参数 该选项会对 fitBounds
产生调用
详见范例 marker-clustering-zoomtobounds.html
markers.on('clusterclick', function (a) {a.layer.zoomToBounds({padding: [20, 20]});
});
聚合点的其余方法
- 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,也许你要找的东西已经被讨论过了,而且还提出了一些解决方法。
请先查看下面的子插件:
插件 | 描述 | 维护者 |
---|---|---|
Leaflet.FeatureGroup.SubGroup | 被在添加到地图上时创建一个要素组,将其子层添加到父组中(例如通过L.Control.Layers)。典型的用法是动态地从聚合点中添加/删除 编组的标记。 | ghybs |
Leaflet.MarkerCluster.LayerSupport | 带来了与L.Control.Layers和其他Leaflet插件的兼容性。也就是说,所有对象使用直接调用map.addLayer和map.removeLayer。 | ghybs |
Leaflet.MarkerCluster.Freezable | 增加了在指定的缩放比例下冻结聚合点的能力。例如,在maxZoom + 1处冻结,就像在程序上禁用聚合功能一样。 | ghybs |
Leaflet.MarkerCluster.PlacementStrategies | 实现新的策略来定位被聚合的标记(例如:时钟、同心圆…)。推荐与circleMarkers一起使用。 Demo | adammertel / UNIVIE |
Leaflet.MarkerCluster.List | 将子元素显示在一个列表中,适用于移动设备。Demo | adammertel / UNIVIE |
更多推荐
Leaflet.markercluster 中文文档 V1.5.4
发布评论