تجميع العلامات

اختيار النظام الأساسي: Android iOS JavaScript

توضّح هذه الصفحة الأداة المساعدة لتجميع العلامات المتاحة في مكتبة الأدوات المساعدة لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS.

من خلال تجميع العلامات في مجموعات، يمكنك وضع عدد كبير من العلامات على الخريطة بدون تصعيب قراءة الخريطة. تساعدك أداة تجميع محدّدات المواقع في إدارة عدة علامات بمستويات تكبير مختلفة.

عندما يشاهد المستخدم الخريطة بمستوى تكبير/تصغير عالٍ، تظهر العلامات الفردية على الخريطة. عندما يقوم المستخدم بالتصغير، تتجمع العلامات معًا في مجموعات لتسهيل عرض الخريطة.

تعرض لقطة الشاشة التالية النمط التلقائي لمجموعات العلامات:

خريطة تحتوي على علامات مجمعة بالنمط التلقائي

في ما يلي مثال على مجموعات العلامات المخصّصة:

خريطة بعلامات مجمعة مخصصة

المتطلّبات الأساسية والملاحظات

حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" في مكتبة أدوات iOS

تعتبر أداة تجميع العلامات جزءًا من حزمة تطوير البرامج (SDK) للخرائط في مكتبة الأدوات لنظام التشغيل iOS. وإذا لم يسبق لك إعداد المكتبة، يُرجى اتّباع دليل الإعداد قبل قراءة بقية هذه الصفحة.

لتحقيق أفضل أداء، يُنصح بأن يبلغ الحد الأقصى لعدد العلامات 10,000.

إذن تحديد الموقع الجغرافي

يستخدم هذا المثال نظام تحديد المواقع العالمي (GPS) في الجهاز لتحديد موقع المستخدم والخريطة على إحداثياته. لتفعيل ذلك، عليك إضافة وصف إلى إذن NSLocationWhenInUseUsageDescription في ملف Info.plist الخاص بالمشروع.

لإضافة هذا الإجراء، يُرجى اتّباع الخطوات التالية:

  1. انقر على ملف Info.plist في Project Navigator (مستكشف المشروع) في Xcode لفتح "محرِّر قائمة المواقع".
  2. انقر على الرمز "+" بجانب "قائمة خصائص المعلومات" لإضافة موقع إلكتروني جديد.
  3. في حقل "المفتاح"، اكتب "NSLocationWhenInUseUsageDescription". سيترجم Xcode هذا تلقائيًا إلى الاسم الطويل "الخصوصية - وصف الموقع عند الاستخدام". للحصول على قائمة كاملة بسمات أذونات تحديد الموقع الجغرافي المحتملة، يُرجى الاطّلاع على طلب الحصول على إذن لخدمات الموقع الجغرافي في مستندات مطوّري برامج Apple.
  4. اترك حقل "النوع" معيّنًا على "سلسلة".
  5. في حقل "القيمة"، اكتب وصفًا لسبب طلب تطبيقك استخدام الموقع الجغرافي للمستخدم. على سبيل المثال، "تحديد موقع المستخدم لتقديم بيانات نشاط تجاري قريبة".

تنفيذ تجميع العلامات

يتطلب تنفيذ تجميع العلامات ثلاث خطوات:

  1. أنشئ مثيلاً لمدير المجموعة.
  2. مرِّر العلامات التي تريد تجميعها في مدير المجموعة.
  3. اطلب مدير المجموعة.
للاطّلاع على مثال كامل حول كيفية تنفيذ تجميع العلامات، يمكنك الرجوع إلى أمثلة تطبيقات FALSE-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)
    // ...
  }
  // ...
}
      

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
      

إضافة العلامات

هناك طريقتان لإضافة علامات إلى أداة تجميع العلامات: بشكل فردي أو كصفيف.

محدّد موقع فردي

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

مصفوفة العلامات

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

استدعاء أداة تجميع محدّدات المواقع

بعد إنشاء أداة تجميع العلامات وتمريرها العلامات التي تريد تجميعها، ما عليك سوى استدعاء طريقة cluster على مثيل أداة تجميع محدّدات المواقع.

Swift

clusterManager.cluster()
      

Objective-C

[_clusterManager cluster];
      

معالجة الأحداث في العلامات والمجموعات

بوجه عام، عند استخدام حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل 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
}
      

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

يعترض مدير المجموعة الآن أي أحداث نفّذتها على clusterManager. يعيد توجيه أي أحداث متبقية إلى المستخدم المفوَّض على الخريطة، في حال توفّره. يُرجى العلم أنّ أحداث العلامات العادية (أي العلامات التي لا ينشئها عارض المجموعة) تتم إعادة توجيهها دائمًا إلى المستخدم المفوَّض بالخريطة.

تخصيص تجميع محدّدات المواقع

يمكنك توفير عملية تنفيذ مخصّصة للسمة GMUClusterRenderer أو GMUClusterIconGenerator أو GMUClusterAlgorithm. يمكنك إسناد عملية التنفيذ المخصّصة إلى نموذج من تنفيذ هذه البروتوكولات المضمّنة في مكتبة الأدوات المساعدة، أو يمكنك ترميز عملية تنفيذ مخصّصة بالكامل عن طريق استيفاء البروتوكولات.