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

تتيح لك واجهة برمجة تطبيقات إنشاء التنقل إمكانية التنقل بين العناصر القابلة للإنشاء في تطبيق "إنشاء"، مع الاستفادة من مكوّن ميزة "التنقل" في Jetpack وبنيتها وميزاتها.

توضّح هذه الصفحة كيفية نقل البيانات من واجهة مستخدم 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، أصبح من الممكن الآن ضبط التحولات المخصّصة، التي كانت متوفرة سابقًا في AnimatedNavHost، في NavHost مباشرةً. اطّلِع على ملاحظات الإصدار للحصول على مزيد من المعلومات.

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

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