التفاعل آليًا مع مكوّن التنقل

يوفّر مكوّن التنقّل طرقًا لإنشاء عناصر تنقّل معيّنة والتفاعل معها آليًا.

إنشاء NavHostFragment

يمكنك استخدام NavHostFragment.create() لإنشاء NavHostFragment آليًا باستخدام مورد رسم بياني محدّد، كما هو موضّح في المثال التالي:

Kotlin

val finalHost = NavHostFragment.create(R.navigation.example_graph)
supportFragmentManager.beginTransaction()
    .replace(R.id.nav_host, finalHost)
    .setPrimaryNavigationFragment(finalHost) // equivalent to app:defaultNavHost="true"
    .commit()

Java

NavHostFragment finalHost = NavHostFragment.create(R.navigation.example_graph);
getSupportFragmentManager().beginTransaction()
    .replace(R.id.nav_host, finalHost)
    .setPrimaryNavigationFragment(finalHost) // equivalent to app:defaultNavHost="true"
    .commit();

يُرجى العِلم أنّ "setPrimaryNavigationFragment(finalHost)" يتيح لـ "NavHost" اعتراض الضغطات على زر الرجوع في النظام. يمكنك أيضًا تنفيذ هذا السلوك في ملف XML الخاص بـ NavHost من خلال إضافة app:defaultNavHost="true". إذا كنت تنفّذ سلوكًا مخصّصًا لزر الرجوع ولا تريد أن يعترض NavHost الضغطات على زر الرجوع، يمكنك تمرير null إلى setPrimaryNavigationFragment().

بدءًا من الإصدار 2.2.0 من مكوّن Navigation، يمكنك الحصول على مرجع إلى NavBackStackEntry لأي وجهة في حزمة التنقّل من خلال استدعاء NavController.getBackStackEntry()، مع تمرير رقم تعريف الوجهة. إذا كانت الأنشطة السابقة تحتوي على أكثر من مثيل واحد للوجهة المحدّدة، تعرض الدالة getBackStackEntry() المثيل الأعلى من الأنشطة السابقة.

يوفّر عنصر NavBackStackEntry الذي يتم عرضه العناصر التالية على مستوى الوجهة:

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

تمنحك هذه السمات Lifecycle ومخزنًا لكائنات وفئات ViewModel التي تعمل مع الحالة المحفوظة بغض النظر عن نوع الوجهة التي تستخدمها.

وهذا مفيد بشكل خاص عند العمل مع أنواع الوجهات التي لا تحتوي تلقائيًا على Lifecycle مرتبط بها، مثل الوجهات المخصّصة.

على سبيل المثال، يمكنك مراقبة Lifecycle لـ NavBackStackEntry تمامًا كما تراقب Lifecycle لجزء أو نشاط. بالإضافة إلى ذلك، NavBackStackEntry هو LifecycleOwner، ما يعني أنّه يمكنك استخدامه عند مراقبة LiveData أو مع مكوّنات أخرى تدرك مراحل النشاط، كما هو موضّح في المثال التالي:

Kotlin

myViewModel.liveData.observe(backStackEntry, Observer { myData ->
    // react to live data update
})

Java

myViewModel.getLiveData().observe(backStackEntry, myData -> {
    // react to live data update
});

يتم تعديل حالة مراحل النشاط تلقائيًا عند طلب navigate(). تنتقل حالات مراحل النشاط للوجهات التي ليست في أعلى الأنشطة السابقة من RESUMED إلى STARTED إذا كانت الوجهات لا تزال مرئية ضمن وجهة FloatingWindow، مثل وجهة مربّع حوار، أو إلى STOPPED في الحالات الأخرى.

إعادة نتيجة إلى الوجهة السابقة

في الإصدار 2.3 من Navigation والإصدارات الأحدث، يتيح NavBackStackEntry الوصول إلى SavedStateHandle. ‫SavedStateHandle هي خريطة مفتاح/قيمة يمكن استخدامها لتخزين البيانات واستردادها. تستمر هذه القيم حتى بعد إيقاف العملية نهائيًا، بما في ذلك تغييرات الإعدادات، وتظل متاحة من خلال العنصر نفسه. باستخدام SavedStateHandle المحدّد، يمكنك الوصول إلى البيانات ونقلها بين الوجهات. وهذا مفيد بشكل خاص كآلية لاستعادة البيانات من وجهة بعد إزالتها من المكدس.

لتمرير البيانات مرة أخرى إلى الوجهة "أ" من الوجهة "ب"، قم أولاً بإعداد الوجهة "أ" للاستماع إلى نتيجة على SavedStateHandle. لإجراء ذلك، يمكنك استرداد NavBackStackEntry باستخدام واجهة برمجة التطبيقات getCurrentBackStackEntry() ثم observe LiveData المقدَّم من SavedStateHandle.

Kotlin

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    val navController = findNavController();
    // We use a String here, but any type that can be put in a Bundle is supported
    navController.currentBackStackEntry?.savedStateHandle?.getLiveData<String>("key")?.observe(
        viewLifecycleOwner) { result ->
        // Do something with the result.
    }
}

