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

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

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

استخدام NavController

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

التنقّل

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

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

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

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

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

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

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

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

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

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

راجِع القسم الفرعي التالي للاطّلاع على مثال.

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

مثال

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

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

@Serializable
object Profile
@Serializable
object FriendsList

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),

) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = Profile
    ) {
        composable<Profile> {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate(route = 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