إضافة خريطة إلى تطبيق iOS (Objective-C)

1. قبل البدء

ملخص

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

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستنشئ تطبيقًا متوافقًا مع نظام التشغيل iOS ينفّذ ما يلي:

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

أهداف الدورة التعليمية

• بدء استخدام "منصة خرائط Google"
• تحميل "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لتطبيقات iOS و"مكتبة الأدوات لحزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لتطبيقات iOS
• تحميل خريطة
• استخدام العلامات والعلامات المخصّصة وتجميع العلامات
• العمل مع نظام الأحداث في حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS لتوفير تفاعل المستخدم
• التحكّم في الخريطة آليًا
• الرسم على الخريطة

المتطلبات الأساسية

عليك التعرّف على العناصر أدناه لإكمال هذا الدرس العملي. إذا كنت معتادًا على استخدام Google Maps Platform، يمكنك الانتقال إلى الدرس العملي.

منتجات Google Maps Platform المطلوبة

في هذا الدرس العملي، ستستخدم منتجات "منصة خرائط Google" التالية:

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

بدء استخدام "منصة خرائط Google"

إذا لم يسبق لك استخدام "منصة خرائط Google"، اتّبِع دليل "البدء باستخدام منصة خرائط Google" أو شاهِد قائمة تشغيل "البدء باستخدام منصة خرائط Google" لإكمال الخطوات التالية:

1. أنشئ حساب فوترة.
2. إنشاء مشروع
3. فعِّل واجهات برمجة التطبيقات وحِزم تطوير البرامج (SDK) في "منصة خرائط Google" (المدرَجة في القسم السابق).
4. أنشئ مفتاح واجهة برمجة تطبيقات.

ملاحظة: يجب تسجيل الدخول إلى حساب حالي على Google أو إنشاء حساب جديد كجزء من عملية الاشتراك.

المتطلبات الأخرى لهذا الدرس التطبيقي حول الترميز

لإكمال هذا الدرس العملي، ستحتاج إلى الحسابات والخدمات والأدوات التالية:

• حساب على Google Cloud Platform تم تفعيل الفوترة فيه
• مفتاح واجهة برمجة تطبيقات Google Maps Platform مع تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS
• معرفة أساسية بلغة Objective-C
• الإصدار 12.0 من Xcode مع الإصدار 12.0 أو إصدار أحدث من حزمة SDK المستهدَفة

2. طريقة الإعداد

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

إعداد Google Maps Platform

إذا لم يكن لديك حساب على Google Cloud Platform ومشروع مفعَّل فيه نظام الفوترة، يُرجى الاطّلاع على دليل البدء باستخدام Google Maps Platform لإنشاء حساب فوترة ومشروع.

1. في Cloud Console، انقر على القائمة المنسدلة الخاصة بالمشروع واختَر المشروع الذي تريد استخدامه في هذا الدرس العملي.

2. فعِّل واجهات برمجة التطبيقات وحِزم تطوير البرامج (SDK) في Google Maps Platform المطلوبة لهذا الدرس العملي في Google Cloud Marketplace. لإجراء ذلك، اتّبِع الخطوات الواردة في هذا الفيديو أو هذه المستندات.
3. أنشئ مفتاح واجهة برمجة التطبيقات في صفحة بيانات الاعتماد في Cloud Console. يمكنك اتّباع الخطوات الواردة في هذا الفيديو أو هذه المستندات. تتطلّب جميع الطلبات إلى "منصة خرائط Google" مفتاح واجهة برمجة تطبيقات.

إعداد نموذج بدء المشروع

قبل البدء في هذا الدرس البرمجي، اتّبِع الخطوات التالية لتنزيل نموذج المشروع المبدئي بالإضافة إلى رمز الحل الكامل:

1. نزِّل مستودع GitHub لهذا الدرس العملي أو أنشئ نسخة منه على https://github.com/googlecodelabs/maps-platform-101-objc.

يقع مشروع StarterApp في الدليل /starter ويتضمّن بنية الملفات الأساسية التي تحتاج إليها لإكمال الدرس التطبيقي. يمكنك العثور على كل ما تحتاج إليه للعمل في الدليل /starter/StarterApp.

إذا أردت الاطّلاع على رمز الحلّ الكامل قيد التشغيل، يمكنك إكمال خطوات الإعداد أعلاه وعرض الحلّ في الدليل /solution/SolutionApp.

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

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

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

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

