Clustering de marcadores

Selecionar plataforma: Android iOS JavaScript

Visão geral

Neste tutorial, falamos sobre como usar os clusters de marcadores para mostrar um grande número de marcadores em um mapa. Você pode usar a biblioteca@googlemaps/markerclusterer com a API Maps JavaScript para combinar e transformar marcadores de proximidade em clusters e simplificar a exibição de marcadores no mapa.

Para saber como o clustering de marcadores funciona, confira o mapa a seguir.

O número em um grupo indica quantos marcadores ele contém. Quando o zoom em qualquer um dos locais do grupo aumenta, o número no grupo diminui e você começa a ver os marcadores individuais no mapa. Afastar o zoom do mapa consolida os marcadores novamente em grupos.

O exemplo a seguir mostra o código completo necessário para criar esse mapa.

TypeScript

import { MarkerClusterer } from '@googlemaps/markerclusterer';

async function init() {
    // Request needed libraries.
    const [{ InfoWindow }, { AdvancedMarkerElement, PinElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
        ]);

    const mapElement =
        document.querySelector<google.maps.MapElement>('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const infoWindow = new 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 PinElement({
            glyphText: label,
            glyphColor: 'white',
        });

        const marker = new AdvancedMarkerElement({
            position,
            content: pinGlyph,
            gmpClickable: true,
        });

        // markers can only be keyboard focusable when they have click listeners
        // open info window when marker is clicked
        marker.addEventListener('gmp-click', () => {
            const content = document.createElement('div');
            content.textContent = `${String(position.lat)}, ${String(position.lng)}`;
            infoWindow.setContent(content);

            infoWindow.open({
                anchor: marker,
                map: innerMap,
            });
        });
        return marker;
    });

    // Add a marker clusterer to manage the markers.
    new MarkerClusterer({ markers, map: innerMap });
}

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 },
];

void init();
index.ts

Observação: acesse o guia sobre como usar o TypeScript e o Google Maps.

JavaScript

import { MarkerClusterer } from '@googlemaps/markerclusterer';

async function init() {
    // Request needed libraries.
    const [{ InfoWindow }, { AdvancedMarkerElement, PinElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
        ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const infoWindow = new 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 PinElement({
            glyphText: label,
            glyphColor: 'white',
        });

        const marker = new AdvancedMarkerElement({
            position,
            content: pinGlyph,
            gmpClickable: true,
        });

        // markers can only be keyboard focusable when they have click listeners
        // open info window when marker is clicked
        marker.addEventListener('gmp-click', () => {
            const content = document.createElement('div');
            content.textContent = `${String(position.lat)}, ${String(position.lng)}`;
            infoWindow.setContent(content);

            infoWindow.open({
                anchor: marker,
                map: innerMap,
            });
        });
        return marker;
    });

    // Add a marker clusterer to manage the markers.
    new MarkerClusterer({ markers, map: innerMap });
}

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 },
];

void init();
index.js

CSS

html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}
style.css

HTML

<html>
    <head>
        <title>Marker Clustering</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY",
            });
        </script>
    </head>
    <body>
        <gmp-map
            center="-28.024,140.887"
            zoom="3"
            map-id="DEMO_MAP_ID"></gmp-map>
    </body>
</html>
index.html

Como ilustração, este tutorial adiciona um conjunto de marcadores ao mapa usando a matriz locations. Você pode usar outras fontes para obter marcadores para o mapa. Se quiser mais informações, acesse o guia sobre como criar marcadores.

Adicionar um clusterer de marcadores

Siga estas etapas para adicionar um clusterer de marcadores:

1. Adicione a biblioteca de clustering de marcadores à sua página ou aplicativo. A biblioteca está disponível no NPM em @googlemaps/markerclusterer e no repositório do GitHub (links em inglês). Selecione uma das seguintes opções para instalar a biblioteca:

   NPM

   Instale a biblioteca @googlemaps/markerclusterer usando o NPM.

   npm install @googlemaps/markerclusterer

   CDN

   O script a seguir carrega a biblioteca da CDN em unpkg.com (link em inglês).

   <script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>

2. Adicione um clusterer de marcadores ao app.

   O código a seguir adiciona um clusterer de marcadores ao mapa. Selecione uma das opções abaixo:

   NPM

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

   CDN

   Quando acessada com a CDN, a biblioteca fica disponível no markerClusterer global.

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

   Este exemplo transmite a matriz markers ao MarkerClusterer.

3. (Opcional) Personalize o clusterer de marcadores para mudar a aparência do ícone do cluster, o algoritmo de clustering ou o comportamento de clique.

Personalizar o clusterer de marcadores

É possível personalizar o MarkerClusterer transmitindo outras opções no MarkerClustererOptions objeto ao criar a instância do clusterer:

• renderer: controla como os marcadores de cluster são renderizados no mapa.
• algorithm e algorithmOptions: controla como os marcadores são agrupados em clusters com base na distância e no nível de zoom.
• onClusterClick: substitui o comportamento padrão quando um usuário clica em um marcador de cluster.

O mapa a seguir mostra marcadores com ícones de cluster personalizados.

