دليل نقل البيانات

تحذير: قد يحتوي هذا المستند على معلومات قديمة. نعمل على حلّ هذه المشكلة، ولكن ننصحك بإلقاء نظرة على صفحة البدء في هذه الأثناء للاطّلاع على نماذج التطبيقات التي نوفّرها. وتعرض سلوكيات وأنماط استخدام واجهة برمجة التطبيقات التي تساعدك في الانتقال من الإصدار 1.

إنّ أكبر تغيير أجرته Google على حزمة تطوير البرامج (SDK) الخاصة بميزة التنقّل في الإصدار الثاني هو أننا استبدلنا العديد من فئات حزمة تطوير البرامج (SDK) للتنقّل بنظيراتها من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android.

اعتبارًا من الإصدار 2.2، ستصبح "حزمة تطوير البرامج (SDK) للتنقل" بديلاً (تقريبًا) لـ "واجهة برمجة التطبيقات لخرائط خدمات Google Play". وبدلاً من إعادة تجميع جميع واجهات برمجة التطبيقات في com.google.android.libraries.maps، يتم تجميعها في com.google.android.gms.maps تمامًا مثل "خدمات Google Play". وهذا يجعل التبديل بين إصدار "خدمات Google Play" وحزمة "SDK للتنقل" أسهل بكثير.

تحذير: هذه التعليمات صالحة فقط للإصدار 2.2 والإصدارات الأحدث.

المزايا

• استخدام أفضل للذاكرة. يتم الآن استهلاك قدر أقل من الذاكرة والنطاق الترددي مقارنة بما إذا كنت تستخدم كلاً من حزمة تطوير البرامج (SDK) للتنقّل وحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.
• يمكنك الآن التبديل من وضع "عرض الخريطة" إلى وضع التنقّل بشكل أكثر سلاسة وسهولة في العمل.
• يمكنك الآن التحكّم بشكل أكبر في الكاميرا.
• يمكنك الآن تنفيذ إجراءات مثل رسم خطوط متعدّدة وتراكبات وإضافة أنماط مخصّصة إلى الخريطة.

ومع ذلك، لا تتوفر ميزات مثل "التجوّل الافتراضي" و"الوضع البسيط".

نقطة رئيسية: ستحلّ حزمة تطوير البرامج (SDK) الخاصة بالتنقل محلّ حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android وستحتاج إلى إزالة أي مراجع للعميل.

المتطلبات الأساسية

• يستخدم الإصدار 2 من حزمة SDK للتنقل باستخدام Android Jetpack، وهو مجموعة من المكتبات والأدوات والإرشادات التي تسهّل كتابة التطبيقات العالية الجودة. وتعني هذه الخطوة أنّه يجب عليك نقل تطبيقك من استخدام مكتبات الدعم إلى استخدام AndroidX. لمزيد من المعلومات، يمكنك الاطّلاع على نقل البيانات إلى AndroidX.

الخطوة 1. نقل البيانات من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android

تم تضمين معظم الوظائف في حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android الآن في الإصدار 2 من حزمة SDK للتنقل. تمت إزالة بعض الميزات لأنها لم تكن مطلوبة في سياق التنقل.

اختلافات مهمة

كانت حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android متوفّرة في "خدمات Google Play".

تعتمد ميزات حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android المضمّنة في الإصدار 2 من حزمة تطوير البرامج (SDK) الخاصة بالتنقل على الإصدار الجديد من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android، ولا تتوفّر في "خدمات Google Play". يتم تشغيل هذه الميزات الجديدة على محرك أحدث من محرك البحث المخصص لخدمات Google Play، وهي تخضع للعديد من التحسينات. ويعني ذلك أيضًا أنّ الخريطة يتم تنفيذها ضمن عملية تطبيقك، وليس في عملية "خدمات Google Play".

تمت إعادة تسمية بعض الصفوف.

يعرض الجدول التالي الصفوف التي تمت إعادة تسميتها. وقد تم تنفيذ ذلك للتفريق بينها وبين نظيرتها في حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" على أجهزة Android.

اسم صف "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android	اسم فئة حزمة تطوير البرامج (SDK) للتنقّل
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

تحتوي هذه الصفوف على مزيج من الطرق المتاحة في فئة NavigationView القديمة وفئة MapView الحالية. ويمكنك اعتبارها على غرار الصفَّين MapView وMapFragment، ولكن مع إتاحة التنقّل.

الميزات التي تمت إزالتها

تمت إزالة بعض ميزات "خرائط Google" لأنّها لم تكن منطقية في سياق التنقّل أو بسبب عدم التوافق الفني. تشمل الميزات التي تمت إزالتها ما يلي:

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

خطوات نقل البيانات

1. أزِل دمج حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android من تصميمك (أي gradle). سيؤدي توفُّر حزمتَي تطوير البرامج (SDK) إلى حدوث أخطاء في التجميع.
2. استبدِل MapView بمثيلات NavigationView.
3. استبدِل MapFragment بمثيلات NavigationSupportFragment.

إذا لم يكن تطبيقك يستخدم حزمة SDK للتنقل في السابق، يعني ذلك أنّ عملية نقل البيانات قد اكتملت.

الخطوة 2. نقل البيانات من الإصدار 1.x من حزمة تطوير البرامج (SDK) الخاصة بالتنقل

نفِّذ الخطوات التالية لنقل دمج الإصدار 1.x من حزمة SDK الخاصة بالتنقل إلى الإصدار 2.

1- الحصول على الخريطة باستخدام طرق جديدة

لقد تغيرت طريقة الحصول على خريطة. قبل الإصدار 2، كانت الخريطة تحصل على الخريطة باستخدام مكالمة متزامنة. الآن، ستستخدم مكالمة غير متزامنة. يسرد الجدول التالي الطرق القديمة إلى جانب الأساليب الجديدة للحصول على الخريطة.

