Safe Args

الطريقة المقترَحة للتنقّل بين الوجهات هي استخدام مكوّن Safe Args الإضافي في Gradle. ينشئ هذا المكوّن الإضافي فئتَي الكائنات والمنشئ اللتين تتيحان التنقّل بين الوجهات مع الحفاظ على سلامة الأنواع. استخدِم Safe Args لـ التنقّل وتمرير البيانات بين الوجهات.

تفعيل Safe Args

لإضافة Safe Args إلى مشروعك، أدرِج classpath التالي في ملف build.gradle ذي المستوى الأعلى:

Groovy

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.9.8"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.9.8"
        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، يحتوي الرمز البرمجي الذي تم إنشاؤه على فئات وطُرق لكل إجراء حدّدته، بالإضافة إلى فئات تتطابق مع كل وجهة إرسال واستلام.

ينشئ Safe Args فئة لكل وجهة ينشأ منها إجراء. يضيف اسم الفئة التي تم إنشاؤها كلمة "Directions" إلى اسم فئة الوجهة الأصلية. على سبيل المثال، إذا كان اسم الوجهة الأصلية SpecifyAmountFragment، يكون اسم الفئة التي تم إنشاؤها SpecifyAmountFragmentDirections.

تحتوي الفئة التي تم إنشاؤها على طريقة ثابتة لكل إجراء محدّد في الوجهة الأصلية. تأخذ هذه الطريقة أي مَعلمات إجراء كوسيطات وتعرض كائن NavDirections يمكنك تمريره مباشرةً إلى navigate().

مثال على Safe Args

على سبيل المثال، لنفترض أنّ لدينا رسمًا بيانيًا للتنقّل يتضمّن إجراءً واحدًا يربط بين وجهتَين، هما SpecifyAmountFragment وConfirmationFragment. تأخذ ConfirmationFragment مَعلمة float واحدة تقدّمها كجزء من الإجراء.

ينشئ Safe Args فئة SpecifyAmountFragmentDirections تتضمّن طريقة واحدة، هي actionSpecifyAmountFragmentToConfirmationFragment()، وفئة داخلية تُسمّى ActionSpecifyAmountFragmentToConfirmationFragment. تستند الفئة الداخلية إلى NavDirections وتخزّن معرّف الإجراء المرتبط ومَعلمة float. يمكن بعد ذلك تمرير كائن NavDirections الذي تم عرضه مباشرةً إلى navigate()، كما هو موضّح في المثال التالي:

Kotlin

override fun onClick(v: View) {
    val amount: Float = ...
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment(amount)
    v.findNavController().navigate(action)
}

Java

@Override
public void onClick(View view) {
    float amount = ...;
    action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment(amount);
    Navigation.findNavController(view).navigate(action);
}

لمزيد من المعلومات حول تمرير البيانات بين الوجهات باستخدام Safe Args، يُرجى الاطّلاع على مقالة استخدام Safe Args لتمرير البيانات مع منع أخطاء الكتابة.

ضمان منع أخطاء الكتابة باستخدام Safe Args

يمكنك التنقّل بين الوجهات باستخدام مكوّن Safe Args الإضافي في Gradle. ينشئ هذا المكوّن الإضافي فئتَي الكائنات والمنشئ البسيطتَين اللتين تتيحان التنقّل بين الوجهات وتمرير الوسيطات بينها مع الحفاظ على سلامة الأنواع.

لإضافة Safe Args إلى مشروعك، أدرِج classpath التالي في ملف build.gradle ذي المستوى الأعلى:

Groovy

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.9.8"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.9.8"
        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، ينشئ المكوّن الإضافي رمزًا برمجيًا يحتوي على فئات وطُرق لكل إجراء حدّدته. لكل إجراء، ينشئ Safe Args أيضًا فئة لكل وجهة أصلية، وهي الوجهة التي ينشأ منها الإجراء. اسم الفئة التي تم إنشاؤها هو مزيج من اسم فئة الوجهة الأصلية وكلمة "Directions". على سبيل المثال، إذا كان اسم الوجهة SpecifyAmountFragment، يكون اسم الفئة التي تم إنشاؤها هو SpecifyAmountFragmentDirections. تحتوي الفئة التي تم إنشاؤها على طريقة ثابتة لكل إجراء محدّد في الوجهة الأصلية. تأخذ هذه الطريقة أي مَعلمات إجراء محدّدة كوسيطات وتعرض كائن NavDirections يمكنك تمريره إلى navigate().

على سبيل المثال، لنفترض أنّ لدينا رسمًا بيانيًا للتنقّل يتضمّن إجراءً واحدًا يربط بين الوجهة الأصلية، SpecifyAmountFragment، ووجهة الاستلام، ConfirmationFragment.

ينشئ Safe Args فئة SpecifyAmountFragmentDirections تتضمّن طريقة واحدة، هي actionSpecifyAmountFragmentToConfirmationFragment()، التي تعرض كائن NavDirections. يمكن بعد ذلك تمرير كائن NavDirections الذي تم عرضه مباشرةً إلى navigate()، كما هو موضّح في المثال التالي:

Kotlin

override fun onClick(view: View) {
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment()
    view.findNavController().navigate(action)
}

Java

@Override
public void onClick(View view) {
    NavDirections action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment();
    Navigation.findNavController(view).navigate(action);
}

لمزيد من المعلومات حول تمرير البيانات بين الوجهات باستخدام Safe Args، يُرجى الاطّلاع على مقالة استخدام Safe Args لتمرير البيانات مع منع أخطاء الكتابة في تمرير البيانات بين الوجهات.