الاستماع إلى أحداث التنقّل

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

نظرة عامة

توفّر لك حزمة Navigation SDK لنظام التشغيل iOS أدوات معالجة مرتبطة بالموقع الجغرافي للمستخدم والظروف على طول المسار، بالإضافة إلى بيانات مهمة حول الوقت والمسافة. في وحدة التحكّم في عرض الخريطة، يجب أن يعتمد تطبيقك البروتوكولات الخاصة بوظائف الاستماع التالية: GMSRoadSnappedLocationProviderListener و GMSNavigatorListener.

تعرض هذه القائمة طرق معالجة الأحداث المتاحة لأحداث التنقّل:

الاطّلاع على الرمز

تحديد المطابقة مع البروتوكولات المطلوبة

قبل تنفيذ طرق التنقّل، يجب أن يتبنّى عنصر التحكّم في العرض البروتوكولات التالية:

Swift

class ViewController:
  UIViewController,
  GMSNavigatorListener,
  GMSRoadSnappedLocationProviderListener
{
}

Objective-C

@interface ViewController () <GMSNavigatorListener, GMSRoadSnappedLocationProviderListener>
@end

بعد اعتماد بروتوكولات التنقّل، اضبط أدوات الاستماع على وحدة التحكّم في العرض. على سبيل المثال، يمكنك إضافة الرمز التالي إلى طريقة viewDidLoad().

Swift

mapView.navigator?.add(self)
mapView.roadSnappedLocationProvider?.add(self)

Objective-C

[_mapView.navigator addListener:self];
[_mapView.roadSnappedLocationProvider addListener:self];

تلقّي إشعارات بشأن الموقع الجغرافي أو إيقافها

يجب الحصول على تحديثات الموقع الجغرافي لعرض مستوى تقدّم المستخدم على الخريطة.

يعرض عنصر location السمات التالية:

موقع العقار الوصف
الارتفاع الارتفاع الحالي
coordinate.latitude إحداثيات خط العرض الحالية التي تم ضبطها على الطريق
coordinate.longitude إحداثيات خط الطول الحالية التي تم ضبطها على الطريق
دورة الاتجاه الحالي بالدرجات
السرعة السرعة الحالية
timestamp تاريخ/وقت القراءة الحالية
.

لتلقّي تعديلات مستمرة على الموقع الجغرافي، استدعِ الدالة mapView.roadSnappedLocationProvider.startUpdatingLocation واستخدِم GMSRoadSnappedLocationProviderListener لمعالجة الحدث didUpdateLocation.

يوضّح المثال التالي كيفية استدعاء startUpdatingLocation:

Swift

mapView.roadSnappedLocationProvider.startUpdatingLocation()

Objective-C

[_mapView.roadSnappedLocationProvider startUpdatingLocation];

تنشئ التعليمة البرمجية التالية عنصر GMSRoadSnappedLocationProviderListener يعالج الحدث didUpdateLocation.

Swift

func locationProvider(_ locationProvider: GMSRoadSnappedLocationProvider,
                      didUpdate location: CLLocation) {
  print("Location: \(location.description)")
}

Objective-C

- (void)locationProvider:(GMSRoadSnappedLocationProvider *)locationProvider
       didUpdateLocation:(CLLocation *)location {
  NSLog(@"Location: %@", location.description);
}

لتلقّي آخر المعلومات حول الموقع الجغرافي عندما يعمل التطبيق في الخلفية، اضبط قيمة allowsBackgroundLocationUpdates على "صحيح":

Swift

mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true

Objective-C

 _mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;

رصد أحداث الوصول

يستخدم تطبيقك الحدث didArriveAtWaypoint لرصد الوقت الذي تم فيه الوصول إلى وجهة. يمكنك استئناف الإرشادات والانتقال إلى نقطة على المسار التالية من خلال الاتصال بـ continueToNextDestinationWithCompletion()، ثم إعادة تفعيل الإرشادات. يجب أن يعيد تطبيقك تفعيل الإرشادات بعد إجراء المكالمة continueToNextDestinationWithCompletion().

