يوفر مكوِّن التنقل طريقة مباشرة وعامة للانتقال إلى وجهة ما. تدعم هذه الواجهة مجموعة من السياقات وإطارات عمل واجهة المستخدم. على سبيل المثال، يمكنك استخدام مكون التنقل مع الإنشاء، وطرق العرض، والأجزاء، والأنشطة، وحتى أطر عمل واجهة المستخدم المخصصة.
يصف هذا الدليل كيف يمكنك استخدام مكوِّن التنقل للانتقال إلى وجهة في سياقات مختلفة.
استخدام وحدة تحكم في التنقل
نوع المفتاح الذي تستخدمه للتنقل بين الوجهات هو 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()
.
راجِع القسم الفرعي التالي للاطّلاع على مثال لذلك.
مثال
كعرض توضيحي للأقسام السابقة، لاحظ هذه النقاط في المقتطف التالي:
- يتم إنشاء كل وجهة في الرسم البياني باستخدام مسار، وهو عبارة عن كائن أو فئة قابلة للتتابع تصف البيانات المطلوبة من تلك الوجهة.
- يتضمّن العنصر
MyAppNavHost
القابل للإنشاء المثيلNavController
. - وفقًا لذلك، يجب أن يتم إجراء المكالمات إلى
navigate()
هناك وليس بلغة قابلة للإنشاء، مثلProfileScreen
. - يحتوي
ProfileScreen
على زر ينقل المستخدم إلىFriendsList
عند النقر عليه. ومع ذلك، لا يستدعيnavigate()
نفسه. - بدلاً من ذلك، يستدعي الزر دالة تظهر كمَعلمة
onNavigateToFriends
. - عندما يضيف
MyAppNavHost
ProfileScreen
إلى الرسم البياني للتنقّل، بالنسبة إلىonNavigateToFriends
، يجتاز دالة لامدا التي تستدعيnavigate(route = FriendsList
). - يضمن ذلك أنّه عندما يضغط المستخدم على الزر
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
:
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);
}
});
عند التنقل باستخدام أرقام التعريف، يجب استخدام الإجراءات كلما أمكن ذلك. توفر الإجراءات معلومات إضافية في الرسم البياني للتنقل، وتعرض بشكل مرئي كيفية ارتباط وجهاتك ببعضها البعض.
التنقّل باستخدام 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)
على عكس التنقل باستخدام أرقام تعريف الوجهة أو الإجراءات، يمكنك الانتقال إلى أي رابط لصفحة معيّنة في الرسم البياني، بغض النظر عما إذا كانت الوجهة مرئية أم لا. يمكنك الانتقال إلى وجهة على الرسم البياني الحالي أو وجهة على رسم بياني مختلف تمامًا.
الإجراءات وأنواع MIME
بالإضافة إلى Uri
، يتيح NavDeepLinkRequest
أيضًا الروابط لصفحات في التطبيق باستخدام الإجراءات وأنواع MIME. لإضافة إجراء إلى الطلب، استخدِم fromAction()
أو setAction()
. لإضافة نوع MIME إلى طلب،
استخدِم fromMimeType()
أو setMimeType()
.
لكي يطابق NavDeepLinkRequest
بشكل صحيح وجهة رابط ضمني لصفحة في التطبيق، يجب أن يتطابق معرّف الموارد المنتظم (URI) والإجراء ونوع MIME مع NavDeepLink
في الوجهة. يجب أن تتطابق معرفات الموارد المنتظمة (URI) مع النمط، ويجب أن تكون الإجراءات متطابقة تمامًا،
ويجب أن تكون أنواع MIME ذات صلة. على سبيل المثال، تتطابق السمة image/jpg
مع السمة image/\*
.
سياقات إضافية
يتناول هذا المستند كيفية استخدام NavController.navigate()
في حالات الاستخدام الأكثر شيوعًا. ومع ذلك، تحتوي الدالة على مجموعة من التحميلات الزائدة يمكنك استخدامها في سياقات مختلفة، وإلى جانب أي إطار عمل لواجهة المستخدم. راجع الوثائق المرجعية لمزيد من التفاصيل حول هذه الأحمال الزائدة.
محتوى إضافي للقراءة
لمزيد من المعلومات، يُرجى الاطّلاع على الصفحات التالية:
- إنشاء وحدة تحكُّم في التنقُّل
- التنقّل وحزمة الخلفية
- التنقّل باستخدام الخيارات
- أمان الكتابة في Kotlin DSL و Navigation Compose