أصبح الإصدار 1.0 من مكتبة Jetpack Navigation 3 مستقرًا 🎉. يمكنك استخدامه اليوم في تطبيقاتك المنشورة. تستخدمه JetBrains حاليًا في تطبيق KotlinConf.

‫Navigation 3 هي مكتبة تنقّل جديدة تم إنشاؤها من الألف للياء لتتوافق مع حالة Jetpack Compose state. تمنحك هذه المكتبة تحكّمًا كاملاً في الأنشطة السابقة، وتساعدك في الاحتفاظ بحالة التنقّل، وتتيح لك إنشاء تنسيقات تكيّفية بسهولة (مثل عرض على شكل قائمة مع تفاصيل). يتوفّر أيضًا إصدار من عدّة منصات من JetBrains.

ما سبب إنشاء مكتبة جديدة؟

تم تصميم مكتبة Jetpack Navigation الأصلية (التي تُعرف الآن باسم Nav2) قبل 7 أعوام، ومع أنّها تحقق أهدافها الأصلية بشكل جيد وتم تحسينها بشكل متكرر، فقد تغيّرت طريقة إنشاء التطبيقات الآن بشكل جذري. 

أصبح الآن استخدام البرمجة التفاعلية مع واجهة مستخدِم تصريحية هو القاعدة. تتّبع Nav3 هذا النهج. على سبيل المثال، تراقب NavDisplay (مكوّن واجهة مستخدِم Nav3 الذي يعرض شاشاتك) ببساطة قائمة بالمفاتيح (يمثّل كل منها شاشة) تستند إلى حالة Compose، وتعدّل واجهة المستخدِم عند تغيير هذه القائمة.

يمكن أن يؤدي استخدام Nav2 أيضًا إلى صعوبة الحصول على مصدر واحد للبيانات لحالة التنقّل لأنّها تتضمّن حالتها الداخلية الخاصة. في Nav3، يمكنك توفير حالتك الخاصة، ما يمنحك تحكّمًا كاملاً.

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

يتيح لك هذا النهج ما يلي: 

• تخصيص الرسوم المتحركة للشاشة على المستوى العام والفردي
• عرض لوحات متعدّدة في الوقت نفسه وإنشاء تنسيقات مرنة باستخدام واجهة برمجة التطبيقات Scenes
• استبدال مكوّنات Nav3 بسهولة بتنفيذاتك الخاصة إذا كنت تريد سلوكًا مخصّصًا

يمكنك الاطّلاع على مزيد من المعلومات عن تصميمها وميزاتها في مدوّنة الإطلاق. 

نقل البيانات من Navigation 2

إذا كنت تستخدم Nav2 حاليًا، وتحديدًا Navigation Compose، ننصحك بنقل البيانات إلى Nav3. لمساعدتك في ذلك، يتوفّر دليل لنقل البيانات . في ما يلي الخطوات الرئيسية: 

1. إضافة الاعتمادات في Navigation 3
2. تعديل مسارات التنقّل لتنفيذ NavKey ليس من الضروري أن تنفّذ مساراتك هذه الواجهة لاستخدام Nav3، ولكن إذا فعلت ذلك، يمكنك الاستفادة من وظيفة rememberNavBackStack في Nav3 لإنشاء سجلّ تصفّح سابق دائم.
3. إنشاء فئات لتخزين حالة التنقّل وتعديلها، حيث يتم تخزين سجلّات التصفّح السابقة
4. استبدال NavController بهذه الفئات
5. نقل وجهاتك من NavGraph في NavHost إلى entryProvider
6. استبدال NavHost بـ NavDisplay

تجربة نقل بيانات وكيل الذكاء الاصطناعي

يمكنك تجربة استخدام وكيل ذكاء اصطناعي لقراءة دليل نقل البيانات وتنفيذ الخطوات في مشروعك. لتجربة ذلك باستخدام Gemini في ميزة Agent Mode ضمن "استوديو Android"، اتّبِع الخطوات التالية:

• احفظ هذا الإصدار بتنسيق Markdown من الدليل في مشروعك.
• الصِق هذا الطلب في الوكيل (ولكن لا تضغط على مفتاح الإدخال): "نقل بيانات هذا المشروع إلى Navigation 3 باستخدام ".
• اكتب ‎ @migration-guide.md، ما سيؤدي إلى توفير الدليل كسياق للوكيل. 

كما هي العادة، تأكَّد من مراجعة التغييرات التي أجراها وكيل الذكاء الاصطناعي بعناية، فقد يرتكب أخطاء.

يسرّنا معرفة أدائك أو أداء وكيلك، لذا يُرجى إرسال ملاحظاتك هنا.

وصفات تنقّل رائعة للسيناريوهات الشائعة

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

تتوفّر حاليًا 19 وصفة، بما في ذلك الوصفات التالية: 

• سجلّات تصفّح سابقة متعدّدة
• التصميم المعياري وإدخال التبعيات
• تمرير وسيطات التنقّل إلى ViewModels (بما في ذلك استخدام Koin)
• عرض النتائج من الشاشات حسب الأحداث وحسب الحالة المشترَكة

نعمل حاليًا على إعداد وصفة للروابط المؤدية إلى محتوى معيّن، بالإضافة إلى عملية دمج مع Koin، ولدينا الكثير من الوصفات الأخرى المخطط لها. نشر أحد المهندسين من JetBrains أيضًا إصدارًا من الوصفات متوافقًا مع Compose Multiplatform.

إذا كان لديك حالة استخدام شائعة تريد الحصول على وصفة لها، يُرجى إرسال طلب وصفة. 

ملخّص

لبدء استخدام Nav3، اطّلِع على المستندات والوصفات. بالإضافة إلى ذلك، ترقَّب أسبوعًا كاملاً من المحتوى الفني، بما في ذلك: 

• فيديو مفصّل عن واجهة برمجة التطبيقات يغطّي التصميم المعياري والرسوم المتحركة والتنسيقات التكيّفية
• جلسة طرح أسئلة (AMA) مباشرة مع المهندسين الذين أنشأوا Nav3

يبدأ أسبوع Nav3 Spotlight في 1 ديسمبر 2025. 

كالعادة، يُرجى الإبلاغ عن أي مشاكل هنا.