به رویدادهای ناوبری گوش دهید

برنامه شما می‌تواند به رویدادهایی که هنگام پیمایش کاربر در طول یک مسیر رخ می‌دهند، گوش دهد.

نمای کلی

از رابط‌های زیر برای گوش دادن به رویدادهای ناوبری استفاده کنید:

  • Navigator.ArrivalListener تابع فراخوانی onArrival() را فراهم می‌کند که هنگام رسیدن دستگاه به مقصد فعال می‌شود.
  • RoadSnappedLocationProvider.LocationListener تابع فراخوانی onLocationChanged() را فراهم می‌کند که هنگام تغییر مکان دستگاه فعال می‌شود.
  • Navigator.RemainingTimeOrDistanceChangedListener تابع فراخوانی onRemainingTimeOrDistanceChanged() را فراهم می‌کند که زمانی که زمان یا مسافت تا مقصد بعدی بیش از مقدار مشخصی تغییر کند، فعال می‌شود.
  • Navigator.RouteChangedListener تابع فراخوانی onRouteChanged() را فراهم می‌کند که هنگام تغییر مسیر فعال می‌شود.

کد را ببینید

تشخیص رسیدن به مقصد

در اینجا، یک مقصد به یک مقصد نهایی یا یک نقطه‌ی بین‌راهی اشاره دارد. برای تشخیص رسیدن، Navigator.addArrivalListener() را فراخوانی کنید، که برای فراخوانی مجدد هنگام رسیدن دستگاه به مقصد ثبت می‌شود.

به محض رسیدن، کیت توسعه نرم‌افزار ناوبری اندروید (Navigation SDK) تابع فراخوانی onArrival() را اجرا می‌کند که می‌تواند برای متوقف کردن راهنمایی گام به گام با استفاده از Navigator.stopGuidance() یا پیشروی به نقطه مسیر بعدی با استفاده از Navigator.continueToNextDestination() استفاده شود. اگر جلسه ناوبری فقط شامل یک مقصد واحد باشد، یا اگر هیچ مقصدی در لیست مقصدها باقی نمانده باشد، فراخوانی Navigator.continueToNextDestination() به طور خودکار راهنمایی را متوقف می‌کند.

وقتی continueToNextDestination() را فراخوانی می‌کنید، ناوبر تمام اطلاعات مربوط به مقصد قبلی را کنار می‌گذارد. اگر می‌خواهید اطلاعات مربوط به بخش مسیر قبلی را تجزیه و تحلیل کنید، باید قبل از فراخوانی تابع continueToNextDestination() اطلاعات را از ناوبر بازیابی کنید.

برای جلوگیری از نشت حافظه، باید زمانی که دیگر به شنونده (listener) نیازی ندارید، تابع 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() را فراخوانی کنید تا در صورت تغییر مکان یا جهت دستگاه، برای یک فراخوانی مجدد ثبت نام کنید. توجه داشته باشید که این مکان به یک جاده متصل شده است و بنابراین ممکن است با مکانی که توسط ارائه دهنده مکان ادغام شده در APIهای مکان سرویس‌های Google Play برگردانده می‌شود، متفاوت باشد.

کیت توسعه نرم‌افزار ناوبری (Navigation SDK) تا حد امکان به‌روزرسانی‌های موقعیت مکانی را ارائه می‌دهد. هنگامی که به‌روزرسانی موقعیت مکانی در دسترس باشد، کیت توسعه نرم‌افزار ناوبری (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() را فراخوانی کنید.

وقتی تغییر در زمان یا مسافت از مقدار مشخص شده بیشتر شود، Navigation SDK تابع onRemainingTimeOrDistanceChanged() را فراخوانی می‌کند.

برای یافتن زمان و مسافت باقی‌مانده، تابع Navigator.getTimeAndDistanceList() را فراخوانی کنید. توجه داشته باشید که زمان‌ها و مسافت‌های موجود در لیست تجمعی هستند: آن‌ها زمان و مسافت را از موقعیت فعلی تا هر نقطه مسیر نشان می‌دهند، نه از یک نقطه مسیر تا نقطه مسیر دیگر. شیء TimeAndDistance اکنون delaySeverity نیز برمی‌گرداند. این enum می‌تواند heavy، meduim، light یا unknown باشد. این مربوط به رنگی است که در رابط کاربری نقشه روی eta می‌بینید (heavy = red، medium = yellow، light = green). این در صورتی که نیاز به ایجاد پاورقی eta خود دارید، مفید است.

برای جلوگیری از نشت حافظه، باید وقتی دیگر به شنونده Navigator.removeRemainingTimeOrDistanceChangedListener(listener) را فراخوانی کنید.

نمونه زیر در صورتی که زمان باقیمانده بیش از ۶۰ ثانیه یا مسافت باقیمانده بیش از ۱۰۰ متر تغییر کند، درخواست فراخوانی مجدد می‌دهد.

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() زمان تقریبی رسیدن به مقصد (ETA) را برای چندین نقطه‌ی مسیر نمایش دهید.

دریافت به‌روزرسانی‌های مسیر

برای ثبت یک فراخوانی برگشتی هنگام تغییر مسیر، تابع Navigator.addRouteChangedListener() را فراخوانی کنید.

وقتی مسیر تغییر می‌کند، Navigation SDK تابع onRouteChanged() را فراخوانی می‌کند. می‌توانید Navigator.getRouteSegments و Navigator.getCurrentRouteSegment() برای یافتن مسیر جدید فراخوانی کنید.

برای جلوگیری از نشت حافظه، باید زمانی که دیگر به شنونده (listener) نیازی ندارید، تابع 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);
    }
});

همچنین می‌توانید حالت شب را به صورت برنامه‌نویسی شده تنظیم کنید. برای اطلاعات بیشتر، به بخش تنظیم حالت شب مراجعه کنید.