الانتقال إلى وجهة معيّنة

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

يصف هذا الدليل كيف يمكنك استخدام مكوِّن التنقل للانتقال إلى وجهة في سياقات مختلفة.

استخدام وحدة تحكم في التنقل

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

التنقّل

بغض النظر عن إطار عمل واجهة المستخدم الذي تستخدمه، هناك دالة واحدة يمكنك استخدامها للانتقال إلى وجهة معيّنة، وهي: NavController.navigate().

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

توضّح الأقسام التالية بعض أحمال navigate() الزائدة التي يمكنك استخدامها.

الانتقال إلى عنصر قابل للإنشاء

للانتقال إلى عنصر قابل للإنشاء في الرسم البياني للتنقّل، استخدِم NavController.navigate(route). مع هذا التحميل الزائد، يأخذ navigate() وسيطة String واحدة. يَتِمُّ الْآنْ تَشْغِيلْ route. إنها بمثابة المفتاح للوجهة.

navController.navigate("friendslist")

للتنقّل باستخدام سلسلة route، عليك أولاً إنشاء NavGraph ليتم ربط كل وجهة بـ route. بالنسبة إلى العناصر القابلة للإنشاء، يمكنك إجراء ذلك باستخدام الدالة composable().

لمزيد من المعلومات، يُرجى الاطّلاع على الانتقال إلى وجهة معيّنة.

عرض الأحداث من العناصر القابلة للإنشاء

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

بعبارة أخرى، يجب أن تكون معلَمة من النوع () -> Unit في العنصر القابل للإنشاء. عند إضافة وجهات إلى NavHost باستخدام الوظيفة composable()، يمكنك تمرير مكالمة قابلة للإنشاء إلى NavController.navigate().

راجِع القسم الفرعي التالي للاطّلاع على مثال واضح على ذلك.

تحذير: لا ترسِل NavController إلى العناصر القابلة للإنشاء. اعرض حدثًا كما هو موضّح هنا.

مثال

كعرض توضيحي للقسم السابق، لاحظ هذه النقاط في المقتطف التالي:

1. يتضمّن العنصر MyAppNavHost القابل للإنشاء المثيل NavController.
2. وفقًا لذلك، يجب أن يتم إجراء المكالمات إلى navigate() هناك وليس بلغة قابلة للإنشاء، مثل ProfileScreen.
3. يحتوي ProfileScreen على زر ينقل المستخدم إلى FriendsList عند النقر عليه. ومع ذلك، لا يستدعي navigate() نفسه.
4. بدلاً من ذلك، يستدعي الزر دالة تظهر كمَعلمة onNavigateToFriends.
5. عندما يضيف MyAppNavHost ProfileScreen إلى الرسم البياني للتنقّل، بالنسبة إلى onNavigateToFriends، يجتاز دالة لامدا التي تستدعي navigate().
6. يضمن ذلك أنّه عندما يضغط المستخدم على الزر ProfileScreen، سيتم نقله بشكل صحيح إلى friendsList.

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),
    startDestination: String = "profile"
) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = startDestination
    ) {
        composable("profile") {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate("friendsList") },
                /*...*/
            )
        }
        composable("friendslist") { FriendsListScreen(/*...*/) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /*...*/
) {
    /*...*/
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

تحذير: يجب استخدام السمة navigate() فقط كجزء من عملية معاودة الاتصال وليس كجزء من المحتوى القابل للإنشاء نفسه. يؤدي ذلك إلى تجنُّب استدعاء navigate() في كل عملية إعادة تركيب.

التنقّل باستخدام رقم تعريف العدد الصحيح

للانتقال إلى وجهة باستخدام رقم تعريف عدد صحيح، استدعِ الحمل الزائد navigate(int). يأخذ رقم تعريف المورد لإجراء أو وجهة. ويوضّح مقتطف الرمز التالي كيفية استخدام هذا التحميل الزائد للانتقال إلى ViewTransactionsFragment:

Kotlin

viewTransactionsButton.setOnClickListener { view ->
  view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
      Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
  }
});

عند التنقل باستخدام أرقام التعريف، يجب استخدام الإجراءات كلما أمكن ذلك. توفر الإجراءات معلومات إضافية في الرسم البياني للتنقل، وتعرض بشكل مرئي كيفية ارتباط وجهاتك ببعضها البعض.

ملاحظة: بالنسبة إلى الأزرار، تتوفّر ثلاثة صيغ للسمة Navigation.createNavigateOnClickListener(). هذه المتغيرات مفيدة إذا كنت تستخدم لغة برمجة Java. إذا كنت تستخدم لغة Kotlin، تكون OnClickListener واجهة SAM، لذا يمكنك استخدام دالة lambda اللاحقة. ويمكن أن يكون هذا النهج أقصر وأسهل في القراءة من طلب createNavigateOnClickListener() مباشرةً.

ملاحظة: للتعامل مع المكونات الشائعة الأخرى لواجهة المستخدم، مثل شريط التطبيق العلوي والتنقّل السفلي، يُرجى الاطّلاع على تحديث مكوّنات واجهة المستخدم باستخدام NavigationUI.

التنقّل باستخدام NavDeepLinkRequest

للانتقال إلى وجهة ضمن رابط لصفحة في التطبيق، استخدِم حِمل navigate(NavDeepLinkRequest) الزائد. يوفر المقتطف التالي تنفيذًا لهذه الطريقة:

Kotlin

val request = NavDeepLinkRequest.Builder
  .fromUri("android-app://androidx.navigation.app/profile".toUri())
  .build()
findNavController().navigate(request)

Java

NavDeepLinkRequest request = NavDeepLinkRequest.Builder
  .fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
  .build()
NavHostFragment.findNavController(this).navigate(request)

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

تنبيه: عند التنقّل باستخدام NavDeepLinkRequest، لا إعادة ضبط الحزمة الخلفية. يختلف هذا السلوك عن الأشكال الأخرى من التنقل عبر روابط صفحات معيَّنة. في المقابل، لا يزال popUpTo() وpopUpToInclusive() يزيلان الوجهات من الحزمة الخلفية تمامًا كما لو كنت تنقَّل باستخدام رقم تعريف.

ملاحظة: للتيسير عليك، يمكنك أيضًا استخدام navigate(Uri) التي تضم Uri في DeepLinkRequest.

الإجراءات وأنواع MIME

بالإضافة إلى Uri، يتيح NavDeepLinkRequest أيضًا الروابط لصفحات في التطبيق باستخدام الإجراءات وأنواع MIME. لإضافة إجراء إلى الطلب، استخدِم fromAction() أو setAction(). لإضافة نوع MIME إلى طلب، استخدِم fromMimeType() أو setMimeType().

لكي يطابق NavDeepLinkRequest بشكل صحيح وجهة رابط ضمني لصفحة في التطبيق، يجب أن يتطابق معرّف الموارد المنتظم (URI) والإجراء ونوع MIME مع NavDeepLink في الوجهة. يجب أن تتطابق معرفات الموارد المنتظمة (URI) مع النمط، ويجب أن تكون الإجراءات متطابقة تمامًا، ويجب أن تكون أنواع MIME ذات صلة. على سبيل المثال، تتطابق السمة image/jpg مع السمة image/\*.

سياقات إضافية

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

محتوى إضافي للقراءة

لمزيد من المعلومات، يُرجى الاطّلاع على الصفحات التالية:

• إنشاء وحدة تحكُّم في التنقُّل
• التنقّل وحزمة الخلفية
• التنقّل باستخدام الخيارات
• أمان الكتابة في Kotlin DSL و Navigation Compose