بعد أن يستدعي التطبيق continueToNextDestinationWithCompletion، لن يتضمّن المتصفّح أي بيانات حول الوجهة السابقة. إذا أردت تحليل معلومات حول جزء من مسار، عليك استرداد هذه المعلومات من أداة التنقّل قبل استدعاء continueToNextDestinationWithCompletion().

يعرض مثال الرمز البرمجي التالي طريقة للتعامل مع حدث didArriveAtWaypoint:

Swift

func navigator(_ navigator: GMSNavigator, didArriveAt waypoint: GMSNavigationWaypoint) {
  print("You have arrived at: \(waypoint.title)")
  mapView.navigator?.continueToNextDestinationWithCompletion { _, _ in }
  mapView.navigator?.isGuidanceActive = true
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator didArriveAtWaypoint:(GMSNavigationWaypoint *)waypoint {
  NSLog(@"You have arrived at: %@", waypoint.title);
  [_mapView.navigator continueToNextDestinationWithCompletion:^(GMSNavigationWaypoint *waypoint,
                                                                GMSRouteStatus status){
  }];
  _mapView.navigator.guidanceActive = YES;
}

تلقّي إشعارات بشأن تغييرات المسار

لتلقّي إشعار كلما تم تغيير المسار، أنشئ طريقة للتعامل مع الحدث navigatorDidChangeRoute. يمكنك الوصول إلى المسار الجديد باستخدام السمتَين routeLegs وcurrentRouteLeg الخاصتَين بـ GMSNavigator.

Swift

func navigatorDidChangeRoute(_ navigator: GMSNavigator) {
  print("The route has changed.")
}

Objective-C

- (void)navigatorDidChangeRoute:(GMSNavigator *)navigator {
  NSLog(@"The route has changed.");
}

تلقّي إشعارات بشأن الوقت المتبقي للوصول إلى الوجهة

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

Swift

func navigator(_ navigator: GMSNavigator, didUpdateRemainingTime time: TimeInterval) {
  print("Time to next destination: \(time)")
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator didUpdateRemainingTime:(NSTimeInterval)time {
  NSLog(@"Time to next destination: %f", time);
}

لضبط الحد الأدنى للتغيير في الوقت المقدَّر للوصول إلى الوجهة التالية، اضبط السمة timeUpdateThreshold على GMSNavigator. يتم تحديد القيمة بالثواني. في حال عدم ضبط هذه السمة، تستخدم الخدمات القيمة التلقائية وهي ثانية واحدة.

Swift

navigator?.timeUpdateThreshold = 10

Objective-C

navigator.timeUpdateThreshold = 10;

تلقّي إشعارات بشأن المسافة إلى الوجهة

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

Swift

func navigator(_ navigator: GMSNavigator, didUpdateRemainingDistance distance: CLLocationDistance)
{
  let miles = distance * 0.00062137
  print("Distance to next destination: \(miles) miles.")
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator
    didUpdateRemainingDistance:(CLLocationDistance)distance {
  double miles = distance * 0.00062137;
  NSLog(@"%@", [NSString stringWithFormat:@"Distance to next destination: %.2f.", miles]);
}

لضبط الحد الأدنى للتغيير في المسافة المقدَّرة إلى الوجهة التالية، اضبط السمة distanceUpdateThreshold على GMSNavigator (يتم تحديد القيمة بالأمتار). في حال عدم ضبط هذه السمة، تستخدم الخدمات القيمة التلقائية وهي متر واحد.

Swift

navigator?.distanceUpdateThreshold = 100

Objective-C

navigator.distanceUpdateThreshold = 100;

تلقّي آخر المعلومات عن حركة المرور

لتلقّي تحديثات مستمرة عن حركة المرور في المسار المتبقي، أنشئ طريقة للتعامل مع الحدث didUpdateDelayCategory. يؤدي طلب delayCategoryToNextDestination إلى عرض GMSNavigationDelayCategory الذي يوفّر قيمة تتراوح بين 0 و3. تستند التعديلات على الفئة إلى الموقع الجغرافي الحالي لمستخدم التطبيق. إذا كانت بيانات عدد الزيارات غير متاحة، سيعرض GMSNavigationDelayCategory القيمة 0. تشير الأرقام من 1 إلى 3 إلى زيادة التدفّق من خفيف إلى غزير.

Swift

func navigator(_ navigator: GMSNavigator,
               didUpdate delayCategory: GMSNavigationDelayCategory)
{
  print("Traffic flow to next destination: \(delayCategory)")
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator
    didUpdateDelayCategory:(GMSNavigationDelayCategory)delayCategory {
  NSLog(@"Traffic flow to next destination: %ld", (long)delayCategory);
}

تعرض السمة GMSNavigationDelayCategory مستويات التأخير التالية:

فئة التأخير الوصف
GMSNavigationDelayCategoryNoData ‫0 - غير متوفّر، ما مِن بيانات عن حركة المرور أو :
المسار
GMSNavigationDelayCategoryHeavy ‫1- غزيرة
GMSNavigationDelayCategoryMedium ‫2 - متوسط
GMSNavigationDelayCategoryLight ‫3 - خفيف

تلقّي إشعارات بشأن السرعة

لتلقّي إشعارات عندما يتجاوز السائق الحد الأقصى للسرعة، أنشئ طريقة للتعامل مع الحدث didUpdateSpeedingPercentage.

Swift

// Listener to handle speeding events.
func navigator(_ navigator: GMSNavigator,
               didUpdateSpeedingPercentage percentageAboveLimit: CGFloat)
{
  print("Speed is \(percentageAboveLimit) above the limit.")
}

Objective-C

// Listener to handle speeding events.
- (void)navigator:(GMSNavigator *)navigator
    didUpdateSpeedingPercentage:(CGFloat)percentageAboveLimit {
  NSLog(@"Speed is %f percent above the limit.", percentageAboveLimit);
}

تغيير وضع الإضاءة المقترَح

تحسب الدالة GMSNavigator وضع الإضاءة المقترَح استنادًا إلى الوقت من اليوم والموقع الجغرافي للجهاز، ولا تستدعي الدالة didChangeSuggestedLightingMode إلا عند تغيُّر الوضع المقترَح (مثلًا عند شروق الشمس أو غروبها). لضمان بدء الخريطة بوضع الإضاءة المناسب عند تشغيل المستخدم لتطبيقك، اضبط قيمة mapView.lightingMode على suggestedLightingMode في برنامج التنقّل أثناء عملية التهيئة، ونفِّذ didChangeSuggestedLightingMode للتعامل مع التغييرات اللاحقة.

يوضّح المثال التالي كيفية ضبط وضع الإضاءة الأوّلي والاستماع إلى التغييرات المقترَحة في وضع الإضاءة:

Swift

// Set the initial lighting mode on launch or setup.
mapView.lightingMode = mapView.navigator?.suggestedLightingMode ?? .normal

// Define a listener for suggested changes to lighting mode.
func navigator(_ navigator: GMSNavigator,
               didChangeSuggestedLightingMode lightingMode: GMSNavigationLightingMode)
{
  print("Suggested lighting mode has changed: \(String(describing: lightingMode))")

  // Make the suggested change.
  mapView.lightingMode = lightingMode
}

Objective-C

// Set the initial lighting mode on launch or setup.
_mapView.lightingMode = _mapView.navigator.suggestedLightingMode;

// Define a listener for suggested changes to lighting mode.
- (void)navigator:(GMSNavigator *)navigator
    didChangeSuggestedLightingMode:(GMSNavigationLightingMode)lightingMode {
  NSLog(@"Suggested lighting mode has changed: %ld", (long)lightingMode);

  // Make the suggested change.
  _mapView.lightingMode = lightingMode;
}

لمزيد من المعلومات حول ضبط وضع الإضاءة تلقائيًا ويدويًا، يُرجى الاطّلاع على ضبط الوضع العادي ووضع الإضاءة المنخفضة.