개요
이 튜토리얼에서는 마커 클러스터를 사용하여 지도에 많은 수의 마커를 표시하는 방법을 설명합니다. @googlemaps/Markerclusterer 라이브러리를 Maps JavaScript API와 함께 사용하면 가까이 있는 마커를 클러스터로 결합하고 지도상에 마커를 간단하게 표시할 수 있습니다.
마커 클러스터링의 작동 방식을 보려면 아래 지도를 참고하세요.
클러스터의 숫자는 클러스터에 포함된 마커의 수를 나타냅니다. 클러스터 위치를 확대하면 클러스터의 숫자가 감소하고 지도에 개별 마커가 표시되기 시작합니다. 지도를 축소하면 마커가 클러스터로 다시 통합됩니다.
아래 샘플은 이 지도를 만드는 데 필요한 전체 코드를 보여줍니다.
TypeScript
function initMap(): void {
const map = new google.maps.Map(
document.getElementById("map") as HTMLElement,
{
zoom: 3,
center: { lat: -28.024, lng: 140.887 },
}
);
const infoWindow = new google.maps.InfoWindow({
content: "",
disableAutoPan: true,
});
// Create an array of alphabetical characters used to label the markers.
const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
// Add some markers to the map.
const markers = locations.map((position, i) => {
const label = labels[i % labels.length];
const marker = new google.maps.Marker({
position,
label,
});
// markers can only be keyboard focusable when they have click listeners
// open info window when marker is clicked
marker.addListener("click", () => {
infoWindow.setContent(label);
infoWindow.open(map, marker);
});
return marker;
});
// Add a marker clusterer to manage the markers.
new MarkerClusterer({ markers, map });
}
const locations = [
{ lat: -31.56391, lng: 147.154312 },
{ lat: -33.718234, lng: 150.363181 },
{ lat: -33.727111, lng: 150.371124 },
{ lat: -33.848588, lng: 151.209834 },
{ lat: -33.851702, lng: 151.216968 },
{ lat: -34.671264, lng: 150.863657 },
{ lat: -35.304724, lng: 148.662905 },
{ lat: -36.817685, lng: 175.699196 },
{ lat: -36.828611, lng: 175.790222 },
{ lat: -37.75, lng: 145.116667 },
{ lat: -37.759859, lng: 145.128708 },
{ lat: -37.765015, lng: 145.133858 },
{ lat: -37.770104, lng: 145.143299 },
{ lat: -37.7737, lng: 145.145187 },
{ lat: -37.774785, lng: 145.137978 },
{ lat: -37.819616, lng: 144.968119 },
{ lat: -38.330766, lng: 144.695692 },
{ lat: -39.927193, lng: 175.053218 },
{ lat: -41.330162, lng: 174.865694 },
{ lat: -42.734358, lng: 147.439506 },
{ lat: -42.734358, lng: 147.501315 },
{ lat: -42.735258, lng: 147.438 },
{ lat: -43.999792, lng: 170.463352 },
];
declare global {
interface Window {
initMap: () => void;
}
}
window.initMap = initMap;
JavaScript
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
zoom: 3,
center: { lat: -28.024, lng: 140.887 },
});
const infoWindow = new google.maps.InfoWindow({
content: "",
disableAutoPan: true,
});
// Create an array of alphabetical characters used to label the markers.
const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
// Add some markers to the map.
const markers = locations.map((position, i) => {
const label = labels[i % labels.length];
const marker = new google.maps.Marker({
position,
label,
});
// markers can only be keyboard focusable when they have click listeners
// open info window when marker is clicked
marker.addListener("click", () => {
infoWindow.setContent(label);
infoWindow.open(map, marker);
});
return marker;
});
// Add a marker clusterer to manage the markers.
new MarkerClusterer({ markers, map });
}
const locations = [
{ lat: -31.56391, lng: 147.154312 },
{ lat: -33.718234, lng: 150.363181 },
{ lat: -33.727111, lng: 150.371124 },
{ lat: -33.848588, lng: 151.209834 },
{ lat: -33.851702, lng: 151.216968 },
{ lat: -34.671264, lng: 150.863657 },
{ lat: -35.304724, lng: 148.662905 },
{ lat: -36.817685, lng: 175.699196 },
{ lat: -36.828611, lng: 175.790222 },
{ lat: -37.75, lng: 145.116667 },
{ lat: -37.759859, lng: 145.128708 },
{ lat: -37.765015, lng: 145.133858 },
{ lat: -37.770104, lng: 145.143299 },
{ lat: -37.7737, lng: 145.145187 },
{ lat: -37.774785, lng: 145.137978 },
{ lat: -37.819616, lng: 144.968119 },
{ lat: -38.330766, lng: 144.695692 },
{ lat: -39.927193, lng: 175.053218 },
{ lat: -41.330162, lng: 174.865694 },
{ lat: -42.734358, lng: 147.439506 },
{ lat: -42.734358, lng: 147.501315 },
{ lat: -42.735258, lng: 147.438 },
{ lat: -43.999792, lng: 170.463352 },
];
window.initMap = initMap;
CSS
/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
#map {
height: 100%;
}
/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
HTML
<html>
<head>
<title>Marker Clustering</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<div id="map"></div>
<!--
The `defer` attribute causes the callback to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises.
See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
defer
></script>
</body>
</html>
샘플 사용해 보기
편의상 이 튜토리얼에서는 locations 배열을 사용하여 지도에 마커 집합을 추가합니다. 실제로는 다른 소스도 사용 가능합니다.
자세한 내용은 마커 만들기 가이드를 참고하세요.
마커 클러스터러 추가
마커 클러스터러를 추가하려면 아래 단계를 따르세요.
- 페이지 또는 애플리케이션에 마커 클러스터링 라이브러리를 추가합니다. 라이브러리는 NPM(@googlemaps/Markerclusterer) 및 GitHub 저장소에 제공됩니다.
NPM
NPM을 사용하여 @googlemaps/Markerclusterer 라이브러리의 최신 버전을 설치합니다.
npm install @googlemaps/markerclusterer
CDN
아래 스크립트는 unpkg.com CDN에서 라이브러리의 최신 1.xx 버전을 로드합니다.
<script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
- 앱에 마커 클러스터러를 추가합니다.
아래 코드는 지도에 마커 클러스터러를 추가합니다.
NPM
import { MarkerClusterer } from "@googlemaps/markerclusterer"; const markerCluster = new MarkerClusterer({ map, markers });CDN
CDN을 사용하여 액세스하는 경우
markerClusterer전역에서 라이브러리를 사용할 수 있습니다.const markerCluster = new markerClusterer.MarkerClusterer({ map, markers });이 샘플은
markers배열을MarkerClusterer에 전달합니다. - 마커 클러스터러를 맞춤설정합니다.
- 렌더기 인터페이스를 통해 클러스터 아이콘을 맞춤설정합니다.
- 클러스터를 생성하기 위한 알고리즘을 수정합니다.
자세히 알아보기
GitHub 저장소에서 마커 클러스터링의 더 복잡한 예를 확인하고 라이브러리에 대한 참조 문서를 읽어 보세요.