En esta página, se describe la utilidad de agrupamiento de marcadores en clústeres disponible en el biblioteca de utilidades para el 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 de agrupamiento de marcadores en clústeres te ayuda 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](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/ios-sdk/images/clustering-default-icon.png?authuser=4&hl=es)
A continuación, se muestra un ejemplo de clústeres de marcadores personalizados:
![Mapa con marcadores agrupados en clústeres personalizados](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/ios-sdk/images/clustering-custom-icon.png?authuser=4&hl=es)
Requisitos previos y notas
Biblioteca de utilidades del SDK de Maps para iOS
La utilidad de agrupamiento de marcadores en clústeres forma parte del SDK de Maps para iOS Biblioteca de utilidades 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 el mapa en sus coordenadas. Para habilitar
esto, debes agregar una descripción al permiso NSLocationWhenInUseUsageDescription
en el archivo Info.plist
del proyecto.
Para agregar esto, haz lo siguiente:
- Haz clic en el archivo
Info.plist
en el navegador de proyectos de Xcode para abrir la Editor de la lista de propiedades. - Haz clic en el signo '+' ícono junto a “Lista de propiedades de información” para agregar una nueva propiedad.
- En el campo “key” escribe "NSLocationWhenInUseUsageDescription". Xcode activará automáticamente traduce esto en el nombre largo "Privacy - Location when In Use Usage Description". Para un todas las posibles propiedades de permisos de ubicación, consulta Cómo solicitar la autorización de los Servicios de ubicación en la documentación para desarrolladores de Apple.
- Deja el “Tipo” configurado como “String”.
- En el campo "Valor" , escribe una descripción del motivo por el que tu aplicación requiere el uso de la la ubicación del usuario. Por ejemplo, “Localiza al usuario para proporcionarle fichas de empresas cercanas”.
Cómo implementar el agrupamiento de marcadores en clústeres
Para implementar el agrupamiento de marcadores en clústeres, debes seguir tres pasos:
- Crea una instancia de administrador de clústeres.
- Pásale los marcadores que deseas agrupar en clústeres al administrador de clústeres.
- Invoca el administrador de clústeres.
Crea el administrador de clústeres
Para usar el administrador de clústeres, haz lo siguiente:
- Establece el objeto
ViewController
en el que se renderiza tu mapa para que cumpla con la ProtocoloGMSMapViewDelegate
. - Crea una instancia de
GMUClusterManager
. - Pasa la instancia de
GMSMapView
en la que deseas implementar el agrupamiento de marcadores en clústeres e implementaciones de los siguientes protocolos a la instanciaGMUClusterManager
:GMUClusterIconGenerator
: Proporciona la lógica de la aplicación que recupera la los íconos de clúster que se usarán en diferentes niveles de zoom.GMUClusterAlgorithm
: Especifica un algoritmo que determina el comportamiento. de cómo se agrupan los marcadores, como la distancia entre los marcadores que se incluirán en el mismo clúster.GMUClusterRenderer
: Proporciona la lógica de la aplicación que controla el flujo de la renderización de los íconos de clústeres en el mapa.
- Configura el delegado del mapa en la instancia
GMUClusterManager
.
La biblioteca de utilidades incluye implementaciones predeterminadas del generador de íconos (GMUDefaultClusterIconGenerator
).
algoritmo (GMUNonHierarchicalDistanceBasedAlgorithm
) y procesador (GMUDefaultClusterRenderer
).
De manera opcional, puedes crear tu propio generador, algoritmo y renderizador de íconos de organización personalizados.
Con el siguiente código, se crea un administrador de clústeres con estos valores predeterminados en viewDidLoad
.
devolución de llamada 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
Existen dos maneras de agregar marcadores al agrupador de marcadores en clústeres: de manera individual o como un array.
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];
Array 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];
Cómo invocar el agrupador de marcadores en clústeres
Una vez que hayas creado tu agrupador de marcadores en clústeres y pasarle los marcadores que deseas agrupar en clústeres,
que debes hacer es llamar al método cluster
en tu instancia de agrupador de marcadores en clústeres.
Swift
clusterManager.cluster()
Objective-C
[_clusterManager cluster];
Administra eventos en marcadores y clústeres
En general, cuando se usa el SDK de Maps para iOS, debes implementar la implementación para escuchar eventos en el mapa
el GMSMapViewDelegate
protocolo. Puedes escuchar
asignar eventos, pero no puedes
escucha los eventos del administrador de clústeres de tipo seguro. Cuando el usuario toca 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 al
propiedad marker.userData
. Luego, puedes verificar si userData
cumple con los
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 ahora intercepta cualquier evento que hayas implementado en
clusterManager
Reenvía los eventos restantes al mapa.
un delegado, si se proporciona. Ten en cuenta que los eventos para marcadores estándares
(es decir, los marcadores que no genera el renderizador del clúster) siempre se reenvían,
al delegado del mapa.
Cómo personalizar el agrupamiento de marcadores en clústeres
Puedes proporcionar una implementación personalizada
GMUClusterRenderer
, GMUClusterIconGenerator
o
GMUClusterAlgorithm
Puedes basar tu implementación personalizada
la implementación de muestra de estos protocolos incluida en la utilidad
o puedes codificar una implementación completamente personalizada
protocolos.