يقدّم مكوّن التنقّل دعمًا لتطبيقات Jetpack Compose. يمكنك التنقّل بين العناصر القابلة للتجميع مع الاستفادة من البنية الأساسية والميزات في عنصر التنقّل.
ضبط إعدادات الجهاز
لتوفير ميزة Compose، استخدِم التبعية التالية في ملف build.gradle
الخاص بوحدة تطبيقك:
dependencies { def nav_version = "2.8.8" implementation "androidx.navigation:navigation-compose:$nav_version" }
dependencies { val nav_version = "2.8.8" implementation("androidx.navigation:navigation-compose:$nav_version") }
البدء
عند تنفيذ ميزة التنقّل في تطبيق، عليك تنفيذ مضيف تنقّل ورسم بياني و عنصر تحكّم. لمزيد من المعلومات، يُرجى الاطّلاع على النظرة العامة حول التنقّل.
إنشاء NavController
للحصول على معلومات حول كيفية إنشاء NavController
في Compose، راجِع قسم "إنشاء" في إنشاء وحدة تحكّم في التنقّل.
إنشاء NavHost
للحصول على معلومات عن كيفية إنشاء NavHost
في ميزة "الإنشاء"، يُرجى الاطّلاع على قسم "الإنشاء"
في مقالة تصميم الرسم البياني للتنقّل.
الانتقال إلى عنصر قابل للإنشاء
للحصول على معلومات عن الانتقال إلى عنصر Composable، يُرجى الاطّلاع على الانتقال إلى وجهة في مستندات التصميم.
التنقّل باستخدام الوسيطات
للحصول على معلومات حول تمرير الوسيطات بين الوجهات القابلة للإنشاء، راجِع القسم "إنشاء" في تصميم الرسم البياني للتنقّل.
استرداد البيانات المعقدة عند التنقل
ننصح بشدة بعدم تمرير عناصر بيانات معقّدة عند التنقّل، وبدلاً من ذلك، تمرير الحد الأدنى من المعلومات اللازمة، مثل معرّف فريد أو شكل آخر من أشكال المعرّفات، كوسيطات عند تنفيذ إجراءات التنقّل:
// Pass only the user ID when navigating to a new destination as argument
navController.navigate(Profile(id = "user1234"))
يجب تخزين العناصر المعقدة كبيانات في مصدر واحد للحقيقة، مثل
طبقة البيانات. بعد الوصول إلى وجهتك بعد التنقّل، يمكنك تحميل المعلومات المطلوبة من مصدر واحد باستخدام رقم التعريف الذي تم تمريره. لاسترداد الوسيطات في ViewModel
المسؤولة عن
الوصول إلى طبقة البيانات، استخدِم SavedStateHandle
ViewModel
:
class UserViewModel(
savedStateHandle: SavedStateHandle,
private val userInfoRepository: UserInfoRepository
) : ViewModel() {
private val profile = savedStateHandle.toRoute<Profile>()
// Fetch the relevant user information from the data layer,
// ie. userInfoRepository, based on the passed userId argument
private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(profile.id)
// …
}
يساعد هذا الأسلوب على منع فقدان البيانات أثناء تغييرات التهيئة وأي تناقضات عند تحديث الكائن المعني أو تغييره.
للحصول على شرح أكثر تفصيلاً حول سبب تجنُّب تمرير البيانات المعقدة كصعوبات، بالإضافة إلى قائمة بأنواع الصعوبات المتوافقة، اطّلِع على مقالة تمرير البيانات بين الوجهات.
روابط لصفحات معيّنة
تدعم ميزة "إنشاء التنقل" الروابط لمواضع معيّنة التي يمكن تحديدها كجزء من وظيفة composable()
أيضًا. تقبل المَعلمة deepLinks
قائمة بعناصر
NavDeepLink
التي يمكن إنشاؤها بسرعة باستخدام الطريقة
navDeepLink()
:
@Serializable data class Profile(val id: String)
val uri = "https://www.example.com"
composable<Profile>(
deepLinks = listOf(
navDeepLink<Profile>(basePath = "$uri/profile")
)
) { backStackEntry ->
ProfileScreen(id = backStackEntry.toRoute<Profile>().id)
}
تتيح لك هذه الروابط لصفحات معيّنة ربط عنوان URL أو إجراء أو نوع MIME مع ملف
قابل للتركيب. ولا تكون هذه الروابط لصفحات في التطبيق متاحة للتطبيقات الخارجية تلقائيًا. لجعل هذه الروابط لصفحات في التطبيق متاحة خارجيًا، يجب إضافة عناصر
<intent-filter>
المناسبة إلى ملف manifest.xml
في تطبيقك. لتفعيل الرابط المؤدي إلى صفحة معيّنة في المثال السابق، عليك إضافة ما يلي داخل عنصر
<activity>
في البيان:
<activity …>
<intent-filter>
...
<data android:scheme="https" android:host="www.example.com" />
</intent-filter>
</activity>
تؤدي عملية التنقّل تلقائيًا إلى إنشاء رابط لصفحة في التطبيق عندما يشغّل تطبيق آخر الرابط لصفحة في التطبيق.
يمكن أيضًا استخدام هذه الروابط لصفحات في التطبيق نفسها لإنشاء PendingIntent
باستخدام الرابط المؤدي لصفحة معيّنة مناسبة من عنصر قابل للإنشاء:
val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
Intent.ACTION_VIEW,
"https://www.example.com/profile/$id".toUri(),
context,
MyActivity::class.java
)
val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
addNextIntentWithParentStack(deepLinkIntent)
getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}
يمكنك بعد ذلك استخدام هذا deepLinkPendingIntent
مثل أي PendingIntent
آخر ل
فتح تطبيقك في وجهة الرابط لصفحة في التطبيق.
التنقّل المتداخل
للحصول على معلومات حول كيفية إنشاء رسوم بيانية متداخلة للتنقّل، يُرجى الاطّلاع على الرسومات البيانية المضمَّنة.
الدمج مع شريط التنقّل السفلي
من خلال تحديد NavController
على مستوى أعلى في التسلسل الهرمي القابل للتجميع،
يمكنك ربط Navigation بمكونات أخرى، مثل مكونات التنقل في أسفل الشاشة. يتيح لك القيام بذلك التنقل عن طريق تحديد
الأيقونات في الشريط السفلي.
لاستخدام مكوّنات BottomNavigation
وBottomNavigationItem
،
أضِف التبعية androidx.compose.material
إلى تطبيق Android.
dependencies { implementation "androidx.compose.material:material:1.7.5" } android { buildFeatures { compose true } composeOptions { kotlinCompilerExtensionVersion = "1.5.15" } kotlinOptions { jvmTarget = "1.8" } }
dependencies { implementation("androidx.compose.material:material:1.7.5") } android { buildFeatures { compose = true } composeOptions { kotlinCompilerExtensionVersion = "1.5.15" } kotlinOptions { jvmTarget = "1.8" } }
لربط العناصر في شريط التنقّل السفلي بالمسارات في الرسم البياني للتنقّل،
ننصح بتحديد فئة، مثل TopLevelRoute
المعروضة هنا، التي تحتوي على
فئة مسار ورمز.
data class TopLevelRoute<T : Any>(val name: String, val route: T, val icon: ImageVector)
بعد ذلك، ضَع هذه المسارات في قائمة يمكن استخدامها من قِبل
BottomNavigationItem
:
val topLevelRoutes = listOf(
TopLevelRoute("Profile", Profile, Icons.Profile),
TopLevelRoute("Friends", Friends, Icons.Friends)
)
في BottomNavigation
القابلة للإنشاء، احصل على NavBackStackEntry
الحالي
باستخدام الدالة currentBackStackEntryAsState()
. يمنحك هذا الإدخال إذن الوصول
إلى NavDestination
الحالي. يمكن بعد ذلك تحديد الحالة المحدّدة لكل
BottomNavigationItem
من خلال مقارنة مسار العنصر بمسار الوجهة الحالية ووجهاتها الرئيسية للتعامل مع الحالات
عند استخدام التنقل المدمج باستخدام التدرّج الهرمي NavDestination
.
يتم أيضًا استخدام مسار العنصر لربط onClick
lambda باستدعاء
navigate
بحيث يؤدي النقر على العنصر إلى الانتقال إلى ذلك العنصر. باستخدام علامتَي
saveState
وrestoreState
، يتم حفظ الحالة والمكدس الخلفي لهذا العنصر
بشكل صحيح واستعادتهما عند التبديل بين عناصر شريط التنقّل في أسفل الشاشة.
val navController = rememberNavController()
Scaffold(
bottomBar = {
BottomNavigation {
val navBackStackEntry by navController.currentBackStackEntryAsState()
val currentDestination = navBackStackEntry?.destination
topLevelRoutes.forEach { topLevelRoute ->
BottomNavigationItem(
icon = { Icon(topLevelRoute.icon, contentDescription = topLevelRoute.name) },
label = { Text(topLevelRoute.name) },
selected = currentDestination?.hierarchy?.any { it.hasRoute(topLevelRoute.route::class) } == true,
onClick = {
navController.navigate(topLevelRoute.route) {
// Pop up to the start destination of the graph to
// avoid building up a large stack of destinations
// on the back stack as users select items
popUpTo(navController.graph.findStartDestination().id) {
saveState = true
}
// Avoid multiple copies of the same destination when
// reselecting the same item
launchSingleTop = true
// Restore state when reselecting a previously selected item
restoreState = true
}
}
)
}
}
}
) { innerPadding ->
NavHost(navController, startDestination = Profile, Modifier.padding(innerPadding)) {
composable<Profile> { ProfileScreen(...) }
composable<Friends> { FriendsScreen(...) }
}
}
وهنا يمكنك الاستفادة من طريقة NavController.currentBackStackEntryAsState()
لرفع الحالة navController
من الدالة NavHost
ومشاركتها مع المكوِّن BottomNavigation
. وهذا يعني أنّه
BottomNavigation
تتضمن تلقائيًا أحدث حالة.
إمكانية التشغيل التفاعلي
إذا كنت تريد استخدام مكوِّن التنقل مع ميزة Compose، فلديك خياران:
- حدِّد رسمًا بيانيًا للتنقّل باستخدام مكوّن التنقّل للمقاطع.
- حدّد رسمًا بيانيًا للتنقل مع
NavHost
في Compose باستخدام وجهات Compose. لا يمكن ذلك إلا إذا كانت جميع الشاشات في الرسم البياني للتنقل قابلة للإنشاء.
لذلك، ننصحك باستخدام المكوّن التنقّل المستنِد إلى المقتطفات في التطبيقات المختلطة التي تتضمّن ميزتَي "إنشاء" و"عرض". ستحتوي الأجزاء بعد ذلك على شاشات مستندة إلى "العرض" وشاشات "الإنشاء" والشاشات التي تستخدم كلّ من "العرض" و"الإنشاء". بعد أن تصبح محتويات كل قطعة في "أداة الإنشاء"، تكون الخطوة التالية هي ربط كل هذه الشاشات معًا باستخدام "أداة التنقّل" وإزالة كل القطع.
التنقّل من ميزة "الإنشاء" باستخدام ميزة "التنقّل" للأجزاء
لتغيير الوجهات داخل رمز الإنشاء، عليك عرض الأحداث التي يمكن تمريرها إلى أيّ عنصر قابل للتركيب في التسلسل الهرمي وتشغيله:
@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}
في المقتطف، يمكنك إنشاء رابط بين Compose ومكوّن التنقّل المستنِد إلى المقتطف من خلال العثور على NavController
والانتقال إلى الوجهة:
override fun onCreateView( /* ... */ ) {
setContent {
MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
}
}
بدلاً من ذلك، يمكنك تمرير NavController
لأسفل التسلسل الهرمي "إنشاء".
ومع ذلك، فإنّ عرض الدوال البسيطة يمكن إعادة استخدامها واختبارها بشكلٍ أكبر.
الاختبار
عليك فصل رمز التنقّل عن الوجهات القابلة للتجميع لتتمكّن من اختبار
كل عنصر قابل للتجميع بشكل منفصل، بمعزل عن العنصر القابل للتجميع NavHost
.
وهذا يعني أنّه يجب عدم تمرير navController
مباشرةً إلى أي عنصر
قابل للتجميع، بل يجب تمرير طلبات استدعاء التنقّل كمَعلمات. يتيح ذلك اختبار
جميع العناصر القابلة للتجميع بشكلٍ فردي، لأنّها لا تتطلّب
مثيلًا من navController
في الاختبارات.
إنّ مستوى التوجيه غير المباشر الذي يوفّره composable
lambda هو ما يتيح لك
فصل رمز التنقّل عن العنصر القابل للتجميع نفسه. ويعمل ذلك في اتجاهين:
- لا تُمرِّر سوى الوسائط التي تم تحليلها إلى العنصر القابل للتجميع.
- نقْل الدوالّ التي يجب أن يبدأها العنصر القابل للتجميع للتنقّل، بدلاً من
NavController
نفسه
على سبيل المثال، قد يتضمّن العنصر القابل للتجميع ProfileScreen
الذي يأخذ userId
كمدخل ويسمح للمستخدمين بالانتقال إلى صفحة الملف الشخصي لصديق التوقيع التالي:
@Composable
fun ProfileScreen(
userId: String,
navigateToFriendProfile: (friendUserId: String) -> Unit
) {
…
}
بهذه الطريقة، تعمل العناصر القابلة للتجميع في ProfileScreen
بشكل مستقل عن التنقّل،
ما يتيح اختبارها بشكل مستقل. ستُغلِّف دالة composable
lambda
الحد الأدنى من المنطق المطلوب لسد الفجوة بين واجهات برمجة التطبيقات
للتنقّل والعنصر القابل للتجميع:
@Serializable data class Profile(id: String)
composable<Profile> { backStackEntry ->
val profile = backStackEntry.toRoute<Profile>()
ProfileScreen(userId = profile.id) { friendUserId ->
navController.navigate(route = Profile(id = friendUserId))
}
}
نقترح عليك كتابة اختبارات تغطي متطلبات التنقّل في التطبيق من خلال اختبار NavHost
وإجراءات التنقّل التي يتم تمريرها إلى العناصر القابلة للإنشاء بالإضافة إلى العناصر الفردية القابلة للإنشاء.
اختبار NavHost
لبدء اختبار NavHost
، أضِف التبعية التالية لاختبار التنقّل:
dependencies {
// ...
androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
// ...
}
احرِص على تضمين NavHost
في تطبيقك ضمن عنصر قابل للتجميع يقبل NavHostController
كمَعلمة.
@Composable
fun AppNavHost(navController: NavHostController){
NavHost(navController = navController){ ... }
}
يمكنك الآن اختبار AppNavHost
وكل منطق التنقّل المحدّد داخل
NavHost
من خلال تمرير مثيل لعنصر اختبار التنقّل
TestNavHostController
. سيظهر اختبار واجهة المستخدم الذي يتحقق من وجهة البدء ل
تطبيقك وNavHost
على النحو التالي:
class NavigationTest {
@get:Rule
val composeTestRule = createComposeRule()
lateinit var navController: TestNavHostController
@Before
fun setupAppNavHost() {
composeTestRule.setContent {
navController = TestNavHostController(LocalContext.current)
navController.navigatorProvider.addNavigator(ComposeNavigator())
AppNavHost(navController = navController)
}
}
// Unit test
@Test
fun appNavHost_verifyStartDestination() {
composeTestRule
.onNodeWithContentDescription("Start Screen")
.assertIsDisplayed()
}
}
اختبار إجراءات التنقّل
يمكنك اختبار تنفيذ التنقّل بطرق متعدّدة، من خلال تنفيذ نقرات على عناصر واجهة المستخدم، ثم التحقّق من الوجهة المعروضة أو مقارنة المسار المتوقّع بالمسار الحالي.
بما أنّك تريد اختبار تنفيذ تطبيقك المحدّد، يُفضَّل استخدام النقرات على واجهة المستخدم. للتعرّف على كيفية اختبار ذلك إلى جانب الدوالّ القابلة للتجميع الفردية بشكل منفصل، احرص على الاطّلاع على الاختبار في Jetpack Compose codelab.
يمكنك أيضًا استخدام navController
للتحقق من تأكيداتك من خلال مقارنة
المسار الحالي بالطريق المتوقّع، باستخدام currentBackStackEntry
في navController
:
@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
composeTestRule.onNodeWithContentDescription("All Profiles")
.performScrollTo()
.performClick()
assertTrue(navController.currentBackStackEntry?.destination?.hasRoute<Profile>() ?: false)
}
للحصول على مزيد من الإرشادات حول أساسيات اختبار Compose، يمكنك الاطّلاع على اختبار تنسيق Compose والاختبار في Jetpack Compose في ورشة التعلم. للاطّلاع على مزيد من المعلومات عن الاختبار المتقدّم لرمز التنقّل، يُرجى الانتقال إلى دليل اختبار التنقّل.
مزيد من المعلومات
للاطّلاع على مزيد من المعلومات عن Jetpack Navigation، اطّلِع على مقالة البدء في استخدام ملف Navigation البرمجي أو اطّلِع على الدليل التعليمي حول ملف التنقّل في Jetpack Compose.
للتعرّف على كيفية تصميم تنقّل تطبيقك ليتلاءم مع أحجام الشاشة واتجاهاتها وأشكالها المختلفة، اطّلِع على مقالة التنقّل في واجهات المستخدم السريعة الاستجابة.
للتعرّف على طريقة أكثر تقدمًا لتنفيذ تنقّل Compose في تطبيق مُقسَّم إلى وحدات، بما في ذلك مفاهيم مثل الرسوم البيانية المتداخلة ودمج شريط التنقّل في أسفل الشاشة، يمكنك الاطّلاع على تطبيق Now in Android على GitHub.
نماذج
ما من اقتراحات في الوقت الحالي.
يُرجى محاولة تسجيل الدخول إلى حسابك على Google.