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

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

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

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

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

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

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

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

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

للحصول على أفضل أداء، الحدّ الأقصى المقترَح لعدد العلامات هو 10,000 علامة.

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

يستخدم هذا المثال نظام تحديد المواقع العالمي (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. استدعاء أداة إدارة المجموعات

إنشاء مدير المجموعة

لاستخدام أداة إدارة المجموعات، اتّبِع الخطوات التالية:

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

التعامل مع الأحداث على العلامات والمجموعات

بشكل عام، عند استخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS، يجب تنفيذ البروتوكول GMSMapViewDelegate لتتبّع الأحداث على الخريطة. يمكنك الاستماع إلى أحداث الخريطة، ولكن لا يمكنك الاستماع إلى أحداث إدارة المجموعات الآمنة من حيث النوع. عندما ينقر المستخدم على علامة أو عنصر فردي من عناصر المجموعة أو على مجموعة، تشغّل واجهة برمجة التطبيقات الحدث 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. ويمكنك استناد عملية التنفيذ المخصّصة إلى نموذج عملية التنفيذ لهذه البروتوكولات المضمّنة في مكتبة الأدوات المساعدة، أو يمكنك ترميز عملية تنفيذ مخصّصة بالكامل من خلال استيفاء البروتوكولات.