Java

@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    NavController navController = NavHostFragment.findNavController(this);
    // We use a String here, but any type that can be put in a Bundle is supported
    MutableLiveData<String> liveData = navController.getCurrentBackStackEntry()
            .getSavedStateHandle()
            .getLiveData("key");
    liveData.observe(getViewLifecycleOwner(), new Observer<String>() {
        @Override
        public void onChanged(String s) {
            // Do something with the result.
        }
    });
}

في الوجهة "ب"، عليك set النتيجة في SavedStateHandle الوجهة "أ" باستخدام واجهة برمجة التطبيقات getPreviousBackStackEntry().

Kotlin

navController.previousBackStackEntry?.savedStateHandle?.set("key", result)

Java

navController.getPreviousBackStackEntry().getSavedStateHandle().set("key", result);

إذا أردت معالجة نتيجة مرة واحدة فقط، عليك استدعاء remove() في SavedStateHandle لمحو النتيجة. إذا لم تتم إزالة النتيجة، سيواصل LiveData عرض النتيجة الأخيرة لأي مثيلات جديدة من Observer.

اعتبارات مهمة عند استخدام وجهات مربّعات الحوار

عند navigate إلى وجهة تشغل العرض الكامل لـ NavHost (مثل وجهة <fragment>)، يتم إيقاف دورة حياة الوجهة السابقة، مما يمنع أي عمليات استدعاء إلى LiveData المقدمة من SavedStateHandle.

ومع ذلك، عند الانتقال إلى وجهة مربّع حوار، تكون الوجهة السابقة مرئية أيضًا على الشاشة، وبالتالي تكون أيضًا STARTED على الرغم من أنّها ليست الوجهة الحالية. وهذا يعني أنّ طلبات getCurrentBackStackEntry() من داخل طرق مراحل النشاط، مثل onViewCreated()، ستعرض NavBackStackEntry لوجهة مربّع الحوار بعد تغيير الإعدادات أو إيقاف العملية نهائيًا وإعادة إنشائها (لأنّه تتم استعادة مربّع الحوار فوق الوجهة الأخرى). لذلك، عليك استخدام getBackStackEntry() مع رقم تعريف وجهتك لضمان استخدام NavBackStackEntry الصحيح دائمًا.

يعني هذا أيضًا أنّ أي Observer يتم ضبطه على النتيجة LiveData سيتم تفعيله حتى عندما تظل وجهات مربّع الحوار معروضة على الشاشة. إذا أردت التحقّق من النتيجة فقط عند إغلاق وجهة مربّع الحوار وتصبح الوجهة الأساسية هي الوجهة الحالية، يمكنك ملاحظة Lifecycle المرتبط بـ NavBackStackEntry واسترداد النتيجة فقط عندما يصبح RESUMED.

Kotlin

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    val navController = findNavController();
    // After a configuration change or process death, the currentBackStackEntry
    // points to the dialog destination, so you must use getBackStackEntry()
    // with the specific ID of your destination to ensure we always
    // get the right NavBackStackEntry
    val navBackStackEntry = navController.getBackStackEntry(R.id.your_fragment)

    // Create our observer and add it to the NavBackStackEntry's lifecycle
    val observer = LifecycleEventObserver { _, event ->
        if (event == Lifecycle.Event.ON_RESUME
            && navBackStackEntry.savedStateHandle.contains("key")) {
            val result = navBackStackEntry.savedStateHandle.get<String>("key");
            // Do something with the result
        }
    }
    navBackStackEntry.lifecycle.addObserver(observer)

    // As addObserver() does not automatically remove the observer, we
    // call removeObserver() manually when the view lifecycle is destroyed
    viewLifecycleOwner.lifecycle.addObserver(LifecycleEventObserver { _, event ->
        if (event == Lifecycle.Event.ON_DESTROY) {
            navBackStackEntry.lifecycle.removeObserver(observer)
        }
    })
}

Java

@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);
    NavController navController = NavHostFragment.findNavController(this);
    // After a configuration change or process death, the currentBackStackEntry
    // points to the dialog destination, so you must use getBackStackEntry()
    // with the specific ID of your destination to ensure we always
    // get the right NavBackStackEntry
    final NavBackStackEntry navBackStackEntry = navController.getBackStackEntry(R.id.your_fragment);

    // Create our observer and add it to the NavBackStackEntry's lifecycle
    final LifecycleEventObserver observer = new LifecycleEventObserver() {
        @Override
        public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
            if (event.equals(Lifecycle.Event.ON_RESUME)
                && navBackStackEntry.getSavedStateHandle().contains("key")) {
                String result = navBackStackEntry.getSavedStateHandle().get("key");
                // Do something with the result
            }
        }
    };
    navBackStackEntry.getLifecycle().addObserver(observer);

    // As addObserver() does not automatically remove the observer, we
    // call removeObserver() manually when the view lifecycle is destroyed
    getViewLifecycleOwner().getLifecycle().addObserver(new LifecycleEventObserver() {
        @Override
        public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
            if (event.equals(Lifecycle.Event.ON_DESTROY)) {
                navBackStackEntry.getLifecycle().removeObserver(observer)
            }
        }
    });
}

