راهنمای مهاجرت، راهنمای مهاجرت، راهنمای مهاجرت

بزرگترین تغییری که Google در Navigation SDK نسخه 2 ایجاد کرد این است که ما چندین کلاس Navigation SDK را با همتایان آنها از Maps SDK برای Android جایگزین کردیم.

از نسخه 2.2، Navigation SDK یک جایگزین (تقریباً) کشویی برای Google Play Services Maps API است. به جای بسته بندی مجدد همه APIها در com.google.android.libraries.maps، آنها در com.google.android.gms.maps مانند خدمات Google Play بسته بندی شده اند. این امر جابجایی بین نسخه Google Play Services و Navigation SDK را بسیار ساده تر می کند.

فواید

  • استفاده بهتر از حافظه اکنون نسبت به زمانی که از Navigation SDK و Maps SDK برای Android استفاده می‌کنید، از حافظه و پهنای باند کمتری استفاده می‌کنید.
  • جابجایی از حالت نمای نقشه به حالت ناوبری اکنون روان‌تر و کار کردن با آن آسان‌تر است.
  • اکنون کنترل بیشتری بر دوربین دارید.
  • اکنون می توانید کارهایی مانند ترسیم چند خطوط و همپوشانی و اضافه کردن سبک های سفارشی به نقشه انجام دهید.

با این حال، ویژگی‌هایی مانند نمای خیابان و حالت ساده پشتیبانی نمی‌شوند.

پیش نیازها

  • نسخه 2 Navigation SDK از Android Jetpack استفاده می کند — مجموعه ای از کتابخانه ها، ابزارها و راهنمایی که نوشتن برنامه های با کیفیت بالا را آسان تر می کند. این حرکت به این معنی است که باید برنامه خود را از استفاده از کتابخانه های پشتیبانی برای استفاده از AndroidX منتقل کنید. برای اطلاعات بیشتر، مهاجرت به AndroidX را ببینید.

مرحله 1. از Maps SDK برای Android مهاجرت کنید

اکثر قابلیت‌های Maps SDK برای Android اکنون در نسخه 2 Navigation SDK گنجانده شده است. چند ویژگی حذف شدند زیرا در زمینه ناوبری مورد نیاز نبودند.

تفاوت های مهم

Maps SDK برای اندروید در Google Play Services بود.
ویژگی‌های Maps SDK برای Android که در نسخه ۲ Navigation SDK ارائه شده‌اند، بر اساس نسخه جدید Maps SDK برای Android هستند و در خدمات Google Play نیستند. این ویژگی‌های جدید بر روی موتور جدیدتر از موتور Google Play Services اجرا می‌شوند و چندین پیشرفت دارند. همچنین به این معنی است که نقشه در فرآیند برنامه شما اجرا می شود، نه در فرآیند Google Play Service.
برخی از کلاس ها تغییر نام دادند
جدول زیر کلاس هایی را که تغییر نام داده اند فهرست می کند. این کار برای متمایز کردن آنها از Maps SDK برای همتای اندرویدی آنها انجام شد.
Maps SDK برای نام کلاس Android نام کلاس SDK پیمایش
MapView.java NavigationView.java
MapFragment.java SupportNavigationFragment.java
این کلاس ها حاوی ترکیبی از روش های موجود در کلاس NavigationView قدیمی و کلاس MapView فعلی هستند. می توانید آنها را مانند کلاس های MapView و MapFragment در نظر بگیرید، اما با پشتیبانی ناوبری.
ویژگی های حذف شده
برخی از ویژگی‌های Maps به دلیل معنی نداشتن در زمینه ناوبری یا ناسازگاری‌های فنی حذف شدند. ویژگی های حذف شده عبارتند از:
  • نمای خیابان.
  • حالت Lite که برای پیمایش کافی نیست.
  • وقتی دوربین در حالت دنبال کردن است، نمی توانید LocationProvider تنظیم کنید. این به این دلیل است که پیمایش به RoadSnappedLocationProvider متکی است و جابه‌جایی به این ارائه‌دهنده می‌تواند هنگام پیمایش مشکلاتی ایجاد کند.
  • اعمال زوم حداقل/حداکثر و مرزهای LatLng زمانی که دوربین در حالت فالو است هیچ تاثیری ندارد.
  • اگر این ویژگی های از دست رفته برای شما مشکل ایجاد می کند، لطفاً با نماینده مشتری خود صحبت کنید.