للبدء، افتح Pods > Podfile في Xcode (أو في محرّر النصوص المفضّل لديك) وعدِّل الملف لتضمين ملحقات "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google لنظام التشغيل iOS" و"مكتبة الأدوات" ضمن use_frameworks!:

pod 'GoogleMaps'
pod 'Google-Maps-iOS-Utils'

2. ثبِّت حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS وحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS Utility Library.

لتثبيت التبعيات، شغِّل pod install في الدليل /starter من سطر الأوامر. سيؤدي ذلك إلى تنزيل التبعيات تلقائيًا، بالإضافة إلى إنشاء StarterApp.xcworkspace. 3- بعد تثبيت التبعيات، افتح StarterApp.xcworkspace في Xcode، ثم شغِّل التطبيق في محاكي iPhone بالضغط على Command+R. إذا تم إعداد كل شيء بشكل صحيح، سيتم تشغيل المحاكي وعرض شاشة سوداء. لا داعي للقلق، لم تنشئ أي شيء بعد، لذا من المتوقّع أن تظهر لك هذه الرسالة. 4. استورِد حزمة تطوير البرامج (SDK) في AppDelegate.h.

بعد تثبيت التبعيات، يحين الوقت لتوفير مفتاح واجهة برمجة التطبيقات لحزمة SDK. الخطوة الأولى هي استيراد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS كعنصر تابع من خلال وضع ما يلي أسفل عبارة #import "AppDelegate.h" import:

@import GoogleMaps;

5. أسفل عبارة استيراد حزمة تطوير البرامج (SDK) لنظام التشغيل iOS، عرِّف الثابت NSString بالقيمة المضبوطة على مفتاح واجهة برمجة التطبيقات:

static NSString *const kMapsAPIKey = @"YOUR API KEY";

6. مرِّر مفتاح واجهة برمجة التطبيقات إلى حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من خلال استدعاء provideAPIKey على GMSServices في application: didFinishLaunchingWithOptions:

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [GMSServices provideAPIKey:kMapsAPIKey];
  return YES;
}

يجب أن يظهر ملف AppDelegate.m المعدَّل الآن على النحو التالي:

#import "AppDelegate.h"
@import GoogleMaps;

static NSString *const kMapsAPIKey = @"YOUR API KEY";

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [GMSServices provideAPIKey:kMapsAPIKey];
  return YES;
}
@end

يجب أن تبدو Podfile على النحو التالي:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'

target 'StarterApp' do
  use_frameworks!

pod 'GoogleMaps', '5.1.0.0'
pod 'Google-Maps-iOS-Utils', '3.4.0'

end

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

4. عرض خريطة

حان الوقت لعرض خريطتك الأولى.

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

1. فتح "ViewController.m"

هذا هو المكان الذي ستنفّذ فيه جميع الأعمال المتبقية لهذا الدرس البرمجي. ستلاحظ أنّه تمّت إضافة أحداث مراحل النشاط loadView وviewDidLoad لوحدة التحكّم في العرض مسبقًا. 2. استورِد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لأجهزة iOS من خلال إضافة ما يلي في أعلى الملف:

@import GoogleMaps;

3. عرِّف متغيّر مثيل ViewController لتخزين GMSMapView.

مثيل GMSMapView هو العنصر الرئيسي الذي ستعمل معه طوال هذا الدرس التطبيقي حول الترميز، وستشير إليه وتتفاعل معه من خلال طرق مختلفة لدورة حياة وحدة التحكّم في العرض. لإتاحة استخدامها، عدِّل عملية تنفيذ ViewController لتحديد متغيّر مثيل لتخزينها:

@implementation ViewController {
  GMSMapView *_mapView;
}

4. في loadView، أنشئ مثيلاً من GMSCameraPosition.

تحدّد GMSCameraPosition مكان توسيط الخريطة ومستوى التكبير أو التصغير الذي سيتم عرضه. يستدعي هذا الرمز الطريقة cameraWithLatitude:longitude:zoom: لتوسيط الخريطة على سيدني، أستراليا، عند خط عرض -33.86 وخط طول 151.20، مع مستوى تكبير/تصغير يبلغ 12:

GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.86 longitude:151.20 zoom:12];

5. في loadView، أنشئ مثيلاً من GMSMapView لإنشاء الخريطة.

