توسّع مكتبة Dynamic Navigator وظائف مكوّن التنقّل في Jetpack للعمل مع الوجهات المحدّدة في وحدات الميزات. توفّر هذه المكتبة أيضًا تثبيتًا سلسًا لوحدات الميزات عند الطلب عند الانتقال إلى هذه الوجهات.
الإعداد
لإتاحة وحدات الميزات، استخدِم الاعتماديات التالية في ملف build.gradle الخاص بوحدة تطبيقك:
Groovy
dependencies { def nav_version = "2.10.2" api "androidx.navigation:navigation-fragment-ktx:$nav_version" api "androidx.navigation:navigation-ui-ktx:$nav_version" api "androidx.navigation:navigation-dynamic-features-fragment:$nav_version" }
Kotlin
dependencies { val nav_version = "2.10.2" api("androidx.navigation:navigation-fragment-ktx:$nav_version") api("androidx.navigation:navigation-ui-ktx:$nav_version") api("androidx.navigation:navigation-dynamic-features-fragment:$nav_version") }
يُرجى العِلم أنّ تبعيات Navigation الأخرى يجب أن تستخدم إعدادات api لتكون متاحة لوحدات الميزات.
الاستخدام الأساسي
لإتاحة وحدات الميزات، عليك أولاً تغيير جميع حالات
NavHostFragment في تطبيقك إلى
androidx.navigation.dynamicfeatures.fragment.DynamicNavHostFragment:
<androidx.fragment.app.FragmentContainerView
android:id="@+id/nav_host_fragment"
android:name="androidx.navigation.dynamicfeatures.fragment.DynamicNavHostFragment"
app:navGraph="@navigation/nav_graph"
... />
بعد ذلك، أضِف سمة app:moduleName إلى أي وجهات <activity> أو <fragment> أو <navigation> في الرسوم البيانية للتنقّل في وحدة com.android.dynamic-feature المرتبطة بـ DynamicNavHostFragment.
تُعلم هذه السمة مكتبة Dynamic Navigator بأنّ الوجهة تنتمي إلى وحدة ميزات بالاسم الذي تحدّده.
<fragment
app:moduleName="myDynamicFeature"
android:id="@+id/featureFragment"
android:name="com.google.android.samples.feature.FeatureFragment"
... />
عند الانتقال إلى إحدى هذه الوجهات، تتحقّق مكتبة Dynamic Navigator أولاً مما إذا كانت وحدة الميزات مثبّتة. إذا كانت وحدة الميزات متوفّرة، سينتقل تطبيقك إلى الوجهة على النحو المتوقّع. إذا لم تكن الوحدة متوفّرة، يعرض تطبيقك وجهة جزء تقدّم وسيطة أثناء تثبيت الوحدة. يعرض التنفيذ التلقائي لجزء التقدّم واجهة مستخدم أساسية مع شريط تقدّم ويعالج أي أخطاء في التثبيت.
لتخصيص واجهة المستخدم هذه أو التعامل يدويًا مع مستوى تقدّم عملية التثبيت من داخل شاشة تطبيقك، يُرجى الاطّلاع على قسمَي تخصيص جزء مستوى التقدّم ومراقبة حالة الطلب في هذا الموضوع.
أما الوجهات التي لا تحدّد app:moduleName، فستستمر في العمل بدون تغييرات وتعمل كما لو أنّ تطبيقك يستخدم NavHostFragment عاديًا.
تخصيص جزء التقدم
يمكنك إلغاء تنفيذ جزء التقدم لكل رسم بياني للتنقل
عن طريق تعيين السمة app:progressDestination على معرّف الوجهة
التي تريد استخدامها للتعامل مع تقدم التثبيت. يجب أن تكون وجهة التقدّم المخصّصة Fragment مشتقة من AbstractProgressFragment. يجب إلغاء الطرق المجرّدة لتلقّي إشعارات حول مستوى تقدّم عملية التثبيت والأخطاء والأحداث الأخرى. ويمكنك بعد ذلك عرض مستوى تقدُّم عملية التثبيت في واجهة مستخدم من اختيارك.
تستخدم فئة DefaultProgressFragment في عملية التنفيذ التلقائية واجهة برمجة التطبيقات هذه
لعرض مستوى تقدّم عملية التثبيت.
مراقبة حالة الطلب
تتيح لك مكتبة Dynamic Navigator تنفيذ مسار تجربة مستخدم مشابه للمسار الموضّح في أفضل ممارسات تجربة المستخدم للتسليم عند الطلب، حيث يظل المستخدم في سياق الشاشة السابقة أثناء انتظار انتهاء عملية التثبيت. وهذا يعني أنّك لست بحاجة إلى عرض واجهة مستخدم وسيطة أو جزء تقدُّم على الإطلاق.
في هذا السيناريو، تكون مسؤولاً عن مراقبة جميع حالات التثبيت والتعامل معها، بما في ذلك تغييرات مستوى التقدّم والأخطاء.
لبدء عملية التنقّل غير المحظورة هذه، عليك تمرير عنصر DynamicExtras
يحتوي على DynamicInstallMonitor إلى
NavController.navigate()، كما هو موضّح في المثال التالي:
Kotlin
val navController = ...
val installMonitor = DynamicInstallMonitor()
navController.navigate(
destinationId,
null,
null,
DynamicExtras(installMonitor)
)
Java
NavController navController = ...
DynamicInstallMonitor installMonitor = new DynamicInstallMonitor();
navController.navigate(
destinationId,
null,
null,
new DynamicExtras(installMonitor);
)
بعد استدعاء navigate() مباشرةً، عليك التحقّق من قيمة
installMonitor.isInstallRequired لمعرفة ما إذا كانت محاولة التنقّل قد أدّت
إلى تثبيت وحدة ميزات.
- إذا كانت القيمة
false، يعني ذلك أنّك تنتقل إلى وجهة عادية ولا تحتاج إلى اتّخاذ أي إجراء آخر. إذا كانت القيمة
true، عليك البدء في مراقبة الكائنLiveDataالذي أصبح الآن فيinstallMonitor.status. يُصدر هذا العنصرLiveDataتحديثاتSplitInstallSessionStateمن مكتبة Play الأساسية. وتتضمّن هذه التحديثات أحداثًا تتعلّق بتقدّم عملية التثبيت يمكنك استخدامها لتعديل واجهة المستخدم. تذكَّر التعامل مع جميع الحالات ذات الصلة كما هو موضّح في دليل مكتبة Play الأساسية، بما في ذلك طلب تأكيد المستخدم إذا لزم الأمر.
Kotlin
val navController = ...
val installMonitor = DynamicInstallMonitor()
navController.navigate(
destinationId,
null,
null,
DynamicExtras(installMonitor)
)
if (installMonitor.isInstallRequired) {
installMonitor.status.observe(this, object : Observer<SplitInstallSessionState> {
override fun onChanged(sessionState: SplitInstallSessionState) {
when (sessionState.status()) {
SplitInstallSessionStatus.INSTALLED -> {
// Call navigate again here or after user taps again in the UI:
// navController.navigate(destinationId, destinationArgs, null, null)
}
SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION -> {
SplitInstallManager.startConfirmationDialogForResult(...)
}
// Handle all remaining states:
SplitInstallSessionStatus.FAILED -> {}
SplitInstallSessionStatus.CANCELED -> {}
}
if (sessionState.hasTerminalStatus()) {
installMonitor.status.removeObserver(this);
}
}
});
}
Java
NavController navController = ...
DynamicInstallMonitor installMonitor = new DynamicInstallMonitor();
navController.navigate(
destinationId,
null,
null,
new DynamicExtras(installMonitor);
)
if (installMonitor.isInstallRequired()) {
installMonitor.getStatus().observe(this, new Observer<SplitInstallSessionState>() {
@Override
public void onChanged(SplitInstallSessionState sessionState) {
switch (sessionState.status()) {
case SplitInstallSessionStatus.INSTALLED:
// Call navigate again here or after user taps again in the UI:
// navController.navigate(mDestinationId, mDestinationArgs, null, null);
break;
case SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION:
SplitInstallManager.startConfirmationDialogForResult(...)
break;
// Handle all remaining states:
case SplitInstallSessionStatus.FAILED:
break;
case SplitInstallSessionStatus.CANCELED:
break;
}
if (sessionState.hasTerminalStatus()) {
installMonitor.getStatus().removeObserver(this);
}
}
});
}
عند انتهاء التثبيت، يُصدر العنصر LiveData الحالة SplitInstallSessionStatus.INSTALLED. بعد ذلك، عليك الاتصال بـ NavController.navigate() مرة أخرى. بما أنّ الوحدة مثبّتة الآن، ينجح الطلب
وينتقل التطبيق إلى الوجهة على النحو المتوقّع.
بعد الوصول إلى حالة نهائية، مثل اكتمال التثبيت أو تعذُّر التثبيت، يجب إزالة مراقِب LiveData لتجنُّب تسرُّب الذاكرة. يمكنك التحقّق مما إذا كانت الحالة تمثّل حالة نهائية باستخدام
SplitInstallSessionStatus.hasTerminalStatus().
يمكنك الاطّلاع على AbstractProgressFragment للحصول على مثال على تنفيذ هذا المراقب.
الرسومات البيانية المضمّنة
تتيح مكتبة Dynamic Navigator تضمين الرسوم البيانية المحدّدة في وحدات الميزات. لتضمين رسم بياني محدّد في وحدة ميزات، اتّبِع الخطوات التالية:
استخدِم
<include-dynamic/>بدلاً من<include/>، كما هو موضّح في المثال التالي:<include-dynamic android:id="@+id/includedGraph" app:moduleName="includedgraphfeature" app:graphResName="included_feature_nav" app:graphPackage="com.google.android.samples.dynamic_navigator.included_graph_feature" />داخل
<include-dynamic ... />، يجب تحديد السمات التالية:-
app:graphResName: اسم ملف مورد الرسم البياني للتنقّل يتم اشتقاق الاسم من اسم ملف الرسم البياني. على سبيل المثال، إذا كان الرسم البياني فيres/navigation/nav_graph.xml، يكون اسم الموردnav_graph. -
android:id: معرّف وجهة الرسم البياني تتجاهل مكتبة Dynamic Navigator أي قيمandroid:idيتم العثور عليها في العنصر الجذر للرسم البياني المضمّن. -
app:moduleName: اسم حزمة الوحدة
-
استخدام graphPackage الصحيح
من المهم ضبط app:graphPackage بشكل صحيح لأنّ مكوّن التنقّل لن يتمكّن من تضمين navGraph المحدّد من وحدة الميزات في حال عدم ضبطه بشكل صحيح.
يتم إنشاء اسم حزمة وحدة الميزات الديناميكية من خلال إلحاق اسم الوحدة بـ applicationId وحدة التطبيق الأساسية. لذا، إذا كانت وحدة التطبيق الأساسية تحتوي على applicationId من com.example.dynamicfeatureapp وتمت تسمية وحدة الميزات الديناميكية باسم DynamicFeatureModule، سيكون اسم حزمة الوحدة الديناميكية هو com.example.dynamicfeatureapp.DynamicFeatureModule. اسم الحزمة هذا
حسّاس لحالة الأحرف.
إذا لم تكن متأكدًا، يمكنك تأكيد اسم حزمة وحدة الميزات
من خلال التحقّق من ملف AndroidManifest.xml الذي تم إنشاؤه.
بعد إنشاء المشروع، انتقِل إلى
<DynamicFeatureModule>/build/intermediates/merged_manifest/debug/AndroidManifest.xml،
والذي من المفترض أن يظهر على النحو التالي:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:dist="http://schemas.android.com/apk/distribution" featureSplit="DynamicFeatureModule" package="com.example.dynamicfeatureapp" android:versionCode="1" android:versionName="1.0" > <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="30" /> <dist:module dist:instant="false" dist:title="@string/title_dynamicfeaturemodule" > <dist:delivery> <dist:install-time /> </dist:delivery> <dist:fusing dist:include="true" /> </dist:module> <application /> </manifest>
يجب أن تتطابق قيمة featureSplit مع اسم وحدة الميزات الديناميكية،
وستتطابق الحزمة مع applicationId لوحدة التطبيق الأساسية. app:graphPackage هو مزيج من:
com.example.dynamicfeatureapp.DynamicFeatureModule.
الانتقال إلى رسم بياني للتنقّل يتضمّن ميزة التنقّل الديناميكي
لا يمكن الانتقال إلا إلى startDestination من
رسم بياني للتنقّل في include-dynamic. الوحدة الديناميكية مسؤولة عن الرسم البياني للتنقّل الخاص بها، ولا يعرف التطبيق الأساسي شيئًا عن ذلك.
تتيح آلية include-dynamic لوحدة التطبيق الأساسية تضمين رسم بياني للتنقّل
مُدمَج يتم تحديده داخل الوحدة الديناميكية. يعمل هذا الرسم البياني للتنقّل المدمج مثل أي رسم بياني آخر للتنقّل المدمج. يمكن للرسم البياني للتنقّل الجذر (أي الرسم البياني الرئيسي للرسم البياني المُدمَج) تحديد الرسم البياني للتنقّل المُدمَج نفسه كوجهة وليس كعناصر فرعية. وبالتالي، يتم استخدام السمة startDestination عندما يكون الرسم البياني include-dynamicnavigation هو الوجهة.
القيود
- لا تتيح الرسوم البيانية المضمّنة ديناميكيًا حاليًا استخدام الروابط لصفحات معيّنة.
- لا تتيح الرسوم البيانية المُدمَجة التي يتم تحميلها ديناميكيًا (أي عنصر
<navigation>يتضمّنapp:moduleName) استخدام الروابط لصفحات في التطبيق حاليًا.