Personalizar o ícone do cluster

Por padrão, MarkerClusterer usa DefaultRenderer para criar ícones de cluster SVG. Para personalizar a aparência dos marcadores de cluster, transmita um objeto que implementa a Renderer interface para a renderer opção.

A interface Renderer requer um método render(cluster, stats, map) que retorna um AdvancedMarkerElement (ou um google.maps.Marker legado). O método render recebe os seguintes argumentos:

• cluster (Cluster): Representa o grupo de marcadores, incluindo:
  • count: o número de marcadores visíveis no cluster.
  • position: a posição central google.maps.LatLng do cluster.
  • bounds: o google.maps.LatLngBounds do cluster.
  • markers: a matriz de marcadores contidos no cluster.
• stats (ClusterStats): fornece estatísticas em todos os clusters no ciclo de renderização atual, como stats.clusters.markers.mean, min, max, e sum. É possível usar esses valores para estilizar clusters dinamicamente com base no tamanho relativo deles.
• map (google.maps.Map): a instância do mapa.

O exemplo a seguir define um renderer personalizado que cria um selo HTML circular para cada AdvancedMarkerElement e muda a cor de plano de fundo quando a contagem de marcadores de cluster excede o tamanho médio do cluster.

TypeScript

// Customize the cluster icons using a custom Renderer
    const renderer = {
        render: (
            {
                count,
                position,
            }: { count: number; position: google.maps.LatLng },
            stats: ClusterStats
        ) => {
            // Change color based on the number of markers in the cluster relative to the mean
            const isLargeCluster =
                count > Math.max(10, stats.clusters.markers.mean);
            const clusterClass = isLargeCluster
                ? 'large-cluster'
                : 'small-cluster';

            // Build the HTML content for the Advanced Marker
            const content = document.createElement('div');
            content.classList.add('custom-cluster-icon', clusterClass);
            content.textContent = String(count);

            return new AdvancedMarkerElement({
                position,
                content,
                // Adjust zIndex to be above other markers
                zIndex: 1000 + count,
            });
        },
    };

    // Add a marker clusterer to manage the markers.
    new MarkerClusterer({ markers, map: innerMap, renderer });
}
index.ts

Observação: acesse o guia sobre como usar o TypeScript e o Google Maps.

JavaScript

// Customize the cluster icons using a custom Renderer
    const renderer = {
        render: ({ count, position }, stats) => {
            // Change color based on the number of markers in the cluster relative to the mean
            const isLargeCluster =
                count > Math.max(10, stats.clusters.markers.mean);
            const clusterClass = isLargeCluster
                ? 'large-cluster'
                : 'small-cluster';

            // Build the HTML content for the Advanced Marker
            const content = document.createElement('div');
            content.classList.add('custom-cluster-icon', clusterClass);
            content.textContent = String(count);

            return new AdvancedMarkerElement({
                position,
                content,
                // Adjust zIndex to be above other markers
                zIndex: 1000 + count,
            });
        },
    };

    // Add a marker clusterer to manage the markers.
    new MarkerClusterer({ markers, map: innerMap, renderer });
}
index.js

Confira o exemplo completo de renderizador personalizado

TypeScript

import { MarkerClusterer, ClusterStats } from '@googlemaps/markerclusterer';

async function init() {
    // Request needed libraries.
    const [{ InfoWindow }, { AdvancedMarkerElement, PinElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
        ]);

    await customElements.whenDefined('gmp-map');

    const mapElement =
        document.querySelector<google.maps.MapElement>('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const infoWindow = new 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 PinElement({
            glyphText: label,
            glyphColor: 'white',
        });

        const marker = new AdvancedMarkerElement({
            position,
            content: pinGlyph,
            gmpClickable: true,
        });

        marker.addEventListener('gmp-click', () => {
            const content = document.createElement('div');
            content.textContent = `${String(position.lat)}, ${String(position.lng)}`;
            infoWindow.setContent(content);

            infoWindow.open({
                anchor: marker,
                map: innerMap,
            });
        });
        return marker;
    });

    // Customize the cluster icons using a custom Renderer
    const renderer = {
        render: (
            {
                count,
                position,
            }: { count: number; position: google.maps.LatLng },
            stats: ClusterStats
        ) => {
            // Change color based on the number of markers in the cluster relative to the mean
            const isLargeCluster =
                count > Math.max(10, stats.clusters.markers.mean);
            const clusterClass = isLargeCluster
                ? 'large-cluster'
                : 'small-cluster';

            // Build the HTML content for the Advanced Marker
            const content = document.createElement('div');
            content.classList.add('custom-cluster-icon', clusterClass);
            content.textContent = String(count);

            return new AdvancedMarkerElement({
                position,
                content,
                // Adjust zIndex to be above other markers
                zIndex: 1000 + count,
            });
        },
    };

    // Add a marker clusterer to manage the markers.
    new MarkerClusterer({ markers, map: innerMap, renderer });
}

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 },
];

void init();
index.ts

Observação: acesse o guia sobre como usar o TypeScript e o Google Maps.

JavaScript

import { MarkerClusterer } from '@googlemaps/markerclusterer';