لإنشاء مثيل خريطة جديد، استدعِ الدالة mapWithFrame:camera:. لاحظ كيف تم ضبط الإطار على CGRectZero، وهو متغير عام من مكتبة CGGeometry لنظام التشغيل iOS يحدّد إطارًا بعرض 0 وارتفاع 0، ويقع في الموضع (0,0) داخل وحدة التحكّم في العرض. يتم ضبط الكاميرا على موضع الكاميرا الذي أنشأته للتو.

لعرض الخريطة فعليًا، عليك ضبط العرض الجذر لوحدة التحكّم في العرض على _mapview، ما سيؤدي إلى عرض الخريطة بملء الشاشة.

_mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
self.view = _mapView;

6. اضبط GMSMapViewDelegate على وحدة التحكّم في العرض.

عند التنفيذ، يتيح لك مفوّض عرض الخريطة التعامل مع الأحداث الناتجة عن تفاعلات المستخدمين على مثيل GMSMapView، وهو ما ستحتاج إليه في الخطوات اللاحقة.

أولاً، عدِّل واجهة ViewController لتتوافق مع بروتوكول GMSMapViewDelegate:

@interface ViewController ()<GMSMapViewDelegate>

بعد ذلك، أضِف ما يلي لضبط GMSMapViewDelegate على ViewController.

_mapView.delegate = self;

أعِد الآن تحميل التطبيق في محاكي iOS (Command+R)، وستظهر الخريطة.

للتلخيص، في هذه الخطوة، أنشأت مثيلاً من GMSMapView لعرض خريطة تتوسّط مدينة سيدني في أستراليا.

يجب أن يظهر ملف ViewController.m الآن على النحو التالي:

#import "ViewController.h"
#import "LocationGenerator.h"
@import GoogleMaps;

@interface ViewController ()<GMSMapViewDelegate>
@end

@implementation ViewController {
  GMSMapView *_mapView;
}

- (void)loadView {
  [super loadView];
  GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.86 longitude:151.20 zoom:12];
  _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
  self.view = _mapView;
  _mapView.delegate = self;
}

5- تصميم الخرائط باستخدام السحابة الإلكترونية (اختياري)

يمكنك تخصيص نمط الخريطة باستخدام تصميم الخرائط باستخدام السحابة الإلكترونية.

إنشاء رقم تعريف خريطة

إذا لم يسبق لك إنشاء معرّف خريطة مرتبط بنمط خريطة، يمكنك الاطّلاع على دليل معرّفات الخرائط لإكمال الخطوات التالية:

1. أنشئ معرّف خريطة.
2. ربط رقم تعريف خريطة بنمط خريطة

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

إضافة رقم تعريف الخريطة إلى تطبيقك

لاستخدام معرّف الخريطة الذي أنشأته في الخطوة السابقة، افتح الملف ViewController.m وأنشئ عنصر GMSMapID ضمن الطريقة loadView وقدِّم له معرّف الخريطة. بعد ذلك، عدِّل عملية إنشاء GMSMapView من خلال توفير الكائن GMSMapID كمعلَمة.

ViewController.m

- (void)loadView {
    GMSMapID *mapID = [[GMSMapID alloc] initWithIdentifier:@"YOUR_MAP_ID"];
    _mapView = [GMSMapView mapWithFrame:CGRectZero mapID:mapID camera:camera];
    // ...
}

بعد إكمال هذه الخطوات، يمكنك تشغيل التطبيق للاطّلاع على الخريطة بالنمط الذي اخترته.

6. إضافة علامات إلى الخريطة

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

في هذه الخطوة، ستتعرّف على كيفية استخدام الفئة GMSMarker لوضع علامات على الخريطة.

يُرجى العِلم أنّه لا يمكن وضع العلامات على الخريطة إلا بعد تحميلها من الخطوة السابقة في حدث دورة حياة loadView لوحدة التحكّم في العرض، لذا ستُكمل هذه الخطوات في حدث دورة حياة viewDidLoad، الذي يتم استدعاؤه بعد تحميل العرض (والخريطة).

1. حدِّد عنصر CLLocationCoordinate2D.

‫CLLocationCoordinate2D هي بنية متاحة من خلال مكتبة CoreLocation لنظام التشغيل iOS، وتحدّد موقعًا جغرافيًا عند خط عرض وخط طول محدّدين. لبدء إنشاء العلامة الأولى، حدِّد عنصر CLLocationCoordinate2D واضبط خطَّي العرض والطول على منتصف الخريطة. يمكن الوصول إلى إحداثيات مركز الخريطة من عرض الخريطة باستخدام السمتَين camera.target.latitude وcamera.target.longitude.