الطريقة القديمة	طريقة جديدة
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

ملاحظة: تمت إزالة الصف NavigationFragment لأنّه تم إيقاف الفئة Fragment نهائيًا لصالح الفئة SupportFragment.

2- نقل المكتبات

احتوى الإصدار 1.x من حزمة SDK الخاصة بالتنقل على تنفيذه لالعديد من صفوف SDK لـ "خرائط Google" لتطبيقات Android. كانت هذه الصفوف ضمن حزمة com.google.android.libraries.navigation.

وقد تم استبدال هذه الفئات بحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android التي تندرج ضمن حزمة com.google.android.gms.maps.model، وذلك في الإصدار 2. يمكنك نقل تطبيقك لدمج الفئات الجديدة من خلال إجراء بحث واستبدال.

يسرد الجدول التالي الفئات القديمة مع الفئات الجديدة.

صف قديم	صف جديد
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- دمج التغييرات التي تطرأ على واجهات برمجة التطبيقات الحالية

يسرد الجدول التالي التغييرات الرئيسية التي أجرتها Google للإصدار 2 من حزمة SDK للتنقل.

الطريقة	تغيير
NavigationApi.cleanup()	تمّت إزالة الموضوع. لم يتم استخدام هذه الطريقة للتشغيل العادي، ويمكن أن يؤدي ذلك إلى سلوك غير متوقّع. يجب إزالة الطلبات لهذه الطريقة.
RoadSnappedLocationProvider.requestLocationUpdates()	تمّت إزالة الموضوع. يمكنك استخدام addLocationListener() كبديل.
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	تمّت إزالة الموضوع. يمكنك استخدام removeLocationListener() كبديل.

4. التغيير إلى فئة "محدِّد العلامة" الجديدة

يستخدم الإصدار الثاني من حزمة تطوير البرامج (SDK) الخاصة بالتنقل الآن تنفيذ فئة Marker نفسه مثل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android. يقدم هذا التغييرات التالية.

الطُرق ذات الصلة بالعلامات

الطريقة	تغيير
addMarker(MarkerOptions markerOptions)	تستخدم الآن الفئة com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	لم تعد هذه الطريقة موجودة. بدلاً من ذلك، أصبحت فئة "أداة العلامة" الآن تتضمّن طريقة marker.remove().
removeAllMarkers()	لم تعُد هذه الطريقة متاحة، ولكن تتوفّر طريقة clear() لإزالة جميع العلامات والخطوط المتعددة والمضلعات والتراكبات من الخريطة.

الاختلافات في MarkerOptions

• لا تتوفر الطريقة describeContents() في الإصدار 2 من حزمة تطوير البرامج (SDK) للتنقل. لقد سمحت لك هذه الخدمة بحفظ بيانات العرض من خلال طلب الرقم onSaveInstanceState(). أصبح عليك الآن تتبّع تفاصيل العرض بنفسك لتتمكن من إعادة إنشاء العرض عند حدوث تغيير في الإعدادات.
• تم تغيير الطريقة navMarker#icon(BitMap) إلى mapMarker#icon(BitmapDescriptor). يتطلب هذا التغيير منك الانتقال من استخدام BitMap إلى استخدام BitmapDescriptor.

الطرق المتعلقة بالعلامات

ستستخدم الآن الفئة Marker من حزمة com.google.android.gms.maps.model. يسرد الجدول التالي الاختلافات في استخدام فئة Marker الجديدة هذه.

الطريقة	تغيير
getAnchorU()	لم يعد موجودًا.
getAnchorV()	لم يعد موجودًا.
getIcon()	لم تعُد متوفّرة. يجب الاحتفاظ بمرجع خاص بالرمز بنفسك، لاستخدامه بعد تغيير الإعدادات، عندما تحتاج إلى إعادة إنشاء حالة الخريطة.
getPosition()	لا يزال متوفرًا.
getTitle()	لا يزال متوفرًا.

ملاحظة: إذا كنت بحاجة إلى استخدام الطُرق التي تمت إزالتها في فئة "أداة العلامة"، يُرجى إعلامنا بذلك لنتمكّن من مساعدتك في حلّ مشكلتك.

5- التحكّم في الكاميرا

كانت عناصر التحكم في الكاميرا المتوفرة في الإصدار 1.x من حزمة SDK للتنقل محدودة نسبيًا. يستخدم الإصدار 2 من حزمة تطوير البرامج (SDK) للتنقل نفس طراز الكاميرا الذي تستخدمه حزمة SDK لتطبيق "خرائط Google" لنظام التشغيل Android، إلا أنك تحصل أيضًا على وضع متابعة مشابه لذلك في الإصدار 1.x من حزمة 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. دمج تدفقات النشاط

إذا كنت تستخدم الإصدار الأول من حزمة SDK للتنقل واتّباع التعليمات أعلاه، عليك نقل حالات استخدام الخريطة لاستخدام الفئة NavigationView، كما سيتم نقل حالات استخدام التنقّل لاستخدام GoogleMap. ومع ذلك، سيكون لديك مثيلان من GoogleMap ومثيلَين من NavigationView. يعني ذلك أنّك ستظل تستخدم ذاكرة أكبر من اللازم، ويمكن أن يؤدي التبديل بين المثيلَين إلى توقف مؤقت ملموس في العرض السلس لواجهة المستخدم. لحل هذه المشكلة، يجب عليك دمج تدفقات النشاط/الجزء بحيث يمكنهما مشاركة مثيل واحد. يوفر هذا تجربة مستخدم أكثر سلاسة ويبسط تطبيقك.