مراحل مهاجرت

  1. Maps SDK برای ادغام اندروید را از ساخت خود (یعنی gradle) حذف کنید. داشتن هر دو SDK باعث ایجاد خطاهای کامپایل می شود.
  2. نمونه های MapView را با نمونه هایی از NavigationView جایگزین کنید.
  3. نمونه‌های MapFragment را با نمونه‌هایی از NavigationSupportFragment جایگزین کنید.

اگر برنامه شما قبلاً از Navigation SDK استفاده نمی کرد، انتقال شما کامل شده است.

مرحله 2. از v1.x از Navigation SDK مهاجرت کنید

مراحل زیر را برای انتقال ادغام v1.x از Navigation SDK به نسخه 2 انجام دهید.

1. نقشه را با استفاده از روش های جدید دریافت کنید

روش دریافت نقشه تغییر کرده است. قبل از نسخه 2، نقشه را با استفاده از تماس همزمان دریافت کردید. اکنون از تماس ناهمزمان استفاده خواهید کرد. جدول زیر روش های قدیمی را به همراه روش های جدید برای گرفتن نقشه فهرست می کند.

روش قدیمی روش جدید
NavigationView.getMap() NavigationView.getMapAsync()
SupportNavigationFragment.getMap() SupportNavigationFragment.getMapAsync()

2. کتابخانه ها را مهاجرت کنید

v1.x از Navigation SDK شامل پیاده‌سازی خود از چندین Maps SDK برای کلاس‌های Android بود. این کلاس ها متعلق به بسته com.google.android.libraries.navigation بودند.

در نسخه ۲، این کلاس‌ها با Maps SDK برای پیاده‌سازی‌های اندروید جایگزین شده‌اند که در بسته com.google.android.gms.maps.model قرار دارند. می توانید با انجام جستجو و جایگزینی، برنامه خود را برای ادغام کلاس های جدید انتقال دهید.

جدول زیر کلاس های قدیمی را به همراه کلاس های جدید فهرست می کند.

کلاس قدیمی کلاس جدید
com.google.android.libraries.navigation.LatLng com.google.android.gms.maps.model.LatLng
com.google.android.libraries.navigation.LatLngBounds com.google.android.gms.maps.model.LatLngBounds
com.google.android.libraries.navigation.Marker com.google.android.gms.maps.model.Marker
com.google.android.libraries.navigation.MarkerOptions com.google.android.gms.maps.model.MarkerOptions
com.google.android.libraries.navigation.VisibleRegion com.google.android.gms.maps.model.VisibleRegion

3. تغییرات APIهای موجود را بپذیرید

جدول زیر تغییرات کلیدی را که گوگل برای نسخه 2 Navigation SDK انجام داده است فهرست می کند.

روش تغییر دادن
NavigationApi.cleanup() حذف شده. این روش برای عملکرد عادی استفاده نمی شود و می تواند باعث رفتار غیرقابل پیش بینی شود. شما باید تماس های این روش را حذف کنید.
RoadSnappedLocationProvider.requestLocationUpdates() حذف شده. به جای آن addLocationListener() استفاده کنید.
RoadSnappedLocationProvider.stopRequestingLocationUpdates() حذف شده. به جای آن از removeLocationListener() استفاده کنید.

4. به کلاس Marker جدید تغییر دهید

نسخه ۲ از Navigation SDK اکنون از همان پیاده‌سازی کلاس Marker به عنوان Maps SDK برای اندروید استفاده می‌کند. این تغییرات زیر را معرفی می کند.

