مؤلفه Navigation از یک نمودار ناوبری برای مدیریت ناوبری برنامه شما استفاده می کند. نمودار ناوبری یک ساختار داده است که شامل هر مقصد در برنامه شما و ارتباطات بین آنها است.
انواع مقصد
سه نوع کلی مقصد وجود دارد: میزبانی، گفتگو و فعالیت. جدول زیر این سه نوع مقصد و اهداف آنها را نشان می دهد.
تایپ کنید | توضیحات | موارد استفاده کنید |
---|---|---|
میزبانی شد | کل میزبان ناوبری را پر می کند. یعنی اندازه یک مقصد میزبانی شده با اندازه میزبان ناوبری برابر است و مقاصد قبلی قابل مشاهده نیستند. | صفحه نمایش اصلی و جزئیات. |
گفتگو | اجزای رابط کاربری همپوشانی را ارائه می دهد. این رابط کاربری به مکان میزبان ناوبری یا اندازه آن وابسته نیست. مقاصد قبلی در زیر مقصد قابل مشاهده است. | هشدارها، انتخابها، فرمها |
فعالیت | نمایشگر صفحه نمایش یا ویژگی های منحصر به فرد در برنامه است. | به عنوان نقطه خروجی برای نمودار پیمایش که فعالیت Android جدیدی را شروع میکند که جدا از مؤلفه ناوبری مدیریت میشود، استفاده کنید. در توسعه مدرن اندروید، یک برنامه از یک فعالیت واحد تشکیل شده است. بنابراین، هنگام تعامل با فعالیتهای شخص ثالث یا بهعنوان بخشی از فرآیند مهاجرت، از مقاصد فعالیت بهتر استفاده میشود. |
این سند شامل نمونه هایی از مقاصد میزبانی شده است که رایج ترین و اساسی ترین مقصدها هستند. برای اطلاعات در مورد سایر مقاصد به راهنماهای زیر مراجعه کنید:
چارچوب ها
اگرچه گردش کار کلی یکسان در هر موردی اعمال می شود، نحوه ایجاد یک هاست ناوبری و نمودار دقیقاً به چارچوب UI که استفاده می کنید بستگی دارد.
- نوشتن: از
NavHost
composable استفاده کنید. با استفاده از Kotlin DSL یکNavGraph
به آن اضافه کنید. شما می توانید نمودار را به دو روش ایجاد کنید:- به عنوان بخشی از NavHost: نمودار ناوبری را مستقیماً به عنوان بخشی از افزودن
NavHost
بسازید. - به صورت برنامه نویسی: از متد
NavController.createGraph()
برای ایجاد یکNavGraph
و ارسال مستقیم آن بهNavHost
استفاده کنید.
- به عنوان بخشی از NavHost: نمودار ناوبری را مستقیماً به عنوان بخشی از افزودن
- Fragments: هنگام استفاده از قطعات با چارچوب UI views، از
NavHostFragment
به عنوان میزبان استفاده کنید. چندین راه برای ایجاد نمودار ناوبری وجود دارد:- به صورت برنامه نویسی: از Kotlin DSL برای ایجاد
NavGraph
استفاده کنید و مستقیماً آن را درNavHostFragment
اعمال کنید.- تابع
createGraph()
مورد استفاده با Kotlin DSL برای هر دو قطعه و Compose یکسان است.
- تابع
- XML: میزبان ناوبری و نمودار خود را مستقیماً در XML بنویسید.
- ویرایشگر Android Studio: از ویرایشگر رابط کاربری گرافیکی در Android Studio برای ایجاد و تنظیم نمودار خود به عنوان یک فایل منبع XML استفاده کنید.
- به صورت برنامه نویسی: از Kotlin DSL برای ایجاد
نوشتن
در Compose، از یک شی یا کلاس قابل سریال برای تعریف مسیر استفاده کنید. یک مسیر نحوه رسیدن به یک مقصد را توصیف می کند و شامل تمام اطلاعات مورد نیاز مقصد است. هنگامی که مسیرهای خود را مشخص کردید، از NavHost
composable برای ایجاد نمودار ناوبری خود استفاده کنید. به مثال زیر توجه کنید:
@Serializable
object Profile
@Serializable
object FriendsList
val navController = rememberNavController()
NavHost(navController = navController, startDestination = Profile) {
composable<Profile> { ProfileScreen( /* ... */ ) }
composable<FriendsList> { FriendsListScreen( /* ... */ ) }
// Add more destinations similarly.
}
- یک شیء قابل سریال سازی هر یک از دو مسیر
Profile
وFriendsList
را نشان می دهد. - تماس با
NavHost
composable یکNavController
و یک مسیر برای مقصد شروع میکند. - لامبدا ارسال شده به
NavHost
در نهایتNavController.createGraph()
را فراخوانی می کند وNavGraph
برمی گرداند. - هر مسیر به عنوان آرگومان نوع به
NavGraphBuilder.composable<T>()
ارائه می شود که مقصد را بهNavGraph
حاصل اضافه می کند. - لامبدا ارسال شده به
composable
چیزی است کهNavHost
برای آن مقصد نمایش می دهد.
لامبدا را درک کنید
برای درک بهتر لامبدا که NavGraph
ایجاد می کند، در نظر بگیرید که برای ساختن همان نموداری که در قطعه قبلی وجود دارد، می توانید NavGraph
به طور جداگانه با استفاده از NavController.createGraph()
ایجاد کنید و آن را مستقیماً به NavHost
ارسال کنید:
val navGraph by remember(navController) {
navController.createGraph(startDestination = Profile)) {
composable<Profile> { ProfileScreen( /* ... */ ) }
composable<FriendsList> { FriendsListScreen( /* ... */ ) }
}
}
NavHost(navController, navGraph)
تصویب آرگومان ها
اگر نیاز به ارسال داده به مقصد دارید، مسیر را با کلاسی که دارای پارامتر است تعریف کنید. به عنوان مثال، مسیر Profile
یک کلاس داده با یک پارامتر name
است.
@Serializable
data class Profile(val name: String)
هر زمان که نیاز دارید آرگومان هایی را به آن مقصد ارسال کنید، یک نمونه از کلاس مسیر خود ایجاد می کنید و آرگومان ها را به سازنده کلاس ارسال می کنید.
نمونه مسیر را بدست آورید
می توانید نمونه مسیر را با NavBackStackEntry.toRoute()
یا SavedStateHandle.toRoute()
بدست آورید. هنگامی که با استفاده از composable()
یک مقصد ایجاد می کنید، NavBackStackEntry
به عنوان یک پارامتر در دسترس است.
@Serializable
data class Profile(val name: String)
val navController = rememberNavController()
NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(name = profile.name) }
}
در این قطعه به موارد زیر توجه کنید:
- مسیر
Profile
مقصد شروع را در نمودار ناوبری مشخص میکند و"John Smith"
به عنوان آرگومانname
. - مقصد خود بلوک
composable<Profile>{}
است. - Composable
ProfileScreen
مقدارprofile.name
را برای آرگومانname
خود می گیرد. - به این ترتیب، مقدار
"John Smith"
بهProfileScreen
منتقل می شود.
نمونه حداقلی
یک مثال کامل از همکاری NavController
و NavHost
با هم:
@Serializable
data class Profile(val name: String)
@Serializable
object FriendsList
// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
profile: Profile
onNavigateToFriendsList: () -> Unit,
) {
Text("Profile for ${profile.name}")
Button(onClick = { onNavigateToFriendsList() }) {
Text("Go to Friends List")
}
}
// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
Text("Friends List")
Button(onClick = { onNavigateToProfile() }) {
Text("Go to Profile")
}
}
// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
val navController = rememberNavController()
NavHost(navController, startDestination = Profile(name = "John Smith")) {
composable<Profile> { backStackEntry ->
val profile: Profile = backStackEntry.toRoute()
ProfileScreen(
profile = profile,
onNavigateToFriendsList = {
navController.navigate(route = FriendsList)
}
)
}
composable<FriendsList> {
FriendsListScreen(
onNavigateToProfile = {
navController.navigate(
route = Profile(name = "Aisha Devi")
)
}
)
}
}
}
همانطور که قطعه نشان می دهد، به جای انتقال NavController
به composable های خود، یک رویداد را در NavHost
نمایش دهید. یعنی، composable های شما باید پارامتری از نوع () -> Unit
داشته باشند که NavHost
برای آن یک لامبدا ارسال می کند که NavController.navigate()
فراخوانی می کند.
قطعات
همانطور که در بخشهای قبل توضیح داده شد، هنگام استفاده از قطعات، میتوانید با استفاده از Kotlin DSL، XML یا ویرایشگر Android Studio، یک نمودار ناوبری به صورت برنامهنویسی ایجاد کنید.
بخش های بعدی این رویکردهای مختلف را شرح می دهد.
به صورت برنامه ای
Kotlin DSL روشی برنامهریزی شده برای ایجاد یک نمودار ناوبری با قطعات ارائه میدهد. از بسیاری جهات این ساده تر و مدرن تر از استفاده از یک فایل منبع XML است.
مثال زیر را در نظر بگیرید که یک نمودار ناوبری دو صفحه ای را پیاده سازی می کند.
ابتدا لازم است NavHostFragment
ایجاد شود، که نباید شامل عنصر app:navGraph
باشد:
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.fragment.app.FragmentContainerView
android:id="@+id/nav_host_fragment"
android:name="androidx.navigation.fragment.NavHostFragment"
android:layout_width="match_parent"
android:layout_height="match_parent" />
</FrameLayout>
سپس، id
NavHostFragment
را به NavController.findNavController
ارسال کنید. این NavController را با NavHostFragment
مرتبط می کند.
متعاقباً، فراخوانی به NavController.createGraph()
نمودار را به NavController
و در نتیجه به NavHostFragment
پیوند می دهد:
@Serializable
data class Profile(val name: String)
@Serializable
object FriendsList
// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)
// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
startDestination = Profile(name = "John Smith")
) {
// Associate each destination with one of the route constants.
fragment<ProfileFragment, Profile> {
label = "Profile"
}
fragment<FriendsListFragment, FriendsList>() {
label = "Friends List"
}
// Add other fragment destinations similarly.
}
استفاده از DSL در این روش بسیار شبیه به جریان کاری است که در بخش قبلی در Compose توضیح داده شد. برای مثال، هم آنجا و هم اینجا، تابع NavController.createGraph()
NavGraph
تولید می کند. به همین ترتیب، در حالی که NavGraphBuilder.composable()
مقاصد قابل ترکیب را به نمودار اضافه می کند، در اینجا NavGraphBuilder.fragment()
یک مقصد قطعه اضافه می کند.
برای اطلاعات بیشتر در مورد نحوه استفاده از Kotlin DSL، به ساخت نمودار با NavGraphBuilder DSL مراجعه کنید.
XML
شما می توانید به طور مستقیم XML را خودتان بنویسید. مثال زیر منعکس کننده و معادل مثال دو صفحه ای از بخش قبل است.
ابتدا یک NavHostFragment
ایجاد کنید. این به عنوان میزبان ناوبری که شامل نمودار ناوبری واقعی است عمل می کند.
اجرای حداقلی از NavHostFragment
:
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<androidx.fragment.app.FragmentContainerView
android:id="@+id/nav_host_fragment"
android:name="androidx.navigation.fragment.NavHostFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:navGraph="@navigation/nav_graph" />
</FrameLayout>
NavHostFragment
حاوی ویژگی app:navGraph
. از این ویژگی برای اتصال نمودار ناوبری خود به میزبان ناوبری استفاده کنید. در زیر نمونه ای از نحوه پیاده سازی نمودار آورده شده است:
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:id="@+id/nav_graph"
app:startDestination="@id/profile">
<fragment
android:id="@+id/profile"
android:name="com.example.ProfileFragment"
android:label="Profile">
<!-- Action to navigate from Profile to Friends List. -->
<action
android:id="@+id/action_profile_to_friendslist"
app:destination="@id/friendslist" />
</fragment>
<fragment
android:id="@+id/friendslist"
android:name="com.example.FriendsListFragment"
android:label="Friends List" />
<!-- Add other fragment destinations similarly. -->
</navigation>
شما از اقدامات برای تعریف ارتباطات بین مقاصد مختلف استفاده می کنید. در این مثال، قطعه profile
حاوی عملی است که به friendslist
هدایت می شود. برای اطلاعات بیشتر، به استفاده از اقدامات و قطعات ناوبری مراجعه کنید.
ویرایشگر
میتوانید نمودار پیمایش برنامهتان را با استفاده از ویرایشگر پیمایش در Android Studio مدیریت کنید. این اساساً یک رابط کاربری گرافیکی است که میتوانید برای ایجاد و ویرایش NavigationFragment
XML خود، همانطور که در بخش قبل مشاهده شد، استفاده کنید.
برای اطلاعات بیشتر، ویرایشگر پیمایش را ببینید.
نمودارهای تو در تو
می توانید از نمودارهای تو در تو نیز استفاده کنید. این شامل استفاده از یک نمودار به عنوان مقصد ناوبری است. برای اطلاعات بیشتر، نمودارهای تودرتو را ببینید.
ادامه مطلب
برای مفاهیم اصلی ناوبری بیشتر، به راهنماهای زیر مراجعه کنید:
- نمای کلی : حتماً نمای کلی مولفه ناوبری را بخوانید.
- مقصدهای فعالیت : نمونه هایی از نحوه پیاده سازی مقاصدی که کاربر را به سمت فعالیت ها می برد.
- مقصدهای گفتگو : نمونه هایی از نحوه ایجاد مقاصدی که کاربر را به یک گفتگو می برد.
- پیمایش به مقصد : راهنمای دقیقی که نحوه پیمایش از یک مقصد به مقصد دیگر را پوشش می دهد.
- نمودارهای تودرتو : راهنمای عمیق در مورد نحوه قرار دادن یک نمودار ناوبری در دیگری.