마커 클러스터링

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
플랫폼 선택: Android iOS 자바스크립트

개요

이 튜토리얼은 마커 클러스터를 사용하여 수많은 마커를 지도에 표시하는 방법을 보여줍니다. @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;

자바스크립트

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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>

샘플 사용해 보기

간단한 그림으로, 이 튜토리얼에서는 locations 배열을 사용하여 지도에 마커 집합을 추가합니다. 다른 소스를 사용하여 지도에 대한 마커를 가져올 수 있습니다. 자세한 내용은 마커 만들기 가이드를 참고하세요.

마커 클러스터러 추가

아래 단계에 따라 마커 클러스터러를 추가합니다.

  1. 페이지 또는 애플리케이션에 마커 클러스터링 라이브러리를 추가합니다. 라이브러리는 NPM(@googlemaps/Markerclusterer) 및 GitHub 저장소에서 확인할 수 있습니다.

    NPM

    NPM을 사용하여 최신 버전의 @googlemaps/Markerclusterer 라이브러리를 설치합니다.

    npm install @googlemaps/markerclusterer

    CDN

    아래 스크립트는 unpkg.com CDN에서 라이브러리의 최신 1.x.x 버전을 로드합니다.

    <script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
  2. 앱에 마커 클러스터러를 추가합니다.

    아래 코드는 마커 클러스터러를 지도에 추가합니다.

    NPM

    import { MarkerClusterer } from "@googlemaps/markerclusterer";
    
    const markerCluster = new MarkerClusterer({ map, markers });

    CDN

    CDN을 통해 액세스하면 라이브러리는 markerClusterer 전역에서 사용할 수 있습니다.

    const markerCluster = new markerClusterer.MarkerClusterer({ map, markers });

    이 샘플은 markers 배열을 MarkerClusterer에 전달합니다.

  3. 마커 클러스터러를 맞춤설정합니다.

자세히 알아보기

GitHub 저장소에서 마커 클러스터링의 더 복잡한 예를 확인하고 라이브러리에 대한 참조 문서를 읽어 보세요.