Regroupement de marqueurs

Sélectionnez une plate-forme : Android iOS JavaScript

Cette page décrit l'utilitaire de regroupement de repères disponible dans la bibliothèque d'utilitaires du SDK Maps pour iOS.

Le regroupement de repères vous permet de placer un grand nombre de repères sur une carte sans la rendre difficile à lire. L'utilitaire de regroupement de repères vous aide à gérer plusieurs repères à différents niveaux de zoom.

Lorsque l'utilisateur affiche la carte à un niveau de zoom élevé, les différents repères s'affichent sur la carte. Lorsqu'il effectue un zoom arrière, les repères se regroupent pour faciliter la consultation de la carte.

La capture d'écran suivante montre le style par défaut des groupes de marqueurs :

Carte contenant des marqueurs regroupés, dans le style par défaut

La capture d'écran suivante montre des groupes de marqueurs personnalisés :

Une carte avec un groupe de repères personnalisé

Prérequis et remarques

Bibliothèque d'utilitaires du SDK Maps pour iOS

L'utilitaire de regroupement de repères fait partie de la bibliothèque d'utilitaires du SDK Maps pour iOS. Si vous n'avez pas encore configuré la bibliothèque, suivez le guide de configuration avant de poursuivre la lecture de cette page.

Pour des performances optimales, le nombre maximum de marqueurs recommandé est de 10 000.

Autorisation d'accéder à la position

Cet exemple utilise le GPS de l'appareil pour localiser l'utilisateur et la carte sur ses coordonnées. Pour ce faire, vous devez ajouter une description à l'autorisation NSLocationWhenInUseUsageDescription dans le fichier Info.plist du projet.

Pour ce faire :

  1. Cliquez sur le fichier Info.plist dans le navigateur de projet Xcode pour ouvrir l'éditeur de liste de propriétés.
  2. Cliquez sur l'icône "+" à côté de "Liste de propriétés d'informations" pour ajouter une propriété.
  3. Dans le champ « key », saisissez « NSLocationWhenInUseUsageDescription ». Xcode le traduira automatiquement par le nom complet « Privacy - Location When In Use Usage Description » (Confidentialité : description de l 'utilisation de la localisation en cours d'utilisation). Pour obtenir la liste complète des propriétés d 'autorisation d'accéder à la position possibles, consultez Demander l 'autorisation d'utiliser les services de localisation dans la documentation pour les développeurs Apple.
  4. Laissez le champ "Type" défini sur "String" (Chaîne).
  5. Dans le champ "Valeur", saisissez une description expliquant pourquoi votre application a besoin d'utiliser la position de l'utilisateur. Par exemple : "Localise l'utilisateur pour lui fournir des fiches d'établissements à proximité."

Implémenter le regroupement de repères

Pour implémenter le regroupement de repères, vous devez suivre trois étapes :

  1. Créez une instance de gestionnaire de cluster.
  2. Transmettez les repères que vous souhaitez regrouper au gestionnaire de clusters.
  3. Appelez le gestionnaire de cluster.
Pour voir un exemple complet d'implémentation du regroupement de repères, consultez les applications exemples en Objective-C et Swift sur GitHub.

Créer le gestionnaire de cluster

Pour utiliser le gestionnaire de cluster, procédez comme suit :

  1. Définissez le ViewController où votre carte est affichée pour qu'il soit conforme au protocole GMSMapViewDelegate.
  2. Créez une instance de GMUClusterManager.
  3. Transmettez l'instance de GMSMapView dans laquelle vous souhaitez implémenter le regroupement de repères, ainsi que les implémentations des protocoles suivants à l'instance GMUClusterManager :
    • GMUClusterIconGenerator : fournit la logique d'application qui récupère les icônes de cluster à utiliser à différents niveaux de zoom.
    • GMUClusterAlgorithm : spécifie un algorithme qui détermine le comportement de regroupement des repères, par exemple, la distance entre les repères à inclure dans le même groupe.
    • GMUClusterRenderer : fournit la logique d'application qui gère le rendu des icônes de clusters sur la carte.
  4. Définissez le délégué de la carte sur l'instance GMUClusterManager.

La bibliothèque d'utilitaires inclut des implémentations par défaut du générateur d'icônes (GMUDefaultClusterIconGenerator), de l'algorithme (GMUNonHierarchicalDistanceBasedAlgorithm) et du moteur de rendu (GMUDefaultClusterRenderer). Vous pouvez également créer votre propre générateur d'icônes, algorithme et moteur de rendu de regroupement personnalisés.

Le code suivant crée un gestionnaire de cluster à l'aide de ces valeurs par défaut dans le rappel 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

Ajouter des repères

Il existe deux façons d'ajouter des repères au regroupement de repères : individuellement ou sous forme de tableau.

Repère individuel

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

Tableau de repères

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

Appeler le regroupeur de repères

Une fois que vous avez créé votre outil de regroupement de repères et que vous lui avez transmis les repères que vous souhaitez regrouper, il vous suffit d'appeler la méthode cluster sur votre instance d'outil de regroupement de repères.

Swift

clusterManager.cluster()

Objective-C

[_clusterManager cluster];

Gérer les événements sur les marqueurs et les groupes

En général, lorsque vous utilisez le SDK Maps pour iOS, vous devez implémenter le protocole GMSMapViewDelegate pour écouter les événements sur la carte. Vous pouvez écouter les événements de carte, mais pas les événements du gestionnaire de clusters à sécurité typée. Lorsque l'utilisateur appuie sur un repère, un élément de cluster individuel ou un cluster, l'API déclenche mapView:didTapMarker: et associe les données de cluster supplémentaires à la propriété marker.userData. Vous pouvez ensuite vérifier si userData est conforme au protocole GMUCluster pour déterminer si l'utilisateur a appuyé sur une icône de cluster ou sur un repère.

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

Le gestionnaire de clusters intercepte désormais tous les événements que vous avez implémentés sur clusterManager. Il transmet tous les événements restants au délégué de la carte, le cas échéant. Notez que les événements pour les repères standards (c'est-à-dire les repères qui ne sont pas générés par le moteur de rendu de cluster) sont toujours transmis au délégué de la carte.

Personnaliser le regroupement de repères

Vous pouvez fournir une implémentation personnalisée pour GMUClusterRenderer, GMUClusterIconGenerator ou GMUClusterAlgorithm. Vous pouvez baser votre implémentation personnalisée sur l'implémentation exemple de ces protocoles incluse dans la bibliothèque d'utilitaires, ou coder une implémentation entièrement personnalisée en respectant les protocoles.