MapConductor문서 / 확장 기능 / 마커 클러스터링
마커를 대량으로 놓기
근접한 마커를 자동으로 클러스터로 묶고, 줌인하면 펼칩니다. 어느 프로바이더의 지도 뷰에서도 같은 코드로 동작합니다.
ANDROID
com.mapconductor:marker-clustering
iOS
MapConductorMarkerCluster
REACT
@mapconductor/react-marker-clustering
01 · 설치
app/build.gradle.kts
implementation("com.mapconductor:marker-clustering")Package.swift
.package(url: "https://github.com/MapConductor/ios-marker-cluster", from: "1.3.1"), .product(name: "MapConductorMarkerCluster", package: "ios-marker-cluster"),
terminal
npm install @mapconductor/react-marker-clustering
02 · 사용법
마커의 배열을 클러스터 그룹에 넘기기만 하면 됩니다. 마커 자체의 상태 객체는 통상의 것과 같으며, 고쳐 쓸 필요가 없습니다.
ClusteredMap.kt · Jetpack Compose
val markerStates: List<MarkerState> = remember { buildMarkerList() }
val clusterState = remember {
MarkerClusterGroupState(
clusterRadiusPx = 90.0,
minClusterSize = 5,
onClusterClick = { cluster -> /* handle tap */ },
)
}
MapLibreMapView(state = mapState) {
MarkerClusterGroup(state = clusterState, markers = markerStates)
}ClusteredMap.swift · SwiftUI
@State private var clusterState = MarkerClusterGroupState(
clusterRadiusPx: 90,
minClusterSize: 5,
onClusterClick: { cluster in /* handle tap */ }
)
MapLibreMapView(state: mapState) {
MarkerClusterGroup(state: clusterState, markers: markerStates)
}ClusteredMap.tsx · React
import { MarkerClusterGroup } from '@mapconductor/react-marker-clustering';
import { MapLibreMapView2D, useMapLibreViewState } from '@mapconductor/react-for-maplibre';
<MapLibreMapView2D state={state}>
<MarkerClusterGroup
markers={markers}
minClusterSize={2}
clusterRadiusPx={80}
enableZoomAnimation
onClusterClick={cluster => console.log(cluster.count)}
/>
</MapLibreMapView2D>03 · 주요 옵션
Option
Default
설명
clusterRadiusPx
90.0
클러스터로 묶는 거리(화면 픽셀). 작게 하면 분할이 촘촘해집니다.
minClusterSize
3
클러스터로 표시할 최소 마커 수. 이 미만은 개별 마커인 채로 둡니다.
clusterIconProvider
circle badge
클러스터 수에 따른 아이콘을 반환합니다. 기본은 원형 배지.
onClusterClick
null
클러스터의 탭을 받습니다. 줌인에 쓰는 것이 일반적입니다.
enableZoomAnimation
false
줌 시의 전개・집약을 애니메이션하는 ON/OFF. 기본은 비활성. 소요 시간은 zoomAnimationDurationMs(기본 300ms)로 조정합니다.
04 · 성능
수천 개라도 매끄럽게
클러스터링은 백그라운드에서 계산하고, 카메라가 멈췄을 때만 재구성합니다.
SAMPLE
24,526