استخدِم هذا الدليل لتفعيل تطبيقك كي يستمع إلى مجموعة متنوعة من الأحداث ويتفاعل معها، وهي الأحداث التي تتغيّر أثناء تنقّل المستخدم على طول مسار. لا يغطّي هذا الدليل تحديد مسار، بل يركّز على الاستجابة للأحداث على طول مسار معيّن.
نظرة عامة
توفّر لك حزمة Navigation SDK لنظام التشغيل iOS أدوات معالجة مرتبطة بالموقع الجغرافي للمستخدم والظروف على طول المسار، بالإضافة إلى بيانات مهمة حول الوقت والمسافة. في وحدة التحكّم في عرض الخريطة، يجب أن يعتمد تطبيقك البروتوكولات الخاصة بوظائف الاستماع التالية:
GMSRoadSnappedLocationProviderListener
و
GMSNavigatorListener
.
تعرض هذه القائمة طرق معالجة الأحداث المتاحة لأحداث التنقّل:
- يتم تشغيل
GMSNavigatorListener.didArriveAtWaypoint
عند الوصول إلى وجهة. GMSNavigatorListener.navigatorDidChangeRoute
، يتم تشغيل هذا الحدث عند تغيير المسار.- يتم استدعاء
GMSNavigatorListener.didUpdateRemainingTime
بشكل متكرر عند تغيير الوقت اللازم للوصول إلى الوجهة التالية، وذلك أثناء نشاط التوجيه. GMSNavigatorListener.didUpdateRemainingDistance
: يتم استدعاؤها بشكل متكرّر مع تغيُّر المسافة إلى الوجهة التالية، وذلك أثناء نشاط التوجيه.-
GMSNavigatorListener.didUpdateDelayCategory
: يتم استدعاؤها عند تغيير فئة التأخير إلى الوجهة التالية، أثناء تفعيل التوجيه. - يتم تشغيل هذا الحدث عند تعديل ظروف الإضاءة المقدَّرة.
GMSNavigatorListener.didChangeSuggestedLightingMode
على سبيل المثال، عندما يحلّ الليل في الموقع الجغرافي الحالي للمستخدم، تتغيّر الإضاءة. GMSNavigatorListener.didUpdateSpeedingPercentage
، يتم تشغيلها عندما يتجاوز السائق حد السرعة.- يتم استدعاء
GMSRoadSnappedLocationProviderListener.didUpdateLocation
بشكل متكرّر عند تغيير الموقع الجغرافي للمستخدم.
الاطّلاع على الرمز
الإفصاح عن الالتزام بالبروتوكولات المطلوبة
قبل تنفيذ طرق التنقّل، يجب أن يتبنّى عنصر التحكّم في العرض البروتوكولات التالية:
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
على true:
Swift
mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true
Objective-C
_mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;
رصد أحداث الوصول
يستخدم تطبيقك الحدث didArriveAtWaypoint
لرصد الوقت الذي تم فيه الوصول إلى وجهة. يمكنك استئناف التوجيه والانتقال إلى نقطة الطريق التالية من خلال الاتصال بـ continueToNextDestination()
، ثم إعادة تفعيل التوجيه. يجب أن يعيد تطبيقك تفعيل التوجيه بعد استدعاء continueToNextDestination()
.
بعد أن يستدعي التطبيق continueToNextDestination
، لن يعود لدى أداة التنقّل أي بيانات حول الوجهة السابقة. إذا أردت تحليل معلومات حول جزء من مسار، عليك استرداد هذه المعلومات من أداة الملاحة قبل طلب continueToNextDestination()
.
يعرض مثال الرمز البرمجي التالي طريقة للتعامل مع حدث didArriveAtWaypoint
:
Swift
func navigator(_ navigator: GMSNavigator, didArriveAt waypoint:
GMSNavigationWaypoint) { print("You have arrived at: \(waypoint.title)")
mapView.navigator?.continueToNextDestination()
mapView.navigator?.isGuidanceActive = true }
Objective-C
- (void)navigator:(GMSNavigator *)navigator
didArriveAtWaypoint:(GMSNavigationWaypoint *)waypoint { NSLog(@"You have
arrived at: %@", waypoint.title); [_mapView.navigator
continueToNextDestination]; _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); }
تغيير وضع الإضاءة المقترَح
لتلقّي إشعارات بشأن التغييرات المقدَّرة في الإضاءة، أنشئ طريقة للتعامل مع حدث didChangeSuggestedLightingMode
.
Swift
// 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
// 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; }