يوفّر مكوّن التنقّل طرقًا لإنشاء عناصر تنقّل معيّنة والتفاعل معها آليًا.
إنشاء 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().
الإشارة إلى وجهة باستخدام NavBackStackEntry
بدءًا من الإصدار 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)
}
}
});
}
مشاركة البيانات ذات الصلة بواجهة المستخدم بين الوجهات باستخدام ViewModel
يخزّن سجلّ التنقّل 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. لتجاوز وجهة البدء
ديناميكيًا، قم بما يلي:
- أولاً، عليك نفخ
NavGraphيدويًا. - تجاوز الوجهة الأولى
- أخيرًا، أرفِق الرسم البياني يدويًا بـ
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() لضمان استخدام البنية الصحيحة
عند التعامل مع الروابط لصفحات معيّنة واستعادة الحالة والانتقال إلى وجهة
البدء في الرسم البياني.