أفضل الممارسات المتعلّقة بالتفاعل مع خريطة التنقّل

توضّح هذه الصفحة أفضل الممارسات للتفاعل مع خريطة التنقّل في تطبيقك.

استخدِم NavigationFragment بدلاً من NavigationView متى أمكن ذلك

يغلّف NavigationFragment NavigationView ويتعامل تلقائيًا مع عمليات الاستدعاء في إحدى مراحل النشاط، لذا لن تحتاج إلى إدارتها بنفسك. هذه الطريقة أقل عرضة للأخطاء، وهي الطريقة التي ننصح بها لاستخدام التنقّل في تطبيقك. عند استخدام NavigationFragment، لا تستدعِ أحداث يتم في مراحل نشاط NavigationView مباشرةً.

في حال استخدام NavigationView، يجب استخدام ترتيب صارم عند استدعاء طرق مراحل النشاط

يستضيف NavigationView خريطة التنقّل ويتابع عن كثب الأحداث التي تتم في مراحل النشاط، مثل أنشطة Android وأجزاء Android، ويتّخذ إجراءات محدّدة عند استدعاء هذه الأحداث. ينفّذ NavigationView عمليات إعداد متعددة على NavigationView#onCreate وNavigationView#onStart، وعمليات تنظيف على NavigationView#onStop وNavigationView#onDestroy، بالإضافة إلى معالجة الأحداث الأخرى التي تتم في مراحل النشاط.

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

لمزيد من المعلومات حول مراحل نشاط Android، يُرجى الاطّلاع على قسم مفاهيم مراحل النشاط في مستندات مطوّري برامج Android.

يوضّح الجدول التالي الحالات التي يجب فيها استدعاء طرق مراحل النشاط الأخرى، بعد طرق مراحل النشاط المحدّدة:

لا تستدعِ طرق مراحل النشاط هذه عدة مرات بدون استدعاء طريقة الإغلاق المقابلة أولاً. بالإضافة إلى ذلك، يُرجى العِلم أنّه إذا كانت بعض عمليات الاستدعاء في إحدى مراحل النشاط على Android تتم إدارتها من خلال التطبيق نفسه، وتمت إضافة NavigationView إلى الجزء بعد الإنشاء أو البدء، يجب أن يستدعي التطبيق الطرق المحدّدة بالترتيب المناسب لإعداد حزمة تطوير البرامج (SDK) للتنقّل بشكل صحيح.

للحصول على إرشادات إضافية حول استخدام هذه الطرق، يمكنك الاطّلاع على التطبيق التجريبي لحزمة تطوير البرامج (SDK) للتنقّل.

في حال استخدام NavigationView، يجب استدعاء الأحداث التي تتم في مراحل النشاط من النشاط أو الجزء، وليس من كليهما

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

تعديل من SupportNavigationFragment إلى NavigationFragment

بدءًا من الإصدار 8.0.0 من حزمة تطوير البرامج (SDK) للتنقّل، يحلّ NavigationFragment محلّ SupportNavigationFragment الذي تم إيقافه نهائيًا كحاوية الأجزاء العادية للاتجاهات المفصّلة وعرض الخريطة.

NavigationFragment يحافظ على التكافؤ الكامل لواجهة برمجة التطبيقات مع SupportNavigationFragment. لتحديث تطبيقك، استبدِل SupportNavigationFragment بـ NavigationFragment في ملفات تنسيق XML وعمليات استيراد الرمز المصدر. وستبقى جميع توقيعات الطرق وطلبات getSupportFragmentManager() متطابقة.

تعديل ملف XML للتنسيق

استبدِل SupportNavigationFragment بـ NavigationFragment في ملفات XML الخاصة بالتنسيق:

قبل (الإصدار 7.x والإصدارات الأقدم):

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

بعد (الإصدار 8.0.0 والإصدارات الأحدث):

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

إذا كان تطبيقك يستخدم FragmentContainerView (يُنصح به لاستضافة الأجزاء)، يُرجى تعديل السمة android:name:

<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

تعديل الرمز البرمجي للتطبيق

استبدِل عمليات الاستيراد وتحويلات الفئات في رمز Java أو Kotlin. بما أنّ كلا الفئتَين توسّعان androidx.fragment.app.Fragment، يمكنك مواصلة استخدام getSupportFragmentManager() للبحث عن الجزء:

قبل (الإصدار 7.x والإصدارات الأقدم):

import com.google.android.libraries.navigation.SupportNavigationFragment;

public class MainActivity extends AppCompatActivity {
  private SupportNavigationFragment mNavFragment;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNavFragment = (SupportNavigationFragment) getSupportFragmentManager()
        .findFragmentById(R.id.navigation_fragment);
  }
}
    

import com.google.android.libraries.navigation.SupportNavigationFragment

class MainActivity : AppCompatActivity() {
  private lateinit var navFragment: SupportNavigationFragment

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    navFragment = supportFragmentManager
        .findFragmentById(R.id.navigation_fragment) as SupportNavigationFragment
  }
}
    

بعد (الإصدار 8.0.0 والإصدارات الأحدث):

import com.google.android.libraries.navigation.NavigationFragment;

public class MainActivity extends AppCompatActivity {
  private NavigationFragment mNavFragment;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNavFragment = (NavigationFragment) getSupportFragmentManager()
        .findFragmentById(R.id.navigation_fragment);
  }
}
    

import com.google.android.libraries.navigation.NavigationFragment

class MainActivity : AppCompatActivity() {
  private lateinit var navFragment: NavigationFragment

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    navFragment = supportFragmentManager
        .findFragmentById(R.id.navigation_fragment) as NavigationFragment
  }
}
    

تكافؤ واجهة برمجة التطبيقات

ولست بحاجة إلى إجراء أي تغييرات أخرى على السلوك أو إعادة هيكلة الرمز البرمجي. تتيح واجهة NavigationFragment استخدام جميع الطرق العامة وواجهات المستمعين وعناصر التحكّم المخصّصة في واجهة المستخدم من SupportNavigationFragment مع توقيعات طرق متطابقة (بما في ذلك getMapAsync() وgetNavigator() وsetEtaCardEnabled() وsetStylingOptions()).