Agrupación de marcadores en clústeres

Seleccionar plataforma: Android iOS JavaScript

En esta página, se describe la utilidad de agrupación de marcadores disponible en la biblioteca de utilidades del SDK de Maps para iOS.

Cuando agrupas tus marcadores en clústeres, puedes incluir muchos marcadores en un mapa sin que esto dificulte su lectura. La utilidad del agrupamiento de marcadores en clústeres te ayuda a administrar varios marcadores con diferentes niveles de zoom.

Cuando un usuario visualiza el mapa con un alto nivel de zoom, aparecen los marcadores individuales. Cuando el usuario aleja el mapa, los marcadores se agrupan en clústeres para facilitar su visualización.

En la siguiente captura de pantalla se muestra el estilo predeterminado de los clústeres de marcadores:

Un mapa con marcadores agrupados en el estilo predeterminado

A continuación, se muestra un ejemplo de clústeres de marcadores personalizados:

Mapa con marcadores agrupados en clústeres personalizados

Requisitos previos y notas

Biblioteca de utilidades del SDK de Maps para iOS

La utilidad del agrupamiento de marcadores en clústeres forma parte de la biblioteca de utilidades del SDK de Maps para iOS. Si aún no configuraste la biblioteca, sigue la guía de configuración antes de leer el resto de esta página.

Para obtener el mejor rendimiento, la cantidad máxima de marcadores es de 10.000.

Permiso de ubicación

En este ejemplo, se usa el GPS del dispositivo para localizar al usuario y al mapa en sus coordenadas. Para habilitar esto, debes agregar una descripción al permiso NSLocationWhenInUseUsageDescription en el archivo Info.plist del proyecto.

Para agregar esta información, haz lo siguiente:

  1. Haz clic en el archivo Info.plist en el navegador de proyectos de Xcode para abrir el Editor de listas de propiedades.
  2. Haz clic en el ícono &+33; junto a 'Information Property List' para agregar una nueva propiedad.
  3. En el campo &key (clave) escribe &NS3WhenInUseUsageDescription'. Xcode traducirá esto automáticamente al nombre largo 'Privacidad - Ubicación en uso Descripción de uso'. Para obtener una lista completa de posibles propiedades de permisos de ubicación, consulta Solicitud de autorización para los Servicios de ubicación en la documentación para desarrolladores de Apple.
  4. Deja el campo &Type3 (tipo) en 'String'.
  5. En el campo "Valor", escribe una descripción del motivo por el cual tu app requiere el uso de la ubicación del usuario. Por ejemplo, "Encuentra al usuario en la lista de empresas cercanas".

Cómo implementar el agrupamiento de marcadores en clústeres

La implementación de la agrupación de marcadores en clústeres consta de tres pasos:

  1. Crea una instancia de administrador de clústeres.
  2. Pasa los marcadores que deseas agrupar al administrador de clústeres.
  3. Invoca el administrador de clústeres.
Para ver un ejemplo completo de cómo implementar el agrupamiento de marcadores en clústeres, consulta las apps de ejemplo de Objective-C y Swift en GitHub.

Crea el administrador de clústeres

Para usar el administrador de clústeres, haz lo siguiente:

  1. Configura el ViewController en el que se renderiza el mapa para cumplir con el protocolo GMSMapViewDelegate.
  2. Crea una instancia de GMUClusterManager.
  3. Pasa la instancia de GMSMapView en la que deseas implementar el agrupamiento de marcadores en clústeres y las implementaciones de los siguientes protocolos a la instancia GMUClusterManager:
    • GMUClusterIconGenerator: Proporciona una lógica de aplicación que obtiene los íconos del clúster para usarlos con diferentes niveles de zoom.
    • GMUClusterAlgorithm: Especifica un algoritmo que determina el comportamiento de la forma en que se agrupan los marcadores, como la distancia entre los marcadores que se incluirán en el mismo clúster.
    • GMUClusterRenderer: Proporciona una lógica de aplicación que controla la renderización real de los íconos de clúster en el mapa.
  4. Configura el delegado del mapa en la instancia GMUClusterManager.

La biblioteca de utilidades incluye implementaciones predeterminadas del generador de íconos (GMUDefaultClusterIconGenerator), del algoritmo (GMUNonHierarchicalDistanceBasedAlgorithm) y del procesador (GMUDefaultClusterRenderer). De forma opcional, puedes crear tu propio generador de íconos personalizados, algoritmo y procesador.

Con el siguiente código, se crea un administrador de clústeres con estos valores predeterminados en la devolución de llamada 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

Cómo agregar marcadores

Hay dos maneras de agregar marcadores al agrupador de marcadores: de forma individual o como arreglo.

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

Arreglo 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];

Invoca el agrupador de marcadores en clústeres

Una vez que hayas creado el agrupador de marcadores y le hayas transferido los marcadores que deseas agrupar, solo tienes que llamar al método cluster en tu instancia de agrupador de marcadores.

Swift

clusterManager.cluster()

Objective‑C

[_clusterManager cluster];

Administra eventos en marcadores y clústeres

En general, cuando uses el SDK de Maps para iOS, debes implementar el protocolo GMSMapViewDelegate a fin de escuchar eventos en el mapa. Puedes escuchar eventos de mapa, pero no los eventos de administrador de clústeres de tipo seguro. Cuando el usuario presiona un marcador, un elemento de clúster individual o un clúster, la API activa mapView:didTapMarker: y adjunta los datos adicionales del clúster a la propiedad marker.userData. Luego, puedes verificar si userData cumple con el protocolo GMUCluster para determinar si se presionó un ícono de clúster o un marcador.

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

El administrador de clústeres intercepta los eventos que implementaste en clusterManager. Reenvía los eventos restantes al delegado del mapa, si se proporciona. Ten en cuenta que los eventos para marcadores estándar (es decir, marcadores que no generó el procesador de clústeres) siempre se reenvían al delegado del mapa.

Cómo personalizar el agrupamiento de marcadores en clústeres

Puedes proporcionar una implementación personalizada para GMUClusterRenderer, GMUClusterIconGenerator o GMUClusterAlgorithm. Puedes basar tu implementación personalizada en la implementación de muestra de estos protocolos incluidos en la biblioteca de utilidades, o puedes codificar una implementación completamente personalizada si cumples con los protocolos.