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

يمكن لتطبيقك الاستماع إلى الأحداث التي تحدث أثناء تنقّل المستخدم على طول مسار.

نظرة عامة

استخدِم الواجهات التالية للاستماع إلى أحداث التنقّل:

  • توفّر السمة Navigator.ArrivalListener وظيفة onArrival() التي يتم تشغيلها عند وصول الجهاز إلى وجهة.
  • توفّر RoadSnappedLocationProvider.LocationListener دالة معاودة الاتصال onLocationChanged() التي يتم تشغيلها عند تغيُّر الموقع الجغرافي للجهاز.
  • توفّر Navigator.RemainingTimeOrDistanceChangedListener وظيفة معاودة الاتصال onRemainingTimeOrDistanceChanged() التي يتم تشغيلها عندما يتغيّر الوقت أو المسافة إلى الوجهة التالية بمقدار أكبر من قيمة معيّنة.
  • توفّر Navigator.RouteChangedListener دالة رد الاتصال onRouteChanged() التي يتم تشغيلها عند تغيير المسار.

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

رصد الوصول إلى وجهة

تشير الوجهة هنا إلى وجهة نهائية أو نقطة توقّف. لرصد الوصول، اتّصِل بالدالة Navigator.addArrivalListener()، التي تسجّل دالة ردّ الاتصال عند وصول الجهاز إلى وجهة.

عند الوصول إلى نقطة الطريق، تنشئ حزمة تطوير البرامج للتنقّل على أجهزة Android الردّ onArrival()، الذي يمكن استخدامه بعد ذلك إما لإيقاف الإرشادات المفصّلة باستخدام Navigator.stopGuidance()، أو للانتقال إلى نقطة الطريق التالية باستخدام Navigator.continueToNextDestination(). إذا كانت جلسة التنقّل تتضمّن وجهة واحدة فقط، أو إذا لم تتبقَّ أي وجهات في قائمة الوجهات، سيؤدي طلب Navigator.continueToNextDestination() إلى إيقاف التوجيه تلقائيًا.

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

لتجنُّب تسرُّب الذاكرة، عليك استدعاء removeArrivalListener(listener) عندما لا تعود بحاجة إلى أداة معالجة الأحداث.

mNavigator.addArrivalListener(new Navigator.ArrivalListener() {
    @Override
    public void onArrival(ArrivalEvent arrivalEvent) {
        displayMessage("onArrival: You've arrived at a waypoint: "
                +   mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_BOTH);
        // Start turn-by-turn guidance for the next leg of the route.
        if (arrivalEvent.isFinalDestination()) {
            displayMessage("onArrival: You've arrived at the final destination.",
                    DISPLAY_BOTH);
        } else {
            mNavigator.continueToNextDestination();
            mNavigator.startGuidance();
        }
    }
});

تلقّي آخر المعلومات حول الموقع الجغرافي

احصل على RoadSnappedLocationProvider من NavigationApi، ثم اتّصِل بـ RoadSnappedLocationProvider.addLocationListener() للتسجيل لتلقّي ردّ عند تغيُّر الموقع الجغرافي للجهاز أو اتجاهه. يُرجى العِلم أنّ هذا الموقع الجغرافي يتم ضبطه على طريق، وبالتالي قد يختلف عن الموقع الجغرافي الذي يعرضه موفر الموقع الجغرافي المدمج في واجهات برمجة التطبيقات الخاصة بالموقع الجغرافي في "خدمات Google Play".

توفّر حزمة تطوير البرامج للتنقّل تحديثات الموقع الجغرافي بأسرع ما يمكن. عند توفّر تحديث للموقع الجغرافي، يستدعي Navigation SDK وظيفة onLocationChanged().

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

mRoadSnappedLocationProvider =
        NavigationApi.getRoadSnappedLocationProvider(getApplication());
if (mRoadSnappedLocationProvider != null) {
    mRoadSnappedLocationProvider.addLocationListener(
            new RoadSnappedLocationProvider.LocationListener() {
                @Override
                public void onLocationChanged(Location location) {
                    displayMessage("onLocationUpdated: Navigation engine has provided a new"
                                    +   " road-snapped location: "
                                    +   location.toString(),
                            DISPLAY_LOG);
                }
            });
} else {
    displayMessage("ERROR: Failed to get a location provider", DISPLAY_LOG);
}

تلقّي آخر المعلومات عن الوقت والمسافة

