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

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

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

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

في حال استخدام NavigationView، استخدِم ترتيبًا صارمًا عند استدعاء طرق دورة الحياة

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

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

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

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

طريقة مراحل النشاط يتم استدعاؤها في أي مرحلة من مراحل نشاط التطبيق يتم استدعاء هذه الطريقة بعد طريقة دورة الحياة التالية
onConfigurationChanged() يتم استدعاؤه عندما تكون واجهة المستخدم في المقدّمة وتتغير الإعدادات. دائمًا بعد onStart()
onTrimMemory() يتم استدعاؤه عندما يكون النشاط في الخلفية. دائمًا بعد onPause()
onSaveInstance() يتم استدعاؤها قبل إيقاف نشاط. دائمًا بعد onStop()

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

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

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

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

تحديث من SupportNavigationFragment إلى NavigationFragment

بدءًا من الإصدار 8.0.0 من حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation، يحلّ 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);
  }
}

Kotlin

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);
  }
}

Kotlin

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()).