CLLocationCoordinate2D mapCenter = CLLocationCoordinate2DMake(_mapView.camera.target.latitude, _mapView.camera.target.longitude);

2. أنشئ مثيلاً من GMSMarker.

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

GMSMarker *marker = [GMSMarker markerWithPosition:mapCenter];

3. ضبط رمز مخصّص للعلامة

إنّ محدّد الموقع التلقائي باللون الأحمر في "خرائط Google" هو خيار رائع، ولكن تخصيص خريطتك هو خيار رائع أيضًا. لحسن الحظ، من السهل جدًا استخدام علامة مخصّصة مع حزمة تطوير البرامج (SDK) لـ "خرائط Google" المتوافقة مع iOS. ستلاحظ أنّ مشروع StarterApp يتضمّن صورة باسم custom_pin.png يمكنك استخدامها، ولكن يمكنك استخدام أي صورة تريدها.

لضبط العلامة المخصّصة، اضبط السمة icon للعلامة على مثيل من UIImage.

marker.icon = [UIImage imageNamed:@"custom_pin.png"];

4. عرض العلامة على الخريطة

تم إنشاء العلامة، ولكن ستلاحظ أنّها غير ظاهرة على الخريطة. لإجراء ذلك، اضبط السمة map للعنصر GMSMarker على عنصر من GMSMapView.

marker.map = _mapView;

أعِد الآن تحميل التطبيق وشاهِد خريطتك الأولى التي تتضمّن علامة.

للتلخيص، أنشأت في هذا القسم مثيلاً لفئة GMSMarker وطبّقته على عرض الخريطة لعرض علامة على الخريطة. من المفترض أن يبدو حدث دورة الحياة viewDidLoad المعدَّل في ViewController.m على النحو التالي:

- (void)viewDidLoad {
  [super viewDidLoad];

  CLLocationCoordinate2D mapCenter = CLLocationCoordinate2DMake(_mapView.camera.target.latitude, _mapView.camera.target.longitude);
  GMSMarker *marker = [GMSMarker markerWithPosition:mapCenter];
  marker.icon = [UIImage imageNamed:@"custom_pin.png"];
  marker.map = _mapView;
}

7. تفعيل ميزة "تجميع العلامات"

عند استخدام الكثير من العلامات أو العلامات التي تقع بالقرب من بعضها البعض، قد تواجه مشكلة تتداخل فيها العلامات أو تظهر بشكل مزدحم جدًا، ما يؤدي إلى تجربة مستخدم سيئة. على سبيل المثال، إذا كان هناك علامتان متجاورتان جدًا، قد ينتهي بك الأمر بموقف مثل هذا:

وهنا يأتي دور تجميع العلامات. تجميع العلامات هو ميزة أخرى يتم تنفيذها بشكل شائع، وهي تعمل على تجميع العلامات القريبة في رمز واحد يتغيّر حسب مستوى التكبير/التصغير، كما يلي:

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

1. إضافة المزيد من العلامات إلى الخريطة

للاطّلاع على تجميع العلامات في الخريطة، يجب أن يكون لديك الكثير من العلامات على الخريطة. لتسهيل ذلك، يتم توفير أداة إنشاء علامات مناسبة لك في مشروع البداية في LocationGenerator.m.

لإضافة أكبر عدد ممكن من العلامات إلى الخريطة، ما عليك سوى استدعاء generateMarkersNear:count: في دورة حياة viewDidLoad لوحدة التحكّم في العرض أسفل الرمز من الخطوة السابقة. تنشئ الطريقة عدد العلامات المحدّدة في count في مواقع جغرافية عشوائية حول الإحداثيات المحدّدة في العنصر CLLocationCoordinate2D. في هذه الحالة، يمكنك تمرير المتغيّر mapCenter الذي أنشأته سابقًا. يتم عرض العلامات في NSArray.

NSArray<GMSMarker *> *markerArray = [LocationGenerator generateMarkersNear:mapCenter count:100];

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

لإضافة مكتبة أدوات iOS في "خرائط Google" كعنصر تابع إلى مشروعك، أضِف ما يلي إلى قائمة العناصر التابعة في أعلى ViewController.m:

@import GoogleMapsUtils;

