Agrupación de marcadores en clústeres

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.
Seleccionar plataforma: Android iOS JavaScript

Descripción general

En este instructivo se muestra la manera de usar clústeres de marcadores para mostrar una gran cantidad de marcadores en un mapa. Puedes usar la biblioteca @googlemaps/markerclusterer en combinación con la API de Maps JavaScript para combinar marcadores cercanos en clústeres y simplificar la visualización de marcadores en el mapa.

Para ver la manera en que funciona la agrupación de marcadores, observa el mapa a continuación.

El número de un clúster indica la cantidad de marcadores que contiene. Ten en cuenta que, a medida que te acercas a cualquiera de las ubicaciones del clúster, el número del clúster disminuye y comienzas a ver los marcadores individuales en el mapa. Al aplicar zoom de alejamiento al mapa, los marcadores se consolidarán nuevamente en clústeres.

En el siguiente ejemplo, se muestra el código completo que necesitas para crear este mapa.

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
     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>

Probar la muestra

A modo de ilustración simple, en este instructivo se agrega un conjunto de marcadores al mapa con el arreglo locations. Puedes usar otras fuentes a fin de obtener recursos para tu mapa. Para obtener más información, lee la guía sobre cómo crear marcadores.

Agregar un agrupador de marcadores en clústeres

Sigue los pasos que se indican a continuación para agregar un agrupador de marcadores en clústeres:

  1. Agrega la biblioteca de agrupación de marcadores en clústeres a tu página o aplicación. La biblioteca está disponible en NPM en @googlemaps/markerclusterer y en el repositorio en GitHub.

    Administración de socios de red

    Instala la versión más reciente de la biblioteca @googlemaps/markerclusterer con NPM.

    npm install @googlemaps/markerclusterer

    CDN

    La secuencia de comandos a continuación carga la última versión 1.x.x de la biblioteca desde la CDN unpkg.com.

    <script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
  2. Agrega un agrupador de marcadores en clústeres a tu app.

    El siguiente código agrega un agrupador de marcadores en clústeres al mapa.

    Administración de socios de red

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

    CDN

    Cuando se accede con la CDN, la biblioteca está disponible en el markerClusterer global.

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

    En este ejemplo, se pasa el arreglo markers a MarkerClusterer.

  3. Personaliza el agrupador de marcadores en clústeres.

Más información

Puedes ver ejemplos más complejos de agrupamiento de marcadores en clústeres en el repositorio en GitHub y leer la documentación de referencia para la biblioteca.