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

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

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

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

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

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

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

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

إذا كان تطبيقك يتّبع نمط تصميم UDF ودليلنا إلى البنية الأساسية، لن يتطلب الانتقال إلى Jetpack Compose و Navigation 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 injection ونقطة الدمج الخاصة به مع Compose و Navigation (الإنشاء) والتنقل من خلال hiltViewModel:

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

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

    1. إذا سبق لك استخدام المكوِّن الإضافي Safe Args لإنشاء اتجاهات التنقُّل والإجراءات، استبدِله بمسار، وهو مسار سلسلة إلى العنصر القابل للإنشاء يكون فريدًا لكل وجهة.
    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 ذات الصلة والتنقل غير الضروري والموارد الأخرى، بالإضافة إلى تبعيات الأجزاء القديمة والتنقل في Jetpack.

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

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

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

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

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

Safe Args

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

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

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

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

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

القيود

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

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

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

الرسوم المتحركة الانتقالية

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

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

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

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