يخزّن سجلّ التنقّل NavBackStackEntry ليس فقط لكل وجهة فردية، بل أيضًا لكل رسم بياني رئيسي للتنقّل يحتوي على الوجهة الفردية. يتيح لك ذلك استرداد NavBackStackEntry يتم تحديد نطاقه في رسم بياني للتنقّل. يوفّر NavBackStackEntry ضمن نطاق الرسم البياني للتنقّل طريقة لإنشاء ViewModel ضمن نطاق الرسم البياني للتنقّل، ما يتيح لك مشاركة البيانات ذات الصلة بواجهة المستخدم بين وجهات الرسم البياني. Any ViewModel objects created in this way live until the associated NavHost and its ViewModelStore are cleared or until the navigation graph is popped from the back stack.

يوضّح المثال التالي كيفية استرداد ViewModel ضمن نطاق رسم بياني للتنقّل:

Kotlin

val viewModel: MyViewModel
        by navGraphViewModels(R.id.my_graph)

Java

NavBackStackEntry backStackEntry = navController.getBackStackEntry(R.id.my_graph);
MyViewModel viewModel = new ViewModelProvider(backStackEntry).get(MyViewModel.class);

إذا كنت تستخدم الإصدار 2.2.0 من Navigation أو إصدارًا أقدم، عليك توفير المصنع الخاص بك لاستخدام الحالة المحفوظة مع ViewModels، كما هو موضّح في المثال التالي:

Kotlin

val viewModel: MyViewModel by navGraphViewModels(R.id.my_graph) {
    SavedStateViewModelFactory(requireActivity().application, requireParentFragment())
}

Java

NavBackStackEntry backStackEntry = navController.getBackStackEntry(R.id.my_graph);

ViewModelProvider viewModelProvider = new ViewModelProvider(
        backStackEntry.getViewModelStore(),
        new SavedStateViewModelFactory(
                requireActivity().getApplication(), requireParentFragment()));

MyViewModel myViewModel = provider.get(myViewModel.getClass());

لمزيد من المعلومات حول ViewModel، يُرجى الاطّلاع على نظرة عامة على ViewModel.

تعديل الرسوم البيانية للتنقّل التي تم تضخيمها

يمكنك تعديل رسم بياني للتنقّل تم تضخيمه ديناميكيًا أثناء التشغيل.

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

لنفترض أنّك تملك NavGraph:

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/nav_graph"
    app:startDestination="@id/home">
    <fragment
        android:id="@+id/home"
        android:name="com.example.android.navigation.HomeFragment"
        android:label="fragment_home"
        tools:layout="@layout/fragment_home" />
    <fragment
        android:id="@+id/location"
        android:name="com.example.android.navigation.LocationFragment"
        android:label="fragment_location"
        tools:layout="@layout/fragment_location" />
    <fragment
        android:id="@+id/shop"
        android:name="com.example.android.navigation.ShopFragment"
        android:label="fragment_shop"
        tools:layout="@layout/fragment_shop" />
    <fragment
        android:id="@+id/settings"
        android:name="com.example.android.navigation.SettingsFragment"
        android:label="fragment_settings"
        tools:layout="@layout/fragment_settings" />
</navigation>

عند تحميل هذا الرسم البياني، تحدّد السمة app:startDestination أنّه سيتم عرض HomeFragment. لتجاوز وجهة البدء ديناميكيًا، قم بما يلي:

  1. أولاً، عليك نفخ NavGraph يدويًا.
  2. تجاوز الوجهة الأولى
  3. أخيرًا، أرفِق الرسم البياني يدويًا بـ NavController.

Kotlin

val navHostFragment =
        supportFragmentManager.findFragmentById(R.id.nav_host_fragment) as NavHostFragment

val navController = navHostFragment.navController
val navGraph = navController.navInflater.inflate(R.navigation.bottom_nav_graph)
navGraph.startDestination = R.id.shop
navController.graph = navGraph
binding.bottomNavView.setupWithNavController(navController)

Java

NavHostFragment navHostFragment = (NavHostFragment) getSupportFragmentManager()
        .findFragmentById(R.id.nav_host_fragment);

NavController navController = navHostFragment.getNavController();
NavGraph navGraph = navController.getNavInflater().inflate(R.navigation.bottom_nav_graph);
navGraph.setStartDestination(R.id.shop);
navController.setGraph(navGraph);
NavigationUI.setupWithNavController(binding.bottomNavView, navController);

الآن، عند بدء تشغيل تطبيقك، سيظهر ShopFragment بدلاً من HomeFragment.

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

يُرجى العِلم أنّ هذه الطريقة تتيح أيضًا إلغاء جوانب أخرى من NavGraph حسب الحاجة. يجب إجراء جميع التعديلات على الرسم البياني قبل استدعاء setGraph() لضمان استخدام البنية الصحيحة عند التعامل مع الروابط لصفحات معيّنة واستعادة الحالة والانتقال إلى وجهة البدء في الرسم البياني.