نقل بيانات التنقّل في Jetpack إلى التنقّل Compose

تتيح لك واجهة برمجة التطبيقات Navigation Compose API التنقّل بين العناصر القابلة للتجميع في تطبيق Compose، مع الاستفادة من المكوّن و البنية الأساسية والميزات في Jetpack Navigation.

توضّح هذه الصفحة كيفية نقل البيانات من واجهة مستخدم Jetpack Navigation المستندة إلى "المقاطع" إلى واجهة مستخدم Navigation Compose، وذلك كجزء من عملية نقل البيانات الأكبر حجمًا لواجهة المستخدم المستندة إلى "العروض" إلى واجهة مستخدم Compose في Jetpack.

المتطلبات الأساسية لنقل البيانات

يمكنك نقل البيانات إلى ميزة "إنشاء التنقّل" بعد أن تتمكّن من استبدال كلّ المقاطع بعناصر قابلة للتجميع على الشاشة. يمكن أن تحتوي العناصر القابلة للتجميع على الشاشة على مزيج من محتوى "الإنشاء" و"العرض"، ولكن يجب أن تكون جميع وجهات التنقّل عناصر قابلة للتجميع لتفعيل نقل بيانات ميزة "التنقّل والإنشاء". وحتى ذلك الحين، يجب مواصلة استخدام مكوّن التنقّل المستنِد إلى الأجزاء في قاعدة بيانات View و Compose للتوافق. يُرجى الاطّلاع على مستندات التشغيل التفاعلي للتنقّل للحصول على مزيد من المعلومات.

إنّ استخدام ميزة "التنقّل والإنشاء" في تطبيق مخصّص للإنشاء فقط ليس شرطًا أساسيًا. يمكنك مواصلة استخدام مكوّن التنقّل المستنِد إلى الأقسام، ما دامت الأقسام متاحة لاستضافة المحتوى القابل للتجميع.

خطوات نقل البيانات

سواء كنت تتّبع استراتيجية نقل البيانات المقترَحة أو تتّبع نهجًا آخر، ستصل إلى نقطة تكون فيها جميع وجهات التنقّل عناصر قابلة للتجميع على الشاشة، وتعمل "المقاطع" فقط كمحاويات قابلة للتجميع. في هذه المرحلة، يمكنك نقل البيانات إلى ميزة "التنقّل والإنشاء".

إذا كان تطبيقك يتّبع حاليًا نمط تصميم وظائف تحديد البيانات ودليلنا ل البنية، لن يتطلّب نقل البيانات إلى Jetpack Compose وNavigation Compose إعادة صياغة كبيرة للطبقات الأخرى من تطبيقك، باستثناء طبقة واجهة المستخدم.

لنقل الرسائل إلى ميزة "التنقّل والإنشاء"، اتّبِع الخطوات التالية:

  1. أضِف التبعية Navigation Compose إلى تطبيقك.

  2. أنشئ App-level قابلة للتجميع وأضِفها إلى Activity كأحد نقاط دخول "الإنشاء"، مع استبدال إعداد تنسيق "العرض":

    class SampleActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
        setContent {
            SampleApp(/* ... */)
        }
    }
}
    MigrationCommonScenariosSnippets.kt

  3. أنشئ أنواعًا لكل وجهة تنقّل. استخدِم data object لتحديد الوجهات التي لا تتطلّب أي بيانات، واستخدِم data class أو class لتحديد الوجهات التي تتطلّب بيانات.

    @Serializable data object First
@Serializable data class Second(val id: String)
@Serializable data object Third

    MigrationCommonScenariosSnippets.kt

  4. اضبط NavController في مكان يمكن لجميع العناصر القابلة للتجميع التي تحتاج إلى الإشارة إليه الوصول إليه (يكون ذلك عادةً داخل العنصر القابل للتجميع App ). يتّبع هذا النهج مبادئ تصعيد الحالة ويتيح لك استخدام NavController كمصدر المعلومات الموثوقة للتنقّل بين الشاشات القابلة للتجميع والحفاظ على الحزمة الخلفية:

    @Composable
fun SampleApp() {
    val navController = rememberNavController()
    // ...
}
    MigrationCommonScenariosSnippets.kt

  5. أنشئ NavHost تطبيقك داخل العنصر القابل للتجميع App وأرسِلnavController:

    @Composable
