خوشه بندی نشانگر

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت

این صفحه ابزار خوشه‌بندی نشانگر را که در کتابخانه ابزار Maps SDK برای iOS موجود است، شرح می‌دهد.

با خوشه‌بندی نشانگرهایتان، می‌توانید تعداد زیادی نشانگر را روی نقشه قرار دهید بدون اینکه خواندن نقشه دشوار شود. ابزار خوشه‌بندی نشانگر به شما کمک می‌کند تا چندین نشانگر را در سطوح بزرگنمایی مختلف مدیریت کنید.

وقتی کاربر نقشه را با بزرگنمایی بالا مشاهده می‌کند، نشانگرهای منفرد روی نقشه نشان داده می‌شوند. وقتی کاربر بزرگنمایی را کاهش می‌دهد، نشانگرها در خوشه‌هایی جمع می‌شوند تا مشاهده نقشه آسان‌تر شود.

تصویر زیر سبک پیش‌فرض خوشه‌های نشانگر را نشان می‌دهد:

در زیر نمونه‌ای از خوشه‌های نشانگر سفارشی آمده است:

پیش نیازها و نکات

کتابخانه ابزار Maps SDK برای iOS

ابزار خوشه‌بندی نشانگر بخشی از کتابخانه‌ی ابزار Maps SDK برای iOS است. اگر هنوز کتابخانه را راه‌اندازی نکرده‌اید، قبل از خواندن ادامه‌ی این صفحه، راهنمای راه‌اندازی را دنبال کنید.

برای بهترین عملکرد، حداکثر تعداد نشانگرهای توصیه شده 10،000 است.

مجوز موقعیت مکانی

این مثال از GPS دستگاه برای مکان‌یابی کاربر و نقشه روی مختصات او استفاده می‌کند. برای فعال کردن این قابلیت، باید توضیحی را به مجوز NSLocationWhenInUseUsageDescription در فایل Info.plist پروژه اضافه کنید.

برای اضافه کردن این مورد، موارد زیر را انجام دهید:

1. برای باز کردن ویرایشگر فهرست ویژگی‌ها (Property List Editor)، روی فایل Info.plist در Project Navigator در Xcode کلیک کنید.
2. برای افزودن یک ملک جدید، روی نماد «+» در کنار «لیست املاک اطلاعات» کلیک کنید.
3. در فیلد «کلید»، عبارت «NSLocationWhenInUseUsageDescription» را تایپ کنید. Xcode به طور خودکار این عبارت را به نام طولانی «Privacy - Location When In Use Usage Description» ترجمه می‌کند. برای مشاهده لیست کاملی از ویژگی‌های مجوز موقعیت مکانی، به بخش «درخواست مجوز برای سرویس‌های موقعیت مکانی» در مستندات توسعه‌دهندگان اپل مراجعه کنید.
4. فیلد «نوع» را روی «رشته» تنظیم کنید.
5. در فیلد «مقدار»، توضیحی در مورد دلیل نیاز برنامه شما به استفاده از موقعیت مکانی کاربر تایپ کنید. برای مثال، «کاربر را برای ارائه فهرست مشاغل نزدیک پیدا می‌کند.»

پیاده‌سازی خوشه‌بندی نشانگر

پیاده‌سازی خوشه‌بندی نشانگرها سه مرحله دارد:

1. یک نمونه مدیر خوشه ایجاد کنید.
2. نشانگرهایی را که می‌خواهید خوشه‌بندی کنید به خوشه‌بند منتقل کنید.
3. مدیر خوشه را فراخوانی کنید.

برای دیدن یک مثال کامل از نحوه پیاده‌سازی خوشه‌بندی نشانگر، برنامه‌های نمونه Objective-C و Swift را در GitHub بررسی کنید.

ایجاد مدیر خوشه

برای استفاده از مدیر خوشه، موارد زیر را انجام دهید:

1. ViewController که نقشه شما در آن رندر می‌شود را طوری تنظیم کنید که با پروتکل GMSMapViewDelegate مطابقت داشته باشد.
2. یک نمونه از GMUClusterManager ایجاد کنید.
3. نمونه‌ای از GMSMapView که می‌خواهید خوشه‌بندی نشانگر را در آن پیاده‌سازی کنید و پیاده‌سازی‌های پروتکل‌های زیر را به نمونه GMUClusterManager منتقل کنید:
   • GMUClusterIconGenerator : منطق برنامه را ارائه می‌دهد که آیکون‌های خوشه‌ای را برای استفاده در سطوح مختلف بزرگنمایی دریافت می‌کند.
   • GMUClusterAlgorithm : الگوریتمی را مشخص می‌کند که رفتار نحوه خوشه‌بندی نشانگرها، مانند فاصله بین نشانگرها برای قرار گرفتن در یک خوشه، را تعیین می‌کند.
   • GMUClusterRenderer : منطق برنامه‌ای را ارائه می‌دهد که رندر واقعی آیکون‌های خوشه روی نقشه را مدیریت می‌کند.
4. نماینده نقشه را روی نمونه GMUClusterManager تنظیم کنید.

این کتابخانه‌ی کاربردی شامل پیاده‌سازی‌های پیش‌فرض مولد آیکون ( GMUDefaultClusterIconGenerator )، الگوریتم ( GMUNonHierarchicalDistanceBasedAlgorithm ) و رندرکننده ( GMUDefaultClusterRenderer ) است. شما می‌توانید به صورت اختیاری مولد آیکون خوشه‌بندی، الگوریتم و رندرکننده‌ی سفارشی خود را ایجاد کنید.

کد زیر با استفاده از این مقادیر پیش‌فرض در فراخوانی viewDidLoad از 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
      

افزودن نشانگرها

دو راه برای اضافه کردن نشانگرها به خوشه‌بندی نشانگر وجود دارد: به صورت جداگانه یا به صورت آرایه.

نشانگر فردی

سویفت

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

آرایه‌ای از نشانگرها

سویفت

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

فراخوانی خوشه‌بند نشانگر

پس از اینکه خوشه‌بندی نشانگر خود را ایجاد کردید و نشانگرهایی را که می‌خواهید خوشه‌بندی کنید به آن ارسال کردید، تنها کاری که باید انجام دهید این است که متد cluster را روی نمونه خوشه‌بندی نشانگر خود فراخوانی کنید.

سویفت

clusterManager.cluster()
      

هدف-سی

[_clusterManager cluster];
      

مدیریت رویدادها روی نشانگرها و خوشه‌ها

به طور کلی هنگام استفاده از Maps SDK برای iOS، برای گوش دادن به رویدادهای روی نقشه، باید پروتکل GMSMapViewDelegate را پیاده‌سازی کنید. می‌توانید به رویدادهای نقشه گوش دهید، اما نمی‌توانید به رویدادهای مدیر خوشه از نوع ایمن گوش دهید. وقتی کاربر روی یک نشانگر، یک آیتم خوشه یا یک خوشه ضربه می‌زند، API تابع mapView:didTapMarker: فعال می‌کند و داده‌های خوشه اضافی را به ویژگی marker.userData متصل می‌کند. سپس می‌توانید بررسی کنید که آیا userData با پروتکل GMUCluster مطابقت دارد یا خیر تا مشخص شود که آیا روی یک نماد خوشه یا یک نشانگر ضربه زده شده است یا خیر.

سویفت

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

مدیر خوشه اکنون هر رویدادی را که در clusterManager پیاده‌سازی کرده‌اید، رهگیری می‌کند. در صورت وجود، رویدادهای باقی‌مانده را به نماینده نقشه ارسال می‌کند. توجه داشته باشید که رویدادهای مربوط به نشانگرهای استاندارد (یعنی نشانگرهایی که توسط رندرکننده خوشه تولید نمی‌شوند) همیشه به نماینده نقشه ارسال می‌شوند.

خوشه‌بندی نشانگر را سفارشی کنید

شما می‌توانید یک پیاده‌سازی سفارشی برای GMUClusterRenderer ، GMUClusterIconGenerator یا GMUClusterAlgorithm ارائه دهید. می‌توانید پیاده‌سازی سفارشی خود را بر اساس پیاده‌سازی نمونه این پروتکل‌های موجود در کتابخانه ابزار قرار دهید، یا می‌توانید با تکمیل پروتکل‌ها، یک پیاده‌سازی کاملاً سفارشی را کدگذاری کنید.