Cluster di indicatori

Seleziona piattaforma: Android iOS JavaScript

In questa pagina viene descritta l'utilità di clustering degli indicatori disponibile nella libreria di utilità per l'SDK Maps per iOS.

Grazie al raggruppamento degli indicatori, puoi posizionare un numero elevato di indicatori su una mappa senza renderla di difficile lettura. L'utilità di clustering degli indicatori consente di gestire più indicatori con livelli di zoom diversi.

Quando un utente visualizza la mappa a un livello di zoom elevato, vengono visualizzati i singoli indicatori. Quando l'utente riduce lo zoom, gli indicatori vengono raccolti in cluster per semplificare la visualizzazione della mappa.

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

Una mappa con indicatori in cluster nello stile predefinito

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

Una mappa con indicatori in cluster personalizzati

Prerequisiti e note

Libreria Maps SDK for iOS

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

Per un miglior rendimento, il numero massimo consigliato di indicatori è 10.000.

Autorizzazione di accesso alla posizione

In questo esempio viene utilizzato il GPS del dispositivo per individuare l'utente e la mappa sulle sue coordinate. Per abilitare questa funzionalità, devi aggiungere una descrizione all'autorizzazione NSLocationWhenInUseUsageDescription nel file Info.plist del progetto.

Ecco come fare:

  1. Fai clic sul file Info.plist in Explorer progetti in Xcode per aprire l'editor dell'elenco di proprietà.
  2. Fai clic sull'icona '+' accanto a 'Elenco proprietà informazioni' per aggiungere una nuova proprietà.
  3. Nel campo 'key', digita 'NSLocationwhenInUseUsageDescription'. Xcode lo traduce automaticamente nel nome esteso 'Privacy - Location When In Use Usage Description'. Per un elenco completo delle possibili proprietà per l'autorizzazione di accesso alla posizione, consulta la pagina Richiesta di autorizzazione per i servizi di geolocalizzazione nella documentazione per gli sviluppatori di Apple.
  4. Lascia il campo 'Type' impostato su 'String'.
  5. Nel campo 'Valore' digita una descrizione del motivo per cui la tua applicazione richiede l'utilizzo della posizione dell'utente. Ad esempio, "Localizza l'utente per fornire schede di attività commerciali nelle vicinanze".

Implementazione del clustering degli indicatori

L'implementazione del clustering degli indicatori prevede tre passaggi:

  1. Crea un'istanza del gestore cluster.
  2. Passa gli indicatori che vuoi cluster alla gestione dei cluster.
  3. Richiama il gestore di cluster.
Per un esempio completo di come implementare il clustering degli indicatori, guarda le app di esempio su GitHub di Objective-C e Swift.

Creazione del gestore di cluster in corso...

Per utilizzare il gestore del cluster:

  1. Imposta il campo ViewController in cui viene visualizzata la mappa per renderlo conforme al protocollo GMSMapViewDelegate.
  2. Crea un'istanza di GMUClusterManager.
  3. Passa l'istanza di GMSMapView in cui implementare il clustering degli indicatori e le implementazioni dei seguenti protocolli per l'istanza GMUClusterManager:
    • GMUClusterIconGenerator: fornisce la logica dell'applicazione che recupera le icone del cluster da utilizzare a diversi livelli di zoom.
    • GMUClusterAlgorithm: specifica un algoritmo che determina il comportamento del clustering 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 delle utilità include implementazioni predefinite del generatore di icone (GMUDefaultClusterIconGenerator), dell'algoritmo (GMUNonHierarchicalDistanceBasedAlgorithm) e del renderer (GMUDefaultClusterRenderer). Facoltativamente, puoi creare un genertator, un algoritmo e un renderer di icone a cilindri personalizzati.

Il codice seguente crea un gestore di cluster utilizzando queste impostazioni predefinite nel callback viewDidLoad di 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

Aggiungere indicatori

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

Indicatore singolo

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 di indicatori

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

Richiamare il cluster di indicatori

Dopo aver creato il cluster di indicatori e aver superato gli indicatori che vuoi cluster, tutto ciò che devi fare è chiamare il metodo cluster sull'istanza del cluster di indicatori.

Swift

clusterManager.cluster()

Objective-C

[_clusterManager cluster];

Gestire gli eventi su indicatori e cluster

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

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

Il gestore di cluster intercetta gli eventi che hai implementato su clusterManager. Inoltre, inoltra gli eventuali eventi rimanenti al delegato della mappa, se fornito. Tieni presente che gli eventi per indicatori standard (ovvero gli indicatori non generati dal renderer del cluster) vengono sempre inoltrati al delegato della mappa.

Personalizza clustering degli indicatori

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