تتيح لك ميزة "التنقّل" إرفاق البيانات بعملية تنقّل من خلال تحديد الوسيطات للوجهة. على سبيل المثال، قد تأخذ وجهة ملف المستخدم الشخصي وسيطة رقم تعريف المستخدم لتحديد المستخدم الذي سيتم عرضه.
بشكل عام، ننصحك بشدة بتمرير الحد الأدنى من البيانات فقط بين الوجهات. على سبيل المثال، يجب تمرير مفتاح لاسترداد عنصر
بدلاً من تمرير العنصر نفسه، لأنّ المساحة الإجمالية لجميع الحالات المحفوظة
محدودة على Android. إذا كنت بحاجة إلى تمرير كميات كبيرة من البيانات، استخدِم
ViewModel كما هو موضّح في
نظرة عامة على ViewModel.
تحديد وسيطات الوجهة
لتمرير البيانات بين الوجهات، حدد أولاً الوسيطة عن طريق إضافتها إلى الوجهة التي تستقبلها باتباع الخطوات التالية:
- في محرِّر التنقّل، انقر على الوجهة التي تتلقّى الوسيطة.
- في لوحة السمات، انقر على إضافة (+).
- في نافذة إضافة رابط وسيطة التي تظهر، أدخِل اسم الوسيطة ونوعها وما إذا كانت الوسيطة تقبل قيمة فارغة وقيمة تلقائية، إذا لزم الأمر.
- انقر على إضافة. لاحظ أن الوسيطة تظهر الآن في قائمة الوسيطات في لوحة السمات.
- بعد ذلك، انقر على الإجراء المقابل الذي ينقلك إلى هذه الوجهة. في لوحة السمات، من المفترض أن تظهر الآن الوسيطة التي أضفتها حديثًا في قسم القيم التلقائية للوسيطة.
يمكنك أيضًا ملاحظة أن الوسيطة تمت إضافتها في XML. انقر على علامة التبويب Text (نص) للتبديل إلى عرض XML، ولاحظ أنّه تمت إضافة الوسيطة إلى الوجهة التي تتلقّى الوسيطة. يظهر مثال في ما يلي:
<fragment android:id="@+id/myFragment" > <argument android:name="myArg" app:argType="integer" android:defaultValue="0" /> </fragment>
أنواع الوسيطات المتوافقة
تتيح مكتبة التنقّل أنواع الوسيطات التالية:
| النوع | بنية app:argType | إتاحة القيم التلقائية | تتم المعالجة من خلال المسارات | Nullable |
|---|---|---|---|---|
| عدد صحيح | app:argType="integer" | نعم | نعم | لا |
| عوامة | app:argType="float" | نعم | نعم | لا |
| الصيغة الطويلة | app:argType="long" | نعم، يجب أن تنتهي القيم التلقائية دائمًا باللاحقة "L" (مثلاً "123L"). | نعم | لا |
| قيمة منطقية | app:argType="boolean" | نعم - "صحيح" أو "خطأ" | نعم | لا |
| سلسلة | app:argType="string" | نعم | نعم | نعم |
| مرجع المورد | app:argType="reference" | نعم، يجب أن تكون القيم التلقائية على شكل "@resourceType/resourceName" (مثلاً "@style/myCustomStyle") أو "0" | نعم | لا |
| Custom Parcelable | app:argType="<type>"، حيث <type> هو اسم الفئة المؤهَّل بالكامل لـ Parcelable |
تتوافق مع القيمة التلقائية "@null". لا تتيح استخدام قيم تلقائية أخرى. | لا | نعم |
| Custom Serializable | app:argType="<type>"، حيث <type> هو اسم الفئة المؤهَّل بالكامل لـ Serializable |
تتوافق مع القيمة التلقائية "@null". لا تتيح استخدام قيم تلقائية أخرى. | لا | نعم |
| تعداد مخصّص | app:argType="<type>"، حيث <type> هو الاسم المؤهَّل بالكامل للتعداد | نعم: يجب أن تتطابق القيم التلقائية مع الاسم غير المؤهَّل (مثلاً، "SUCCESS" لمطابقة MyEnum.SUCCESS). | لا | لا |
إذا كان نوع الوسيطة يتيح استخدام القيم الفارغة، يمكنك تحديد قيمة تلقائية فارغة باستخدام android:defaultValue="@null".
يمكن تحليل المسارات والروابط لصفحات معيّنة ومعرّفات الموارد المنتظمة (URI) مع وسيطاتها من السلاسل. لا يمكن إجراء ذلك باستخدام أنواع البيانات المخصّصة، مثل Parcelables و Serializables، كما هو موضّح في الجدول السابق. لتمرير بيانات معقّدة مخصّصة، يمكنك تخزين البيانات في مكان آخر مثل ViewModel أو قاعدة بيانات وتمرير معرّف فقط أثناء التنقّل، ثم استرداد البيانات في الموقع الجديد بعد انتهاء التنقّل.
عند اختيار أحد الأنواع المخصّصة، يظهر مربّع الحوار اختيار فئة ويطلب منك اختيار الفئة المقابلة لهذا النوع. تتيح لك علامة التبويب المشروع اختيار فئة من مشروعك الحالي.
يمكنك اختيار <inferred type> لكي تحدّد مكتبة التنقّل النوع استنادًا إلى القيمة المقدَّمة.
يمكنك اختيار مصفوفة للإشارة إلى أنّ الوسيطة يجب أن تكون مصفوفة من قيمة النوع المحدّدة. يُرجى مراعاة ما يلي:
- لا تتوفّر مصفوفات التعدادات ومصفوفات مراجع الموارد.
- تتيح المصفوفات استخدام القيم التي يمكن أن تكون فارغة، بغض النظر عن إتاحة استخدام القيم التي يمكن أن تكون فارغة للنوع الأساسي. على سبيل المثال، يتيح لك استخدام
app:argType="integer[]"استخدامapp:nullable="true"للإشارة إلى أنّ تمرير مصفوفة فارغة مقبول. - تتيح المصفوفات قيمة تلقائية واحدة، وهي "@null". لا تتيح المصفوفات أي قيمة تلقائية أخرى.
تجاوز وسيطة وجهة في إجراء
تستخدم جميع الإجراءات التي تنتقل إلى الوجهة الوسيطات والقيم التلقائية على مستوى الوجهة. إذا لزم الأمر، يمكنك إلغاء القيمة التلقائية لوسيطة (أو ضبط قيمة إذا لم تكن موجودة) من خلال تحديد وسيطة على مستوى الإجراء. يجب أن تكون هذه الوسيطة بنفس الاسم والنوع مثل الوسيطة المعلنة في الوجهة.
يعرّف ملف XML التالي إجراءً يتضمّن وسيطة تلغي الوسيطة على مستوى الوجهة من المثال السابق:
<action android:id="@+id/startMyFragment"
app:destination="@+id/myFragment">
<argument
android:name="myArg"
app:argType="integer"
android:defaultValue="1" />
</action>
استخدام Safe Args لتمرير البيانات مع منع أخطاء الكتابة
يحتوي مكوّن التنقّل على مكوّن Gradle إضافي يُسمى Safe Args ينشئ فئات بسيطة للكائنات وأدوات الإنشاء للتنقّل الآمن من حيث النوع والوصول إلى أي وسيطات مرتبطة. ننصح بشدة باستخدام Safe Args للتنقّل وتمرير البيانات، لأنّها تضمن منع أخطاء الكتابة.
إذا لم تكن تستخدم Gradle، لن تتمكّن من استخدام المكوّن الإضافي Safe Args. في هذه الحالات، يمكنك استخدام الحِزم لتمرير البيانات مباشرةً.
لإضافة Safe Args إلى مشروعك، أدرِج classpath التالي في ملف build.gradle ذي المستوى الأعلى:
Groovy
buildscript { repositories { google() } dependencies { def nav_version = "2.10.2" classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version" } }
Kotlin
buildscript { repositories { google() } dependencies { val nav_version = "2.10.2" classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version") } }
يجب أيضًا تطبيق أحد المكوّنين الإضافيين المتاحَين.
لإنشاء رمز لغة Java مناسب لوحدات Java أو الوحدات المختلطة التي تستخدم Java وKotlin، أضِف السطر التالي إلى ملف build.gradle في تطبيقك أو وحدتك:
Groovy
plugins { id 'androidx.navigation.safeargs' }
Kotlin
plugins { id("androidx.navigation.safeargs") }
بدلاً من ذلك، لإنشاء رمز Kotlin مناسب للوحدات التي تستخدم Kotlin فقط، أضِف ما يلي:
Groovy
plugins { id 'androidx.navigation.safeargs.kotlin' }
Kotlin
plugins { id("androidx.navigation.safeargs.kotlin") }
يجب أن يتضمّن ملف gradle.properties android.useAndroidX=true وفقًا لما ورد في مقالة نقل البيانات إلى AndroidX.
بعد تفعيل Safe Args، يحتوي الرمز الذي تم إنشاؤه على الفئات والطرق التالية لمنع أخطاء الكتابة لكل إجراء، بالإضافة إلى كل وجهة إرسال واستلام.
يتم إنشاء فئة لكل وجهة ينشأ منها إجراء. اسم هذه الفئة هو اسم الوجهة الأصلية متبوعًا بكلمة "اتجاهات". على سبيل المثال، إذا كانت الوجهة الأصلية عبارة عن جزء يُسمى
SpecifyAmountFragment، فسيتم تسمية الفئة التي تم إنشاؤهاSpecifyAmountFragmentDirections.تحتوي هذه الفئة على طريقة لكل إجراء محدّد في الوجهة الأصلية.
بالنسبة لكل إجراء مستخدم لتمرير الوسيطة، يتم إنشاء فئة داخلية يعتمد اسمها على الإجراء. على سبيل المثال، إذا كان الإجراء يحمل الاسم
confirmationAction,، يكون اسم الفئةConfirmationAction. إذا كان الإجراء يحتوي على وسيطات بدونdefaultValue، يمكنك استخدام فئة الإجراء المرتبطة لضبط قيمة الوسيطات.يتم إنشاء فئة للوجهة المستلِمة. اسم هذه الفئة هو اسم الوجهة متبوعًا بكلمة "Args". على سبيل المثال، إذا كان الجزء المقصود يحمل الاسم
ConfirmationFragment,، فسيتم تسمية الفئة التي تم إنشاؤها باسمConfirmationFragmentArgs. استخدِم طريقةfromBundle()لهذه الفئة لاسترداد الوسيطات.
يوضّح المثال التالي كيفية استخدام هذه الطرق لضبط وسيطة وتمريرها إلى إجراء navigate():
Kotlin
override fun onClick(v: View) {
val amountTv: EditText = view!!.findViewById(R.id.editTextAmount)
val amount = amountTv.text.toString().toInt()
val action = SpecifyAmountFragmentDirections.confirmationAction(amount)
v.findNavController().navigate(action)
}
Java
@Override
public void onClick(View view) {
EditText amountTv = (EditText) getView().findViewById(R.id.editTextAmount);
int amount = Integer.parseInt(amountTv.getText().toString());
ConfirmationAction action =
SpecifyAmountFragmentDirections.confirmationAction();
action.setAmount(amount);
Navigation.findNavController(view).navigate(action);
}
في الرمز البرمجي للوجهة المستلِمة، استخدِم طريقة getArguments()
لاسترداد الحزمة واستخدام محتواها. عند استخدام تبعيات -ktx،
يمكن لمستخدمي Kotlin أيضًا استخدام مفوّض السمة by navArgs() للوصول إلى
الوسيطات.
Kotlin
val args: ConfirmationFragmentArgs by navArgs()
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
val tv: TextView = view.findViewById(R.id.textViewAmount)
val amount = args.amount
tv.text = amount.toString()
}
Java
@Override
public void onViewCreated(View view, @Nullable Bundle savedInstanceState) {
TextView tv = view.findViewById(R.id.textViewAmount);
int amount = ConfirmationFragmentArgs.fromBundle(getArguments()).getAmount();
tv.setText(amount + "");
}
استخدام Safe Args مع إجراء شامل
عند استخدام Safe Args مع
إجراء عام،
يجب تقديم قيمة android:id لعنصر <navigation> الجذر، كما
هو موضّح في المثال التالي:
<?xml version="1.0" encoding="utf-8"?> <navigation xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools" xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/main_nav" app:startDestination="@id/mainFragment"> ... </navigation>
تنشئ ميزة "التنقّل" فئة Directions للعنصر <navigation> استنادًا إلى قيمة android:id. على سبيل المثال، إذا كان لديك عنصر <navigation>
مع android:id=@+id/main_nav، ستكون الفئة التي تم إنشاؤها باسم
MainNavDirections. تحتوي جميع الوجهات داخل العنصر <navigation> على
طرق تم إنشاؤها للوصول إلى جميع الإجراءات العامة المرتبطة باستخدام الطرق نفسها
كما هو موضّح في القسم السابق.
تمرير البيانات بين الوجهات باستخدام عناصر Bundle
إذا لم تكن تستخدم Gradle، سيظل بإمكانك تمرير الوسيطات بين الوجهات باستخدام عناصر Bundle. أنشئ عنصر Bundle ومرِّره إلى الوجهة باستخدام navigate()، كما في المثال التالي:
Kotlin
val bundle = bundleOf("amount" to amount)
view.findNavController().navigate(R.id.confirmationAction, bundle)
Java
Bundle bundle = new Bundle();
bundle.putString("amount", amount);
Navigation.findNavController(view).navigate(R.id.confirmationAction, bundle);
In your receiving destination's code, use the getArguments() method to
retrieve the Bundle and use its contents:
Kotlin
val tv = view.findViewById<TextView>(R.id.textViewAmount)
tv.text = arguments?.getString("amount")
Java
TextView tv = view.findViewById(R.id.textViewAmount);
tv.setText(getArguments().getString("amount"));
تمرير البيانات إلى وجهة البدء
يمكنك تمرير البيانات إلى وجهة بدء تطبيقك. أولاً، عليك إنشاء Bundle بشكل صريح
يحتوي على البيانات. بعد ذلك، استخدِم إحدى الطرق التالية لتمرير Bundle إلى وجهة البدء:
- إذا كنت تنشئ
NavHostآليًا، يمكنك استدعاءNavHostFragment.create(R.navigation.graph, args)، حيث يمثّلargsBundleالذي يحتوي على بياناتك. - بخلاف ذلك، يمكنك ضبط وسيطات وجهة البدء من خلال استدعاء إحدى الدوال التالية التي تحمل الاسم نفسه
NavController.setGraph():- استخدِم معرّف الرسم البياني:
navController.setGraph(R.navigation.graph, args) - استخدام الرسم البياني نفسه:
navController.setGraph(navGraph, args)
- استخدِم معرّف الرسم البياني:
لاسترداد البيانات في وجهة البدء، اتصل بالرقم
Fragment.getArguments().
اعتبارات ProGuard
إذا كنت تُقلّص حجم الرمز البرمجي، عليك منع حجب أسماء فئات Parcelable وSerializable وEnum كجزء من عملية إزالة البيانات غير الضرورية. يمكن تنفيذ هذه الخطوة بإحدى الطريقتَين التاليتَين:
- استخدام تعليقات @Keep التوضيحية
- استخدِم قواعد keepnames.
توضّح الفقرات الفرعية التالية هذه الطرق.
استخدام تعليقات @Keep التوضيحية
يضيف المثال التالي تعليقات توضيحية @Keep إلى تعريفات فئات النماذج:
Kotlin
@Keep class ParcelableArg : Parcelable { ... }
@Keep class SerializableArg : Serializable { ... }
@Keep enum class EnumArg { ... }
Java
@Keep public class ParcelableArg implements Parcelable { ... }
@Keep public class SerializableArg implements Serializable { ... }
@Keep public enum EnumArg { ... }
استخدام قواعد keepnames
يمكنك أيضًا إضافة قواعد keepnames إلى ملف proguard-rules.pro، كما هو موضّح في المثال التالي:
proguard-rules.pro
...
-keepnames class com.path.to.your.ParcelableArg
-keepnames class com.path.to.your.SerializableArg
-keepnames class com.path.to.your.EnumArg
...
مراجع إضافية
لمعرفة المزيد حول التنقل، راجع الموارد الإضافية التالية.