3. اضبط أداة تجميع العلامات.

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

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

id<GMUClusterAlgorithm> algorithm = [[GMUNonHierarchicalDistanceBasedAlgorithm alloc] init];

id<GMUClusterIconGenerator> clusterIconGenerator = [[GMUDefaultClusterIconGenerator alloc] init];

id<GMUClusterRenderer> renderer = [[GMUDefaultClusterRenderer alloc] initWithMapView:_mapView clusterIconGenerator:clusterIconGenerator];

4. أنشئ مثيلاً من GMUClusterManager.

‫GMUClusterManager هي الفئة التي تنفّذ تجميع العلامات في مجموعات، وذلك باستخدام الخوارزمية وأداة إنشاء الرموز والعارض الذي تحدّده. لإنشاء أداة العرض وإتاحتها لعرض الخريطة، عليك أولاً إضافة متغيّر مثيل إلى تنفيذ ViewController لتخزين مثيل أداة إدارة المجموعات:

@implementation ViewController {
  GMSMapView *_mapView;
  GMUClusterManager *_clusterManager;
}

بعد ذلك، أنشِئ مثيلاً من GMUClusterManager في حدث دورة حياة viewDidLoad:

_clusterManager = [[GMUClusterManager alloc] initWithMap:_mapView algorithm:algorithm renderer:renderer];

5. أضِف العلامات وشغِّل أداة تجميع العلامات.

بعد إعداد مثيل أداة تجميع العلامات، ما عليك سوى تمرير مصفوفة العلامات التي سيتم تجميعها إلى أداة إدارة المجموعات من خلال استدعاء addItems:، ثم تشغيل أداة التجميع من خلال استدعاء cluster.

[_clusterManager addItems:markerArray];
[_clusterManager cluster];

أعِد تحميل تطبيقك، وستظهر لك الآن مجموعة كبيرة من العلامات منظَّمة بشكل جيد. يمكنك تجربة مستويات تكبير/تصغير مختلفة من خلال الضغط بإصبعين على الخريطة وتكبيرها أو تصغيرها، وذلك لمعرفة كيفية تعديل مجموعات العلامات أثناء التكبير أو التصغير.

باختصار، في هذه الخطوة، أعددت مثيلاً لأداة تجميع العلامات من "مكتبة الأدوات المساعدة" في حزمة تطوير البرامج لتطبيق "خرائط Google" المتوافقة مع iOS، ثم استخدمته لتجميع 100 علامة على الخريطة. يجب أن يبدو حدث دورة الحياة viewDidLoad في ViewController.m الآن على النحو التالي:

- (void)viewDidLoad {
  [super viewDidLoad];

  CLLocationCoordinate2D mapCenter = CLLocationCoordinate2DMake(_mapView.camera.target.latitude,
                                                                _mapView.camera.target.longitude);
  GMSMarker *marker = [GMSMarker markerWithPosition:mapCenter];
  marker.icon = [UIImage imageNamed:@"custom_pin.png"];
  marker.map = _mapView;
  NSArray<GMSMarker *> *markerArray = [LocationGenerator generateMarkersNear:mapCenter count:100];

  id<GMUClusterAlgorithm> algorithm = [[GMUNonHierarchicalDistanceBasedAlgorithm alloc] init];
  id<GMUClusterIconGenerator> clusterIconGenerator = [[GMUDefaultClusterIconGenerator alloc] init];
  id<GMUClusterRenderer> renderer = [[GMUDefaultClusterRenderer alloc] initWithMapView:_mapView clusterIconGenerator:clusterIconGenerator];
  _clusterManager = [[GMUClusterManager alloc] initWithMap:_mapView algorithm:algorithm renderer:renderer];

  [_clusterManager addItems:markerArray];
  [_clusterManager cluster];
}

8. إضافة تفاعل المستخدم

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

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

في هذه الخطوة، ستبرمِج الخريطة آليًا بحيث يتم تحريكها إلى منتصف أي علامة ينقر عليها المستخدم.

1. نفِّذ أداة معالجة النقر على العلامة.

يتم استدعاء mapView:didTapMarker في أي وقت ينقر فيه المستخدم على أحد العلامات التي أنشأتها سابقًا، بالإضافة إلى أي وقت ينقر فيه المستخدم على مجموعة علامات (يتم تنفيذ مجموعات العلامات داخليًا كمثيل من GMSMarker).

