Clustering de marcadores

Selecione a plataforma: Android iOS JavaScript

Nesta página, descrevemos o utilitário de clustering de marcadores disponível na biblioteca de utilitários do SDK do Maps para iOS.

Com o clustering de marcadores, você pode colocar um grande número de marcadores em um mapa sem dificultar a leitura. O utilitário de clustering de marcadores ajuda a gerenciar vários marcadores em diferentes níveis de zoom.

Quando um usuário vê um mapa com bastante zoom, os marcadores individuais aparecem no mapa. Quando o usuário diminui o zoom, os marcadores se reúnem em clusters, facilitando a visualização.

A captura de tela a seguir mostra o estilo padrão dos clusters de marcadores:

Um mapa com marcadores agrupados no estilo padrão

Abaixo está um exemplo de clusters de marcadores personalizados:

Mapa com marcadores em cluster personalizados

Pré-requisitos e observações

Biblioteca de utilitários do SDK do Maps para iOS

O utilitário de clustering de marcadores faz parte da Biblioteca de utilitários do SDK do Maps para iOS. Se você ainda não configurou a biblioteca, siga o guia antes de ler o restante desta página.

Para obter o melhor desempenho, o número máximo recomendado de marcadores é 10.000.

Permissão de localização

Este exemplo usa o GPS do dispositivo para localizar o usuário e o mapa nas coordenadas. Para ativar isso, adicione uma descrição à permissão NSLocationWhenInUseUsageDescription no arquivo Info.plist do projeto.

Para adicionar isso, faça o seguinte:

  1. Clique no arquivo Info.plist do Project Navigator no Xcode para abrir o editor de listas de propriedades.
  2. Clique no ícone '+' ao lado de 'Informações da lista de propriedades' para adicionar uma nova propriedade.
  3. No campo 'key', digite 'NSLocationWhenInUseUsageDescription'. O Xcode traduzirá isso automaticamente para o nome longo 'Privacidade - Localização quando estiver em uso Descrição' Para ver uma lista completa das possíveis propriedades de permissão de localização, consulte Solicitar solicitação de autorização de serviços de localização na documentação do desenvolvedor da Apple.
  4. Deixe o campo 'Type' definido como 'String'.
  5. No campo 'Valor' digite uma descrição do motivo pelo qual o aplicativo exige o uso da localização do usuário. Por exemplo, "Localiza o usuário para fornecer listas de empresas próximas."

Como implementar o clustering de marcadores

A implementação do clustering de marcadores requer três etapas:

  1. Criar uma instância do gerenciador de clusters.
  2. Transmitir os marcadores que você quer agrupar para o gerenciador de clusters
  3. Invoque o gerenciador de clusters.
Para ver um exemplo completo de como implementar o clustering de marcadores, confira os apps de exemplo no Objective-C e no Swift no GitHub (em inglês).

Como criar o gerenciador de cluster

Para usar o gerenciador de cluster, faça o seguinte:

  1. Defina o ViewController onde seu mapa é renderizado para estar de acordo com o protocolo GMSMapViewDelegate.
  2. Crie uma instância de GMUClusterManager.
  3. Transmita a instância de GMSMapView em que você quer implementar o clustering de marcadores e as implementações dos seguintes protocolos à instância GMUClusterManager:
    • GMUClusterIconGenerator: oferece uma lógica do aplicativo que busca os ícones do cluster a serem usados em diferentes níveis de zoom.
    • GMUClusterAlgorithm: especifica um algoritmo que determina o comportamento do modo como os marcadores são agrupados, como a distância entre os marcadores a serem incluídos no mesmo cluster.
    • GMUClusterRenderer: oferece uma lógica do aplicativo que processa a renderização real dos ícones de cluster no mapa.
  4. Defina o delegado de mapa na instância GMUClusterManager.

A biblioteca de utilitários inclui implementações padrão do gerador de ícones (GMUDefaultClusterIconGenerator), do algoritmo (GMUNonHierarchicalDistanceBasedAlgorithm) e do renderizador (GMUDefaultClusterRenderer). Como opção, você pode criar seu próprio generador, renderizador e algoritmo de ícone de restrição personalizados.

O código a seguir cria um gerenciador de cluster usando esses padrões no callback viewDidLoad de ViewController:

Swift

import GoogleMaps
import GoogleMapsUtils

class MarkerClustering: UIViewController, GMSMapViewDelegate {
  private var mapView: GMSMapView!
  private var clusterManager: GMUClusterManager!

  override func viewDidLoad() {
    super.viewDidLoad()

    // Set up the cluster manager with the supplied icon generator and
    // renderer.
    let iconGenerator = GMUDefaultClusterIconGenerator()
    let algorithm = GMUNonHierarchicalDistanceBasedAlgorithm()
    let renderer = GMUDefaultClusterRenderer(mapView: mapView,
                                clusterIconGenerator: iconGenerator)
    clusterManager = GMUClusterManager(map: mapView, algorithm: algorithm,
                                                      renderer: renderer)

    // Register self to listen to GMSMapViewDelegate events.
    clusterManager.setMapDelegate(self)
    // ...
  }
  // ...
}

Objective-C

@import GoogleMaps;
@import GoogleMapsUtils;

@interface MarkerClustering () <GMSMapViewDelegate>

@end

