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

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

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

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

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

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

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

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

إذا كان تطبيقك يتّبع نمط تصميم متفرّق (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. يجب إعداد NavController في مكان تتيح لجميع العناصر القابلة للإنشاء التي يجب الإشارة إليها الوصول إليها (يكون ذلك عادةً داخل App القابل للإنشاء). يتّبع هذا النهج مبادئ عرض الحالات ويسمح لك باستخدام NavController كمصدر الحقيقة للتنقّل بين الشاشات القابلة للإنشاء والحفاظ على حزمة الخلفية:

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

  4. أنشِئ NavHost لتطبيقك داخل "التطبيق القابل للإنشاء" وأجرِ navController:

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

    SampleNavHost(navController = navController)
}

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

  5. أضِف وجهات composable لإنشاء رسم بياني للتنقّل. إذا تم نقل كل شاشة مسبقًا إلى Compose، فهذه الخطوة لا تتألف فقط من استخراج محتوى الشاشة القابل للإنشاء من الأجزاء إلى وجهات 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

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

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

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

    1. إذا سبق لك استخدام المكوّن الإضافي "الوسيطات الآمنة" لإنشاء اتجاهات وإجراءات التنقّل، استبدِله بمسار، وهو مسار سلسلة إلى العنصر القابل للإنشاء يكون فريدًا لكل وجهة.
    2. لاستبدال الوسيطات الآمنة عند تمرير البيانات، راجع التنقل باستخدام الوسيطات.

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

      @Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = "first") {
        composable("first") {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate("second_screen_route")
                }
            )
        }
        composable("second") {
            SecondScreen(
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate("third_screen_route")
                }
            )
        }
        // ...
    }
}
      MigrationCommonScenariosSnippets.kt

  8. يجب إزالة جميع "الأجزاء" وتنسيقات XML ذات الصلة والانتقالات غير الضرورية والموارد الأخرى، والتبعيات القديمة لكل من Fragment وJetpack للتنقّل.

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

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

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

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

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

Safe Args

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

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

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

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

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

القيود

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

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

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

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

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

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

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

  • الدرس التطبيقي حول الترميز الخاص بإنشاء التنقل: يمكنك التعرُّف على أساسيات ميزة "إنشاء التنقل" باستخدام درس تطبيقي حول الترميز.
  • الآن في مستودع Android: تطبيق Android كامل الوظائف تم إنشاؤه بالكامل باستخدام Kotlin وJetpack Compose والذي يتّبع أفضل الممارسات المتعلّقة بتصميم Android وتطوير التطبيقات ويشمل ميزة Navigation Compose.
  • نقل بيانات تطبيق Sunflower إلى Jetpack Compose: هي مشاركة مدوّنة توثّق رحلة نقل نموذج تطبيق Sunflower من تطبيق "Views" إلى "Compose"، ويشمل ذلك أيضًا عملية الانتقال إلى Navigation Compose.
  • Jetnews لكلّ شاشة: هي مشاركة مدوّنة توثّق عملية إعادة بناء نموذج Jetnews ونقله لإتاحة استخدام جميع الشاشات مع Jetpack Compose و Navigation Compose.