لتنفيذ معالج الأحداث، ابدأ بإنشاء نسخة فارغة منه في أسفل ViewController.m قبل عبارة end.

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

- (BOOL)mapView:(GMSMapView *)mapView didTapMarker:(GMSMarker *)marker {

  return NO;
}

2. التعامل مع حدث النقر وتحريك الكاميرا لإعادة توسيط الخريطة عند النقر على علامة أو مجموعة علامات

عند استدعاء mapView:didTapMarker، يتم تمرير مثيل GMSMarker الذي تم النقر عليه، ما يتيح لك التعامل معه في الرمز البرمجي. يمكنك استخدام هذا العنصر لإعادة توسيط الخريطة من خلال استدعاء animateToLocation: في عرض الخريطة من داخل معالج الأحداث، وتمرير موضع عنصر العلامة إليه، والذي يتوفّر في السمة position.

[_mapView animateToLocation:marker.position];

3. تكبير مجموعة من العلامات عند النقر عليها

من الأنماط الشائعة في تجربة المستخدم تكبير مجموعات العلامات عند النقر عليها. يتيح ذلك للمستخدمين عرض العلامات المجمّعة، لأنّ المجموعة ستتوسّع عند مستويات تكبير/تصغير أقل.

كما ذكرنا سابقًا، رمز مجموعة العلامات هو في الواقع مجرد تنفيذ لـ GMSMarker باستخدام رمز مخصّص. إذًا، كيف يمكنك معرفة ما إذا تم النقر على محدّد موقع أو مجموعة محدّدات مواقع؟ عندما ينشئ مدير تجميع العلامات رمزًا جديدًا لمجموعة العلامات، ينفّذ مثيلاً من GMSMarker ليتوافق مع بروتوكول يُسمى GMUCluster.. يمكنك استخدام شرط للتحقّق ممّا إذا كانت العلامة التي تم تمريرها إلى معالج الأحداث تتوافق مع هذا البروتوكول.

بعد معرفة أنّه تم النقر على مجموعة برمجيًا، يمكنك بعد ذلك استدعاء animateToZoom: في مثيل عرض الخريطة وضبط مستوى التكبير/التصغير على مستوى التكبير/التصغير الحالي بالإضافة إلى واحد. يتوفّر مستوى التكبير أو التصغير الحالي في مثيل عرض الخريطة في السمة camera.zoom.

لاحظ أيضًا كيف يعرض الرمز أدناه القيمة YES. يُعلم هذا معالج الأحداث بأنّك أكملت معالجة الحدث وأنه يجب عدم تنفيذ أي رمز إضافي في المعالج. أحد أسباب إجراء ذلك هو منع العنصر الأساسي GMSMarker من تنفيذ بقية سلوكه التلقائي، مثل عرض نافذة معلومات، وهو أمر غير منطقي في حالة النقر على رمز مجموعة.

if ([marker.userData conformsToProtocol:@protocol(GMUCluster)]) {
    [_mapView animateToZoom:_mapView.camera.zoom +1];
    return YES;
}

أعِد الآن تحميل التطبيق وانقر على بعض العلامات ومجموعات العلامات. عند النقر على أي منهما، ستتم إعادة تحديد مركز الخريطة على العنصر الذي تم النقر عليه. عند النقر على مجموعة من العلامات، سيتم أيضًا تكبير الخريطة بمستوى واحد، وسيتم توسيع مجموعة العلامات لعرض العلامات المجمّعة تحتها.

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

يجب أن تبدو طريقة mapView:didTapMarker على النحو التالي:

- (BOOL)mapView:(GMSMapView *)mapView didTapMarker:(GMSMarker *)marker {
  [_mapView animateToLocation:marker.position];

  if ([marker.userData conformsToProtocol:@protocol(GMUCluster)]) {
    [_mapView animateToZoom:_mapView.camera.zoom +1];
    return YES;
  }

  return NO;
}

9- الرسم على الخريطة

حتى الآن، أنشأت خريطة لمدينة سيدني تعرض علامات في 100 نقطة عشوائية، وتتعامل مع تفاعل المستخدم. في الخطوة الأخيرة من هذا الدرس التطبيقي حول الترميز، ستستخدم ميزات الرسم في Maps SDK لنظام التشغيل iOS لإضافة ميزة مفيدة أخرى إلى تجربة الخريطة.

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

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