روش تغییر دادن
addMarker(MarkerOptions markerOptions) اکنون از کلاس com.google.android.gms.maps.model.MarkerOptions استفاده می کند.
removeMarker(Marker marker) این روش دیگر وجود ندارد. در عوض، کلاس Marker اکنون یک متد marker.remove() دارد.
removeAllMarkers() این روش دیگر وجود ندارد، اگرچه یک متد clear() وجود دارد که همه نشانگرها، چند خط ها، چند ضلعی ها و همپوشانی ها را از نقشه حذف می کند.

تفاوت های MarkerOptions

  • متد describeContents() در نسخه ۲ از Navigation SDK وجود ندارد. به شما این امکان را می دهد که داده های view را با فراخوانی onSaveInstanceState() ذخیره کنید. اکنون، باید جزئیات نما را خودتان پیگیری کنید تا بتوانید در صورت تغییر پیکربندی، نما را بازسازی کنید.
  • روش navMarker#icon(BitMap) به mapMarker#icon(BitmapDescriptor) تغییر کرده است. این تغییر مستلزم آن است که از BitMap برای استفاده از BitmapDescriptor مهاجرت کنید.

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

اکنون از کلاس Marker از بسته com.google.android.gms.maps.model استفاده خواهید کرد. جدول زیر تفاوت های استفاده از این کلاس Marker جدید را فهرست می کند.

روش تغییر دادن
getAnchorU() دیگر موجود نیست.
getAnchorV() دیگر موجود نیست.
getIcon() دیگر موجود نیست.
برای استفاده پس از تغییر پیکربندی، زمانی که نیاز به ایجاد مجدد وضعیت نقشه دارید، باید خودتان یک مرجع به نماد حفظ کنید.
getPosition() هنوز وجود دارد.
getTitle() هنوز وجود دارد.

5. کنترل دوربین

کنترل های دوربین ارائه شده در v1.x از Navigation SDK نسبتاً محدود بود. نسخه 2 Navigation SDK اکنون از همان مدل دوربین استفاده شده توسط Maps SDK برای اندروید استفاده می کند، با این تفاوت که شما همچنین یک حالت Follow مشابه حالت نسخه 1.x از Navigation SDK دریافت می کنید.

تفاوت های کلیدی

  • کلاس com.google.android.libraries.navigation.Camera در نسخه 2 حذف شد.
    • Camera.showRouteOverview() به NavigationView و SupportNavigationFragment منتقل شد.
    • روش Camera.followMyLocation() به GoogleMap منتقل شد.
  • می‌توانید تماس‌های Camera.setLocation() را با GoogleMap.moveCamera() یا GoogleMap.animateCamera() جایگزین کنید.
  • setOnFollowMyLocationCallback() و isCameraFollowingMyLocation() به GoogleMap اضافه شدند تا اطلاعات بیشتری در مورد حالت دنبال کردن ارائه کنند.

مرحله 3. ادغام جریان های فعالیت

اگر قبلاً از V1 Navigation SDK استفاده می‌کردید و دستورالعمل‌های بالا را دنبال می‌کردید، موارد استفاده از نقشه خود را برای استفاده از کلاس NavigationView و موارد استفاده ناوبری خود را برای استفاده از GoogleMap منتقل می‌کنید. با این حال، دو نمونه از GoogleMap و دو نمونه از NavigationView خواهید داشت. این بدان معنی است که شما همچنان از حافظه بیشتری نسبت به مقدار لازم استفاده خواهید کرد و جابجایی بین دو نمونه می تواند منجر به مکث های محسوس در ارائه نرم افزار رابط کاربری شود. برای حل این مشکل، باید جریان‌های فعالیت/بخش خود را ادغام کنید تا بتوانند یک نمونه واحد را به اشتراک بگذارند. این یک تجربه کاربری روانتر را فراهم می کند و برنامه شما را ساده می کند.