اتّصِل بالدالة Navigator.addRemainingTimeOrDistanceChangedListener() لتسجيل دالة معالجة سيتم استدعاؤها عند تغيُّر الوقت المتبقي (بالثواني) أو المسافة (بالأمتار) بمقدار أكبر من الحدّ المحدّد.

عندما يتجاوز التغيير في الوقت أو المسافة المقدار المحدّد، تنشئ حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation دالة معاودة الاتصال onRemainingTimeOrDistanceChanged().

للعثور على الوقت والمسافة المتبقّيَين، اتّصِل بالرقم Navigator.getTimeAndDistanceList(). يُرجى العِلم أنّ الأوقات والمسافات الواردة في القائمة تراكمية، أي أنّها تعرض الوقت والمسافة من الموقع الجغرافي الحالي إلى كل نقطة طريق، وليس من نقطة طريق إلى أخرى. يعرض الكائن TimeAndDistance الآن أيضًا delaySeverity. ستكون قيمة هذا التعداد الثابت إما heavy أو medium أو light أو unknown. يتوافق ذلك مع اللون الذي يظهر في واجهة المستخدم الخاصة بالوقت المقدّر للوصول في "خرائط Google" (ازدحام شديد = أحمر، ازدحام متوسط = أصفر، ازدحام خفيف = أخضر). يكون ذلك مفيدًا إذا كنت بحاجة إلى إنشاء تذييل خاص بك للإعلانات الموسّعة النصية.

لتجنُّب تسرُّب الذاكرة، عليك استدعاء Navigator.removeRemainingTimeOrDistanceChangedListener(listener) عندما لا تعود بحاجة إلى أداة معالجة الأحداث.

يطلب النموذج أدناه تنفيذ دالة ردّ الاتصال إذا تغيّر الوقت المتبقي بأكثر من 60 ثانية أو تغيّرت المسافة المتبقية بأكثر من 100 متر.

mNavigator.addRemainingTimeOrDistanceChangedListener(60, 100,
        new Navigator.RemainingTimeOrDistanceChangedListener() {
            @Override
            public void onRemainingTimeOrDistanceChanged() {
                displayMessage("onRemainingTimeOrDistanceChanged: Time or distance estimate"
                        +   " has changed.",
                        DISPLAY_LOG);
            }
        });

يمكنك عرض معلومات الوقت والمسافة المتبقّية باستخدام شاشة العرض المضمّنة باستخدام الطريقة setEtaCardEnabled() وتمرير مَعلمة بالقيمة TRUE. لإيقاف عرض الوقت والمسافة، اضبط هذه القيمة على FALSE.

يمكنك أيضًا عرض الوقت المقدَّر للوصول إلى نقاط طريق متعددة باستخدام الطريقة getTimeAndDistanceList().

تلقّي آخر المعلومات بشأن المسار

اتّصِل بالرقم Navigator.addRouteChangedListener() لتسجيل طلب معاودة الاتصال عند تغيير المسار.

عندما يتغيّر المسار، تنشئ حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation رد الاتصال onRouteChanged(). يمكنك الاتصال بـ Navigator.getRouteSegments وNavigator.getCurrentRouteSegment() للعثور على المسار الجديد.

لتجنُّب حدوث تسرُّب للذاكرة، عليك استدعاء removeRouteChangedListener(listener) عندما لا تعود بحاجة إلى أداة معالجة الأحداث.

mNavigator.addRouteChangedListener(new Navigator.RouteChangedListener() {
    @Override
    public void onRouteChanged() {
        displayMessage("onRouteChanged: The driver's route has changed. Current waypoint: "
                +   mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_LOG);
    }
});

رصد التغييرات في "الوضع الليلي"

اتّصِل NavigationView.addOnNightModeChangedListener أو SupportNavigationFragment.addOnNightModeChangedListener للتسجيل في خدمة معاودة الاتصال عند تغيير الوضع الليلي.

يعرض المثال التالي عملية الاستماع إلى تغييرات الوضع الداكن في جزء خاص بالتنقّل.

mNavFragment.addOnNightModeChangedListener(new NavigationView.OnNightModeChangedListener() {
    @Override
    public void onNightModeChanged(NightModeChangedEvent nightModeChangedEvent) {
        displayMessage("Night mode is active: " + nightModeChangedEvent.inNightMode(),
        DISPLAY_LOG);
    }
});

يمكنك أيضًا ضبط "الوضع الليلي" آليًا. لمزيد من المعلومات، يُرجى الاطّلاع على ضبط وضع الليل.