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

پلاتفرم را انتخاب کنید: Android iOS JavaScript

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

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

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

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

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

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

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

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

کتابخانه کاروری‌های کیت توسعه نرم‌افزار Maps ویژه iOS

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

برای بهترین عملکرد، حداکثر تعداد توصیه‌شده نشانگرها ۱۰٬۰۰۰ است.

اجازه مکان

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

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

  1. روی فایل Info.plist در Project Navigator (پیمایشگر پروژه) در Xcode کلیک کنید تا Property List Editor (ویرایشگر فهرست ویژگی) باز شود.
  2. برای افزودن ویژگی جدید، روی نماد «+» در کنار «فهرست ویژگی‌های اطلاعات» کلیک کنید.
  3. در فیلد «کلید»، «NSLocationWhenInUseUsageDescription» را تایپ کنید. Xcode به‌طور خودکار این را به نام طولانی «Privacy - Location When In Use Usage Description» ترجمه می‌کند. برای مشاهده فهرست کامل ویژگی‌های ممکن برای اجازه مکان، به درخواست مجوز برای خدمات مکان در اسناد Apple Developer مراجعه کنید.
  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، مدیر خوشه‌ای ایجاد می‌کند:

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

آبجکتیو-سی

@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

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

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

نشانگر تکی

Swift

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

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

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)

آبجکتیو-سی

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 را در نمونه خوشه‌کننده نشانگرها فراخوانی کنید.

Swift

clusterManager.cluster()

آبجکتیو-سی

[_clusterManager cluster];

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

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

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
}

آبجکتیو-سی

- (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 ارائه دهید. می‌توانید پیاده‌سازی سفارشی‌تان را براساس پیاده‌سازی نمونه این پروتکل‌ها که در کتابخانه ابزار گنجانده شده است انجام دهید، یا می‌توانید با برآورده کردن پروتکل‌ها، پیاده‌سازی کاملاً سفارشی را کدگذاری کنید.