数据可视化数据分析GIS【免费下载链接】foliumPython Data. Leaflet.js Maps.项目地址https://gitcode.com/gh_mirrors/fo/folium点击查看免费下载OverlappingMarkerSpiderfier是 folium 中用于解决标记点重叠问题的官方插件当多个Marker在地图上重合或距离过近时点击它们会以蜘蛛腿spider legs般的圆形或螺旋形向外展开让每个标记变得可单独点击。本文围绕官方指南docs/user_guide/plugins/overlapping_marker_spiderfier.md中的三种集成方式展开并结合插件源码深入讲解参数原理与底层工作流程读完即可在普通地图、FeatureGroup与FeatureGroupSubGroup分层结构中正确接入该插件。插件是什么解决什么痛点在 Leaflet 地图上当大量标记点集中在同一经纬度附近例如相同位置的多次上报、聚合的 POI 数据时标记会彼此遮挡用户很难点中某个具体标记。OverlappingMarkerSpiderfier缩写 OMS的解决方案是点击重叠区域后把聚集的标记按蜘蛛形状向四周展开——数量少时排成圆环circle数量多时切换为螺旋spiral——并绘制连接线蜘蛛腿指向每个标记的原始位置点击其他空白处后标记再收回原位。folium 对该插件的封装位于 folium/plugins/overlapping_marker_spiderfier.py其类定义如下class OverlappingMarkerSpiderfier(JSCSSMixin, MacroElement):它继承自JSCSSMixin负责注入 JS 资源与MacroElement负责渲染自定义 JavaScript 模板。插件本身不会自动生成标记而是通过递归遍历地图上的子元素把已有的Marker实例收集起来统一托管因此无需为插件单独注册标记。该类已在 folium/plugins/init.py 中导出直接from folium.plugins import OverlappingMarkerSpiderfier即可使用。构造参数与默认值插件构造函数定义于 folium/plugins/overlapping_marker_spiderfier.py全部参数均为可选参数类型默认值含义keep_spiderfiedboolTrue点击展开后是否保持蜘蛛化状态为False时点击空白处即收回nearby_distanceint20判定重叠的像素距离阈值两个标记相距不超过该像素数即视为重叠leg_weightfloat1.5蜘蛛腿连接线的粗细像素circle_spiral_switchoverint9从圆形布局切换为螺旋布局的标记数量阈值**kwargs——透传给底层 Leaflet 插件的其他选项参数通过parse_options()统一解析后存入self.options在渲染时会以 JSON 形式传给前端OverlappingMarkerSpiderfier构造函数见 folium/plugins/overlapping_marker_spiderfier.pyvar oms new OverlappingMarkerSpiderfier( {{ this._parent.get_name() }}, {{ this.options|tojson }} );小提示官方示例见下文中使用了circle_spiral_switchover10、leg_weight2.0等非默认值这是为了演示效果更明显若不加参数插件会使用源码中的默认值leg_weight1.5、circle_spiral_switchover9。与普通 Marker 配合使用官方指南给出的最基础用法是先向地图添加一批位置相近的Marker再把插件add_to(m)即可。以下为完整示例原样保留自官方文档import folium from folium.plugins import OverlappingMarkerSpiderfier # Create a map m folium.Map(location[45.05, 3.05], zoom_start13) # Add markers to the map for i in range(20): folium.Marker( location[45.05 i * 0.0001, 3.05 i * 0.0001], popupfMarker {i} ).add_to(m) # Add the OverlappingMarkerSpiderfier plugin oms OverlappingMarkerSpiderfier( keep_spiderfiedTrue, # Markers remain spiderfied after clicking nearby_distance20, # Distance for clustering markers in pixel circle_spiral_switchover10, # Threshold for switching between circle and spiral leg_weight2.0 # Line thickness for spider legs ) oms.add_to(m) m代码中 20 个标记的经纬度每次仅递增0.0001度在zoom_start13级别下会大面积重叠。nearby_distance20表示相距 20 像素以内的标记会被视为一组由于标记总数20超过circle_spiral_switchover10点击后将直接呈现螺旋展开形态。从源码看add_to的执行逻辑folium/plugins/overlapping_marker_spiderfier.py会先记录父元素再调用_get_all_markers递归收集地图下所有直接或间接的Markerdef add_to(self, parent, nameNone, indexNone): self._parent parent self.markers self._get_all_markers(parent) return super().add_to(parent, namename, indexindex)_get_all_markersfolium/plugins/overlapping_marker_spiderfier.py遍历_children凡是Marker实例直接收集凡是还拥有_children的容器元素则递归深入。这意味着插件必须在地图上的标记全部添加完成之后再add_to(m)否则后添加的标记不会被收集。收集到的标记会在渲染模板中逐一注册folium/plugins/overlapping_marker_spiderfier.py{%- for marker in this.markers %} oms.addMarker({{ marker.get_name() }}); {%- endfor %}此外模板中还内置了事件监听folium/plugins/overlapping_marker_spiderfier.py每次触发spiderfy蜘蛛化时自动调用closePopup()关闭其他弹出的气泡避免多个 popup 同时遮挡地图oms.addListener(spiderfy, function() { {{ this._parent.get_name() }}.closePopup(); });与 FeatureGroup 配合使用当标记数量较多时推荐先用FeatureGroup分组管理可配合LayerControl统一开关整组。官方指南示例import folium from folium.plugins import OverlappingMarkerSpiderfier # Create a map m folium.Map(location[45.05, 3.05], zoom_start13) # Create a FeatureGroup feature_group folium.FeatureGroup(nameFeature Group) # Add markers to the FeatureGroup for i in range(10): folium.Marker( location[45.05 i * 0.0001, 3.05 i * 0.0001], popupfFeature Group Marker {i} ).add_to(feature_group) # Add the FeatureGroup to the map feature_group.add_to(m) # Initialize OverlappingMarkerSpiderfier oms OverlappingMarkerSpiderfier() oms.add_to(m) m这里的FeatureGroup定义于 folium/map.py本身是一个可容纳子元素的Layer因此_get_all_markers会递归穿过FeatureGroup找到其内部的全部Marker并注册给 OMS。注意插件应先添加到地图这样父元素地图才能作为递归收集的起点示例中OverlappingMarkerSpiderfier()未传任何参数全部使用源码默认值keep_spiderfiedTrue、nearby_distance20、leg_weight1.5、circle_spiral_switchover910 个标记未超过默认阈值9实际上恰好达到切换边界若想强制圆形布局可把circle_spiral_switchover调大例如circle_spiral_switchover20。与 FeatureGroupSubGroup 配合使用多层分组当需要在一张地图上呈现多类数据例如类型 A 的点与类型 B 的点分开展示、独立开关时官方指南推荐使用FeatureGroupSubGroup建立嵌套分组结构。完整示例import folium from folium.plugins import OverlappingMarkerSpiderfier, FeatureGroupSubGroup # Create a map m folium.Map(location[45.05, 3.05], zoom_start13) # Create a main FeatureGroup main_group folium.FeatureGroup(nameMain Group) # Create sub-groups sub_group1 FeatureGroupSubGroup(main_group, nameSub Group 1) sub_group2 FeatureGroupSubGroup(main_group, nameSub Group 2) # Add markers to the first sub-group for i in range(10): folium.Marker( location[45.05 i * 0.0001, 3.05 i * 0.0001], popupfSub Group 1 Marker {i} ).add_to(sub_group1) # Add markers to the second sub-group for i in range(10, 20): folium.Marker( location[45.06 (i - 10) * 0.0001, 3.06 (i - 10) * 0.0001], popupfSub Group 2 Marker {i} ).add_to(sub_group2) # Add the main group to the map main_group.add_to(m) # Add sub-groups to the map sub_group1.add_to(m) sub_group2.add_to(m) # Initialize OverlappingMarkerSpiderfier oms OverlappingMarkerSpiderfier() oms.add_to(m) # Add the LayerControl plugin folium.LayerControl().add_to(m) mFeatureGroupSubGroup定义于 folium/plugins/feature_group_sub_group.py它实现了 Leaflet.FeatureGroup.SubGroup 的封装核心特性是把子元素挂载到其所属的group此处为main_group下从而形成主组—子组的层级。其构造参数为FeatureGroupSubGroup(group, nameNone, overlayTrue, controlTrue, showTrue)group所属的父级Layer如FeatureGroup或MarkerCluster必填name在LayerControl中显示的名称overlay作为叠加层复选框还是底图单选框control是否出现在LayerControl中。本示例的关键结构是两个sub_group的标记分别集中在地图两块区域45.05, 3.05与45.06, 3.06每块内部自重叠。由于两个子组都挂在main_group之下并且main_group、sub_group1、sub_group2均被add_to(m)OMS 的递归收集可以同时覆盖两层嵌套的标记。LayerControl则提供界面上独立勾选Sub Group 1 / Sub Group 2的能力与蜘蛛化展开互不冲突——子组内重叠标记被点击时spiderfy事件仍会正常触发并关闭 popup。源码级运行机制小结综合 folium/plugins/overlapping_marker_spiderfier.py 的实现插件在浏览器端的工作流程可概括为资源加载default_js声明从 CDN 引入OverlappingMarkerSpiderfier-Leaflet/0.2.6/oms.min.js见 folium/plugins/overlapping_marker_spiderfier.py实例化渲染时以地图对象与序列化后的optionskeep_spiderfied、nearby_distance、leg_weight、circle_spiral_switchover等构造前端插件实例注册标记遍历_get_all_markers收集到的Marker逐个调用oms.addMarker()事件绑定监听spiderfy事件展开时自动closePopup()交互展开点击重叠标记时插件依据nearby_distance判定重叠组依据circle_spiral_switchover决定圆环或螺旋布局用leg_weight粗细的连线指向原位置点击地图空白处标记按keep_spiderfied的取值决定是否收回。该插件的集成行为在 tests/plugins/test_overlapping_marker_spiderfier.py 中有自动化测试覆盖可作为验证自身用法的参照test_oms_js_inclusion断言渲染结果中包含oms.min.js的script标签用于验证 CDN 资源正常注入test_marker_addition随机生成 10 个标记并add_to(m)断言地图子元素数量正确对应标记收集的前提条件test_map_bounds验证地图边界正确覆盖所有标记坐标保证点击交互区域不被裁切test_overlapping_marker_spiderfier_integration断言插件实例成功注册进地图的_children对应add_to(m)调用链的完整性。常见使用要点先加标记后加插件add_to时即完成标记收集之后再添加的标记不在托管范围内如标记为动态加载可在加载完成后重新add_to或按需刷新。多层嵌套均可识别_get_all_markers会递归遍历所有拥有_children的容器FeatureGroup、FeatureGroupSubGroup、MarkerCluster等因此嵌套分组下无需额外操作。参数按需调整nearby_distance过小会导致重叠组判定不足、依旧难以点选circle_spiral_switchover决定展开形态的视觉观感leg_weight影响连线可见性建议结合地图缩放级别实测调整。与 LayerControl 搭配配合 folium 的 LayerControl 使用可同时获得分组显隐与重叠展开两种能力。赞分享数据可视化数据分析GIS【免费下载链接】foliumPython Data. Leaflet.js Maps.项目地址https://gitcode.com/gh_mirrors/fo/folium点击查看免费下载相关推荐folium 插件指南MarkerCluster 与 FastMarkerCluster 海量标记点聚合实战folium 插件指南MarkerCluster 与 FastMarkerCluster 海量标记点聚合实战 导读 当一张地图上需要展示数百、数千乃至上万个标数据可视化数据分析GIS终极Leaflet.markercluster事件处理指南从点击交互到蜘蛛化的完整实现终极Leaflet.markercluster事件处理指南从点击交互到蜘蛛化的完整实现 Leaflet.markercluster是一款强大的Leaflet插前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
