Descripción general
En este instructivo, se muestra cómo usar clústeres de marcadores para mostrar una gran cantidad de marcadores en un mapa. Puedes utilizar la biblioteca @googlemaps/markerclusterer junto 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 cómo funciona el agrupamiento de marcadores en clústeres, observa el siguiente mapa.
El número de un clúster indica la cantidad de marcadores que contiene. Ten en cuenta que, a medida que hagas zoom en cualquiera de las ubicaciones del clúster, el número correspondiente disminuirá, y empezarás a ver los marcadores individuales en el mapa. Cuando te alejes del 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
async function initMap() {
// Request needed libraries.
const { Map, InfoWindow } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;
const map = new google.maps.Map(
document.getElementById("map") as HTMLElement,
{
zoom: 3,
center: { lat: -28.024, lng: 140.887 },
mapId: 'DEMO_MAP_ID',
}
);
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 pinGlyph = new google.maps.marker.PinElement({
glyph: label,
glyphColor: "white",
})
const marker = new google.maps.marker.AdvancedMarkerElement({
position,
content: pinGlyph.element,
});
// markers can only be keyboard focusable when they have click listeners
// open info window when marker is clicked
marker.addListener("click", () => {
infoWindow.setContent(position.lat + ", " + position.lng);
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 },
];
initMap();
JavaScript
async function initMap() {
// Request needed libraries.
const { Map, InfoWindow } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary(
"marker",
);
const map = new google.maps.Map(document.getElementById("map"), {
zoom: 3,
center: { lat: -28.024, lng: 140.887 },
mapId: "DEMO_MAP_ID",
});
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 pinGlyph = new google.maps.marker.PinElement({
glyph: label,
glyphColor: "white",
});
const marker = new google.maps.marker.AdvancedMarkerElement({
position,
content: pinGlyph.element,
});
// markers can only be keyboard focusable when they have click listeners
// open info window when marker is clicked
marker.addListener("click", () => {
infoWindow.setContent(position.lat + ", " + position.lng);
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 },
];
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>
<!-- prettier-ignore -->
<script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
</body>
</html>
Prueba la muestra
Para brindarte una ilustración simple, en este instructivo, se agrega un conjunto de marcadores al mapa mediante el array locations. Puedes usar otras fuentes a fin de obtener marcadores para tu mapa.
Para obtener más información, lee la guía sobre cómo crear marcadores.
Cómo 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:
- Agrega la biblioteca de agrupamiento 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 de GitHub.
NPM
Instala la versión más reciente de la biblioteca @googlemaps/markerclusterer con NPM.
npm install @googlemaps/markerclusterer
CDN
La secuencia de comandos que se indica a continuación carga la última versión 1.x.x de la biblioteca desde la CDN de unpkg.com.
<script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
- 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.
NPM
import { MarkerClusterer } from "@googlemaps/markerclusterer"; const markerCluster = new MarkerClusterer({ markers, map });CDN
Cuando se accede con la CDN, la biblioteca está disponible en el
markerClustererglobal.const markerCluster = new markerClusterer.MarkerClusterer({ markers, map });En este ejemplo, se pasa el array
markersaMarkerClusterer. - Personaliza el agrupador de marcadores en clústeres.
- Personaliza el ícono de clúster en la interfaz del procesador.
- Modifica el algoritmo para generar clústeres.
Más información
Puedes ver ejemplos más complejos sobre el agrupamiento de marcadores en clústeres en el repositorio de GitHub y leer la documentación de referencia de la biblioteca.