@implementation MarkerClustering {
  GMSMapView *_mapView;
  GMUClusterManager *_clusterManager;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // Set up the cluster manager with a supplied icon generator and renderer.
  id<GMUClusterAlgorithm> algorithm =
      [[GMUNonHierarchicalDistanceBasedAlgorithm alloc] init];
  id<GMUClusterIconGenerator> iconGenerator =
      [[GMUDefaultClusterIconGenerator alloc] init];
  id<GMUClusterRenderer> renderer =
      [[GMUDefaultClusterRenderer alloc] initWithMapView:_mapView
                                    clusterIconGenerator:iconGenerator];
  _clusterManager =
      [[GMUClusterManager alloc] initWithMap:_mapView
                                   algorithm:algorithm
                                    renderer:renderer];

  // Register self to listen to GMSMapViewDelegate events.
  [_clusterManager setMapDelegate:self];
  // ...
}
// ...
@end

Adicionar marcadores

Há duas maneiras de adicionar marcadores ao clustering de marcadores: individualmente ou como uma matriz.

Marcador individual

Swift

let position = CLLocationCoordinate2D(latitude: 47.60, longitude: -122.33)
let marker = GMSMarker(position: position)
clusterManager.add(marker)

Objective-C

CLLocationCoordinate2D position = CLLocationCoordinate2DMake(47.60, -122.33);
GMSMarker *marker = [GMSMarker markerWithPosition:position];
[_clusterManager addItem:marker];

Matriz de marcadores

Swift

let position1 = CLLocationCoordinate2D(latitude: 47.60, longitude: -122.33)
let marker1 = GMSMarker(position: position1)

let position2 = CLLocationCoordinate2D(latitude: 47.60, longitude: -122.46)
let marker2 = GMSMarker(position: position2)

let position3 = CLLocationCoordinate2D(latitude: 47.30, longitude: -122.46)
let marker3 = GMSMarker(position: position3)

let position4 = CLLocationCoordinate2D(latitude: 47.20, longitude: -122.23)
let marker4 = GMSMarker(position: position4)

let markerArray = [marker1, marker2, marker3, marker4]
clusterManager.add(markerArray)

Objective-C

CLLocationCoordinate2D position1 = CLLocationCoordinate2DMake(47.60, -122.33);
GMSMarker *marker1 = [GMSMarker markerWithPosition:position1];

CLLocationCoordinate2D position2 = CLLocationCoordinate2DMake(47.60, -122.46);
GMSMarker *marker2 = [GMSMarker markerWithPosition:position2];

CLLocationCoordinate2D position3 = CLLocationCoordinate2DMake(47.30, -122.46);
GMSMarker *marker3 = [GMSMarker markerWithPosition:position3];

CLLocationCoordinate2D position4 = CLLocationCoordinate2DMake(47.20, -122.23);
GMSMarker *marker4 = [GMSMarker markerWithPosition:position4];

NSArray<GMSMarker *> *markerArray = @[marker1, marker2, marker3, marker4];
[_clusterManager addItems:markerArray];

Como invocar o clustering de marcadores

Depois de criar o clustering de marcadores e transmitir os marcadores que você quer agrupar, basta chamar o método cluster na instância do clustering de marcadores.

Swift

clusterManager.cluster()

Objective-C

[_clusterManager cluster];

Tratamento de eventos em marcadores e grupos

Em geral, ao usar o SDK do Maps para iOS, você precisa implementar o protocolo GMSMapViewDelegate para detectar eventos no mapa. Você pode detectar eventos de mapa, mas não eventos de gerenciador de clusters com segurança de tipos. Quando o usuário toca em um marcador, um item individual de cluster ou um cluster, a API aciona mapView:didTapMarker: e anexa os dados de cluster extras à propriedade marker.userData. Você pode verificar se userData está em conformidade com o protocolo GMUCluster para determinar se um ícone de cluster ou um marcador foi tocado.

Swift

func mapView(_ mapView: GMSMapView, didTap marker: GMSMarker) -> Bool {
  // center the map on tapped marker
  mapView.animate(toLocation: marker.position)
  // check if a cluster icon was tapped
  if marker.userData is GMUCluster {
    // zoom in on tapped cluster
    mapView.animate(toZoom: mapView.camera.zoom + 1)
    NSLog("Did tap cluster")
    return true
  }

  NSLog("Did tap a normal marker")
  return false
}

Objective-C

- (BOOL)mapView:(GMSMapView *)mapView didTapMarker:(GMSMarker *)marker {
  // center the map on tapped marker
    [_mapView animateToLocation:marker.position];
    // check if a cluster icon was tapped
    if ([marker.userData conformsToProtocol:@protocol(GMUCluster)]) {
      // zoom in on tapped cluster
      [_mapView animateToZoom:_mapView.camera.zoom + 1];
      NSLog(@"Did tap cluster");
      return YES;
    }

    NSLog(@"Did tap marker in cluster");
    return NO;
}

O gerenciador de clusters agora intercepta todos os eventos que você implementou em clusterManager. Ele encaminha todos os eventos restantes ao delegado do mapa, se fornecido. Os eventos de marcadores padrão (ou seja, os marcadores não gerados pelo renderizador de cluster) são sempre encaminhados para o delegado de mapa.

Personalizar o clustering de marcadores

Você pode fornecer uma implementação personalizada para GMUClusterRenderer, GMUClusterIconGenerator ou GMUClusterAlgorithm. Você pode basear a implementação personalizada na implementação de amostra desses protocolos incluídos na biblioteca de utilitários ou programar uma implementação totalmente personalizada realizando os protocolos.