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

يوفّر مكوّن التنقّل طريقة مباشرة وعامة للتنقّل إلى وجهة معيّنة. تتوافق هذه الواجهة مع مجموعة من السياقات وأُطر عمل واجهة المستخدم. على سبيل المثال، يمكنك استخدام "مكوّن التنقّل" مع 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().

يمكنك الاطّلاع على القسم الفرعي التالي للحصول على مثال على ذلك.

مثال

لإثبات صحة ما ورد في الأقسام السابقة، راجِع النقاط التالية في المقتطف التالي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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