Safe Args

تتمثل الطريقة الموصى بها للتنقل بين الوجهات في استخدام المكون الإضافي Safe Args Gradle. يُنشئ هذا المكون الإضافي فئات الكائنات والمنشئات التي تمكّن التنقل الآمن بين الوجهات. استخدم الوسيطات الآمنة للتنقل وتمرير البيانات بين الوجهات.

تفعيل الوسيطات الآمنة

لإضافة الوسيطات الآمنة إلى مشروعك، ضمِّن classpath التالي في ملف build.gradle ذي المستوى الأعلى:

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

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

يجب أيضًا تطبيق أحد المكوّنَين الإضافيَين المتاحَين.

لإنشاء رمز لغة Java مناسب لوحدات Java وKotlin المختلطة، يمكنك إضافة هذا السطر إلى ملف build.gradle في التطبيق أو الوحدة:

plugins {
  id 'androidx.navigation.safeargs'
}

plugins {
    id("androidx.navigation.safeargs")
}

وبدلاً من ذلك، لإنشاء رمز Kotlin المناسب للوحدات الخاصة بلغة Kotlin فقط، أضِف ما يلي:

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

يجب أن يكون لديك android.useAndroidX=true في ملف gradle.properties وفقًا لنقل البيانات إلى AndroidX.

الرمز الذي تم إنشاؤه

بعد تفعيل Safe Args، تحتوي التعليمة البرمجية التي تم إنشاؤها على فئات وطرق لكل إجراء حددته بالإضافة إلى الفئات التي تتوافق مع كل وجهة إرسال واستلام.

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

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

مثال على الوسيطات الآمنة

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

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

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

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

لمزيد من المعلومات حول تمرير البيانات بين الوجهات باستخدام الوسيطات الآمنة، يُرجى الاطّلاع على المقالة استخدام الوسيطات الآمنة لتمرير البيانات ذات النوع الآمن.

ضمان أمان الكتابة باستخدام الوسيطات الآمنة

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

لإضافة الوسيطات الآمنة إلى مشروعك، ضمِّن classpath التالي في ملف build.gradle ذي المستوى الأعلى:

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

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

يجب أيضًا تطبيق أحد المكوّنَين الإضافيَين المتاحَين.

لإنشاء رمز لغة Java مناسب لوحدات Java وKotlin المختلطة، يمكنك إضافة هذا السطر إلى ملف build.gradle في التطبيق أو الوحدة:

plugins {
  id 'androidx.navigation.safeargs'
}

plugins {
    id("androidx.navigation.safeargs")
}

وبدلاً من ذلك، لإنشاء رمز Kotlin المناسب للوحدات الخاصة بلغة Kotlin فقط، أضِف ما يلي:

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

يجب أن يكون لديك android.useAndroidX=true في ملف gradle.properties وفقًا لنقل البيانات إلى AndroidX.

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

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

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

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

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

لمزيد من المعلومات حول تمرير البيانات بين الوجهات باستخدام الوسيطات الآمنة، يُرجى الاطّلاع على القسم استخدام الوسيطات الآمنة لتمرير البيانات ذات النوع الآمن في تمرير البيانات بين الوجهات.