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

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

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

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

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

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

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

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

إذا كان تطبيقك يتّبع نمط تصميم متفرّق (UDF) ودليلنا إلى البنية الهندسية، يجب ألا يتطلب الانتقال إلى Jetpack Compose وCompose Compose إعادة ضبط أساسية لطبقات التطبيق الأخرى، باستثناء طبقة واجهة المستخدم.

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

  1. أضِف تبعية ميزة "إنشاء التنقل" إلى تطبيقك.

  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 للتنقّل.

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

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

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

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

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

استرداد البيانات المعقدة عند التنقل

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

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

القيود

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

نقل بيانات إضافي إلى ميزة "إنشاء التنقل"

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

المؤثرات الحركية الانتقالية

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

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

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