fun SampleApp() {
    val navController = rememberNavController()

    SampleNavHost(navController = navController)
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  6. أضِف composable وجهة لإنشاء الرسم البياني للتنقّل. إذا سبق نقل كل شاشة إلى أداة "الإنشاء"، تتألف هذه الخطوة فقط من استخراج مكونات الشاشة هذه من "المقاطع" إلى composable الوجهات التالية:

    class FirstFragment : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        return ComposeView(requireContext()).apply {
            setContent {
                // FirstScreen(...) EXTRACT FROM HERE
            }
        }
    }
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(/* ... */) // EXTRACT TO HERE
        }
        composable<Second> {
            SecondScreen(/* ... */)
        }
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  7. إذا اتّبعت الإرشادات حول تصميم واجهة مستخدم Compose، على وجه التحديد كيفية تمرير ViewModel وأحداث التنقّل إلى العناصر القابلة للتجميع، تكون الخطوة التالية هي تغيير طريقة تقديم ViewModel إلى كل عنصر قابل للتجميع على الشاشة. يمكنك في كثير من الأحيان استخدام ميزة "حقن Hilt" ونقطة دمجها مع Compose وNavigation من خلال hiltViewModel:

    @Composable
fun FirstScreen(
    // viewModel: FirstViewModel = viewModel(),
    viewModel: FirstViewModel = hiltViewModel(),
    onButtonClick: () -> Unit = {},
) {
    // ...
}
    MigrationCommonScenariosSnippets.kt

  8. استبدِل جميع طلبات التنقّل findNavController() بطلبات navController وقدِّمها كأحداث تنقّل إلى كل شاشة قابلة للتجميع، بدلاً من تمرير navController بالكامل. يتّبع هذا النهج أفضل الممارسات لعرض الأحداث من الدوالّ القابلة للتجميع للمتصلين وي يحافظ على navController كمصدر واحد للحقائق.

    يمكن تمرير البيانات إلى وجهة من خلال إنشاء مثيل لفئة مسار المحدّدة لتلك الوجهة. ويمكن الحصول عليه بعد ذلك إما مباشرةً من إدخال الحزمة الخلفية في الوجهة أو من ViewModel باستخدام SavedStateHandle.toRoute().

    @Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate(Second(id = "ABC"))
                }
            )
        }
        composable<Second> { backStackEntry ->
            val secondRoute = backStackEntry.toRoute<Second>()
            SecondScreen(
                id = secondRoute.id,
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate(Third)
                }
            )
        }
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  9. أزِل جميع المقاطع وتنسيقات XML ذات الصلة وعناصر التنقّل غير الضرورية وغيرها من موارد التنقّل، بالإضافة إلى التبعيات القديمة لـ Fragment وJetpack Navigation.

يمكنك العثور على الخطوات نفسها مع مزيد من التفاصيل المتعلّقة بميزة "إنشاء مسار التنقّل" في مستندات الإعداد.

حالات الاستخدام الشائعة

بغض النظر عن مكوّن التنقّل الذي تستخدمه، تنطبق مبادئ التنقّل نفسها.

تشمل حالات الاستخدام الشائعة عند نقل البيانات ما يلي:

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

استرداد البيانات المعقدة أثناء التنقّل

ننصح بشدة بعدم نقل عناصر البيانات المعقدة عند التنقّل. بدلاً من ذلك، يمكنك ضبط الحد الأدنى من المعلومات اللازمة، مثل معرّف فريد أو شكل آخر من المعرّفات، كوسيطات عند تنفيذ إجراءات التنقّل. يجب تخزين العناصر المعقدة كبيانات في مصدر واحد للحقائق، مثل طبقة البيانات. لمزيد من المعلومات، يُرجى الاطّلاع على استرداد البيانات المعقدة عند التنقّل.

إذا كانت المقاطع تمرّر عناصر معقّدة كوسيطات، ننصحك بإعادة صياغة الرمز البرمجي أولاً، بطريقة تسمح بتخزين هذه العناصر واستردادها من طبقة البيانات. يمكنك الاطّلاع على الميزات المتوفّرة الآن في مستودع Android للاطّلاع على مثالين.

القيود

يصف هذا القسم القيود الحالية لميزة "التنقّل والإنشاء".

نقل البيانات بشكل تدريجي إلى Navigation Compose

لا يمكنك حاليًا استخدام أداة إنشاء التنقّل مع مواصلة استخدام المقتطفات كأحد الوجهات في الرمز البرمجي. لبدء استخدام ميزة "إنشاء مسار"، يجب أن تكون كل وجهاتك قابلة للإنشاء. يمكنك تتبُّع طلب الميزة هذا على نظام تتبُّع المشاكل.

الصور المتحركة للانتقال

اعتبارًا من الإصدار Navigation 2.7.0-alpha01، أصبح من الممكن الآن ضبط التحولات المخصّصة في NavHost مباشرةً، بدلاً من استخدام AnimatedNavHost. اطّلِع على ملاحظات الإصدار للحصول على مزيد من المعلومات.

مزيد من المعلومات

لمزيد من المعلومات عن نقل البيانات إلى ميزة "التنقّل والإنشاء"، يُرجى الاطّلاع على المراجع التالية: