Raggruppamento di indicatori

Questa pagina descrive l'utilità di clustering degli indicatori disponibile nella libreria di utilità di Maps SDK for iOS.

Raggruppando gli indicatori, puoi inserirne un numero elevato su una mappa senza renderla illeggibile. L'utilità di clustering degli indicatori ti aiuta a gestire più indicatori a diversi livelli di zoom.

Quando un utente visualizza la mappa a un livello di zoom elevato, gli indicatori singoli vengono visualizzati sulla mappa. Quando l'utente diminuisce lo zoom, gli indicatori si raggruppano in cluster per facilitare la visualizzazione della mappa.

Lo screenshot seguente mostra lo stile predefinito dei cluster di indicatori:

Di seguito è riportato un esempio di cluster di indicatori personalizzati:

Prerequisiti e note

Libreria di utilità di Maps SDK for iOS

L'utilità di clustering degli indicatori fa parte della libreria di utilità di Maps SDK for iOS. Se non hai ancora configurato la libreria, segui la guida alla configurazione prima di leggere il resto di questa pagina.

Per prestazioni ottimali, il numero massimo consigliato di indicatori è 10.000.

Autorizzazione di accesso alla posizione

Questo esempio utilizza il GPS del dispositivo per individuare l'utente e la mappa in base alle sue coordinate. Per attivare questa funzionalità, devi aggiungere una descrizione all'autorizzazione NSLocationWhenInUseUsageDescription nel file Info.plist del progetto.

Per aggiungere questa autorizzazione:

1. Fai clic sul file Info.plist nel navigatore del progetto in Xcode per aprire l' editor dell'elenco delle proprietà.
2. Fai clic sull'icona "+" accanto a "Information Property List" (Elenco delle proprietà delle informazioni) per aggiungere una nuova proprietà.
3. Nel campo "chiave", digita "NSLocationWhenInUseUsageDescription". Xcode lo tradurrà automaticamente nel nome lungo "Privacy - Location When In Use Usage Description" (Privacy - Descrizione dell'utilizzo della posizione quando in uso). Per un elenco completo delle possibili proprietà di autorizzazione di accesso alla posizione, consulta Requesting Authorization for Location Services nella documentazione per sviluppatori Apple.
4. Lascia il campo "Tipo" impostato su "Stringa".
5. Nel campo 'Valore', digita una descrizione del motivo per cui la tua app richiede l'utilizzo della posizione dell'utente. Ad esempio, "Individua l'utente per fornire elenchi di attività commerciali nelle vicinanze".

Implementare il clustering degli indicatori

L'implementazione del clustering degli indicatori prevede tre passaggi:

1. Crea un'istanza di gestione dei cluster.
2. Trasmetti gli indicatori che vuoi raggruppare al gestore dei cluster.
3. Richiama il gestore dei cluster.

Creare il gestore dei cluster

Per utilizzare il gestore dei cluster:

1. Imposta ViewController in cui viene eseguito il rendering della mappa in modo che sia conforme al GMSMapViewDelegate protocollo.
2. Crea un'istanza di GMUClusterManager.
3. Trasmetti l'istanza di GMSMapView in cui vuoi implementare il clustering degli indicatori e le implementazioni dei seguenti protocolli all'istanza GMUClusterManager instance:
   • GMUClusterIconGenerator: fornisce la logica dell'applicazione che recupera le icone dei cluster da utilizzare a diversi livelli di zoom.
   • GMUClusterAlgorithm: specifica un algoritmo che determina il comportamento del raggruppamento degli indicatori, ad esempio la distanza tra gli indicatori da includere nello stesso cluster.
   • GMUClusterRenderer: fornisce la logica dell'applicazione che gestisce il rendering effettivo delle icone dei cluster sulla mappa.
4. Imposta il delegato della mappa sull'istanza GMUClusterManager.

La libreria di utilità include implementazioni predefinite del generatore di icone (GMUDefaultClusterIconGenerator), algoritmo (GMUNonHierarchicalDistanceBasedAlgorithm) e renderer (GMUDefaultClusterRenderer). Se vuoi, puoi creare il tuo generatore di icone, algoritmo e renderer di clustering personalizzati.

Il seguente codice crea un gestore dei cluster utilizzando questi valori predefiniti nel viewDidLoad callback di ViewController:

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)
    // ...
  }
  // ...
}
      

@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
      

Aggiungere indicatori

Esistono due modi per aggiungere indicatori al raggruppatore di indicatori: singolarmente o come array.

Indicatore singolo

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

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

Array di indicatori

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)
      

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

Richiamare il raggruppatore di indicatori

Dopo aver creato il raggruppatore di indicatori e avergli trasmesso gli indicatori che vuoi raggruppare, tutto quello che devi fare è chiamare il metodo cluster sull'istanza del raggruppatore di indicatori.

clusterManager.cluster()
      

[_clusterManager cluster];
      

Gestire gli eventi su indicatori e cluster

In generale, quando utilizzi Maps SDK for iOS, per ascoltare gli eventi sulla mappa devi implementare il GMSMapViewDelegate protocollo. Puoi ascoltare gli eventi della mappa, ma non puoi ascoltare gli eventi del gestore dei cluster con tipo sicuro. Quando l'utente tocca un indicatore, un elemento di cluster singolo o un cluster, l'API attiva mapView:didTapMarker: e associa i dati del cluster aggiuntivi alla marker.userData proprietà. Puoi quindi verificare se il userData è conforme a il protocollo GMUCluster per determinare se è stata toccata un'icona di cluster o un indicatore.

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
}
      

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

Il gestore dei cluster ora intercetta tutti gli eventi che hai implementato su clusterManager. Se forniti, inoltra gli eventi rimanenti al delegato della mappa. Tieni presente che gli eventi per gli indicatori standard (ovvero gli indicatori non generati dal renderer dei cluster) vengono sempre inoltrati al delegato della mappa.

Personalizzare il clustering degli indicatori

Puoi fornire un'implementazione personalizzata per il GMUClusterRenderer, GMUClusterIconGenerator, o il GMUClusterAlgorithm. Puoi basare l'implementazione personalizzata sull'implementazione di esempio di questi protocolli inclusi nella libreria di utilità oppure puoi codificare un'implementazione completamente personalizzata rispettando i protocolli.