async function init() {
    // Request needed libraries.
    const [{ InfoWindow }, { AdvancedMarkerElement, PinElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
        ]);

    await customElements.whenDefined('gmp-map');

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const infoWindow = new 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 PinElement({
            glyphText: label,
            glyphColor: 'white',
        });

        const marker = new AdvancedMarkerElement({
            position,
            content: pinGlyph,
            gmpClickable: true,
        });

        marker.addEventListener('gmp-click', () => {
            const content = document.createElement('div');
            content.textContent = `${String(position.lat)}, ${String(position.lng)}`;
            infoWindow.setContent(content);

            infoWindow.open({
                anchor: marker,
                map: innerMap,
            });
        });
        return marker;
    });

    // Customize the cluster icons using a custom Renderer
    const renderer = {
        render: ({ count, position }, stats) => {
            // Change color based on the number of markers in the cluster relative to the mean
            const isLargeCluster =
                count > Math.max(10, stats.clusters.markers.mean);
            const clusterClass = isLargeCluster
                ? 'large-cluster'
                : 'small-cluster';

            // Build the HTML content for the Advanced Marker
            const content = document.createElement('div');
            content.classList.add('custom-cluster-icon', clusterClass);
            content.textContent = String(count);

            return new AdvancedMarkerElement({
                position,
                content,
                // Adjust zIndex to be above other markers
                zIndex: 1000 + count,
            });
        },
    };

    // Add a marker clusterer to manage the markers.
    new MarkerClusterer({ markers, map: innerMap, renderer });
}

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 },
];

void init();
index.js

CSS

html,
body,
gmp-map {
    height: 100%;
    margin: 0;
    padding: 0;
}

.custom-cluster-icon {
    width: 45px;
    height: 45px;
    border-radius: 50%;
    border: 2px solid white;
    display: flex;
    justify-content: center;
    align-items: center;
    color: white;
    font-weight: bold;
    font-size: 14px;
    font-family: sans-serif;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
}

.large-cluster {
    background-color: #ff0000;
}

.small-cluster {
    background-color: #0000ff;
}
style.css

HTML

<html>
    <head>
        <title>marker-clustering-custom</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map
            center="-28.024, 140.887"
            zoom="3"
            map-id="DEMO_MAP_ID"></gmp-map>
    </body>
</html>
index.html

Para outros exemplos de renderizador, consulte a demonstração de uso do renderizador.

Modificar o algoritmo de clustering

Por padrão, MarkerClusterer usa SuperClusterAlgorithm, que agrupa marcadores usando árvores k-d. É possível personalizar o comportamento de clustering transmitindo uma instância de algoritmo para a algorithm opção ou transmitindo opções para o algoritmo padrão para algorithmOptions.

A biblioteca inclui os seguintes algoritmos integrados:

• SuperClusterAlgorithm (padrão): clustering de pontos geoespaciais rápido usando árvores k-d. As opções comuns incluem:
  • maxZoom: o nível máximo de zoom em que os clusters são gerados (padrão: 16). Em níveis de zoom acima de maxZoom, os marcadores individuais são exibidos sem clustering.
  • radius: o raio do cluster em pixels (padrão: 60).
  • minPoints: o número mínimo de marcadores necessários para formar um cluster (padrão: 2).
• SuperClusterViewportAlgorithm: Uma variante filtrada pela janela de visualização de SuperClusterAlgorithm que agrupa apenas marcadores na janela de visualização do mapa atual, além de um preenchimento de pixels (viewportPadding, padrão: 60).
• GridAlgorithm: Um algoritmo de clustering baseado em grade. As opções comuns incluem maxZoom (padrão: 16), gridSize (tamanho da grade em pixels, padrão: 40) e maxDistance (distância máxima em metros entre um centro de cluster e um marcador, padrão: 40000).
• NoopAlgorithm: renderiza todos os marcadores sem agrupá-los.

O exemplo a seguir configura SuperClusterAlgorithm com um radius e maxZoom personalizados:

import {MarkerClusterer, SuperClusterAlgorithm} from '@googlemaps/markerclusterer';

const markerCluster = new MarkerClusterer({
  map,
  markers,
  algorithm: new SuperClusterAlgorithm({
    radius: 80,
    maxZoom: 15,
  }),
});

Para comparar o comportamento dos diferentes algoritmos, consulte a demonstração de comparação de algoritmos.

Personalizar o comportamento de clique do cluster

Por padrão, clicar em um marcador de cluster ajusta a janela de visualização do mapa aos limites do cluster clicado (map.fitBounds(cluster.bounds)). Para personalizar o que acontece quando um usuário clica em um cluster, transmita uma função de callback para a onClusterClick opção:

const markerCluster = new MarkerClusterer({
  map,
  markers,
  onClusterClick: (event, cluster, map) => {
    // Zoom in by 2 levels centered on the cluster position
    map.setCenter(cluster.position);
    map.setZoom((map.getZoom() ?? 3) + 2);
  },
});

Saiba mais

Confira exemplos mais complexos de clustering de marcadores no repositório do GitHub e na documentação de referência da biblioteca (links em inglês).