1. أضِف متغيّر مثيل _circ إلى تنفيذ ViewController.

سيتم استخدام متغيّر المثيل هذا لحفظ الدائرة التي تم رسمها مؤخرًا، حتى يمكن إتلافها قبل رسم دائرة أخرى. ففي النهاية، لن يكون ذلك مفيدًا للمستخدم وسيبدو سيئًا للغاية إذا تم رسم دائرة حول كل علامة تم النقر عليها.

لإجراء ذلك، عدِّل عملية تنفيذ ViewController على النحو التالي:

@implementation ViewController {
  GMSMapView *_mapView;
  GMUClusterManager *_clusterManager;
  GMSCircle *_circ;
}

2. ارسم الدائرة عند النقر على علامة.

في أسفل طريقة mapView:didTapMarker، أضِف الرمز التالي لإنشاء مثيل لفئة GMSCircle في حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من أجل رسم دائرة جديدة بنصف قطر 800 متر من خلال استدعاء circleWithPosition:radius: وتمرير موضع العلامة التي تم النقر عليها إليها، تمامًا كما فعلت أعلاه عند إعادة توسيط الخريطة.

_circ = [GMSCircle circleWithPosition:marker.position radius:800];

3. اختَر نمط الدائرة.

بشكلٍ تلقائي، يرسم الأمر GMSCircle دائرة بحدود سوداء وتعبئة شفافة. سيعمل ذلك على عرض نصف القطر، ولكنّه لن يبدو جيدًا جدًا، وسيكون من الصعب بعض الشيء رؤيته. بعد ذلك، امنح الدائرة لون تعبئة لتحسين التصميم من خلال تعيين UIColor للسمة fillColor الخاصة بالدائرة. سيضيف الرمز التالي تعبئة رمادية بنسبة شفافية تبلغ% 50:

_circ.fillColor = [UIColor colorWithRed: 0.67 green: 0.67 blue: 0.67 alpha: 0.5];

4. عرض الدائرة على الخريطة

كما هو الحال عند إنشاء علامات في وقت سابق، ستلاحظ أنّ مجرد إنشاء مثيل من GMSCircle لا يؤدي إلى ظهوره على الخريطة. لإجراء ذلك، ما عليك سوى تعيين مثيل عرض الخريطة إلى السمة map للدائرة.

_circ.map = _mapView;

5. أزِل أي دوائر تم عرضها سابقًا.

كما ذكرنا سابقًا، لن تكون تجربة المستخدم جيدة إذا استمررنا في إضافة دوائر إلى الخريطة. لإزالة الدائرة التي تم إنشاؤها بواسطة حدث نقرة سابق، اضبط السمة map الخاصة بالعنصر _circ على nil في أعلى mapView:didTapMarker.

_circ.map = nil;

أعِد تحميل التطبيق، وانقر على علامة. من المفترض أن تظهر دائرة جديدة عند النقر على علامة، وأن تتم إزالة أي دائرة تم عرضها سابقًا.

باختصار، في هذه الخطوة، استخدَمت الفئة GMSCircle لعرض دائرة عند النقر على علامة.

يجب أن تبدو طريقة mapView:didTapMarker على النحو التالي:

- (BOOL)mapView:(GMSMapView *)mapView didTapMarker:(GMSMarker *)marker {
  _circ.map = nil;
  [_mapView animateToLocation:marker.position];

  if ([marker.userData conformsToProtocol:@protocol(GMUCluster)]) {
    [_mapView animateToZoom:_mapView.camera.zoom +1];
    return YES;
  }

  _circ = [GMSCircle circleWithPosition:marker.position radius:800];
  _circ.fillColor = [UIColor colorWithRed: 0.67 green: 0.67 blue: 0.67 alpha: 0.5];
  _circ.map = _mapView;
  return NO;
}

10. تهانينا

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

للاطّلاع على الرمز البرمجي المكتمل، يمكنك الانتقال إلى المشروع النهائي في الدليل /solution.

ما هي الخطوات التالية؟

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

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

لمواصلة التعرّف على المزيد من الطرق التي يمكنك من خلالها استخدام "منصة خرائط Google" على الويب، يمكنك الاطّلاع على الروابط التالية:

• مستندات "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لأجهزة iOS
• قناة "منصة خرائط Google" على YouTube
• برامج الترميز في "منصة خرائط Google"
• المشاريع مفتوحة المصدر على "منصة خرائط Google" على GitHub