نمودار ناوبری خود را طراحی کنید

مؤلفه Navigation از یک نمودار ناوبری برای مدیریت ناوبری برنامه شما استفاده می کند. نمودار ناوبری یک ساختار داده است که شامل هر مقصد در برنامه شما و ارتباطات بین آنها است.

انواع مقصد

سه نوع کلی مقصد وجود دارد: میزبانی، گفتگو و فعالیت. جدول زیر این سه نوع مقصد و اهداف آنها را نشان می دهد.

این سند شامل نمونه هایی از مقاصد میزبانی شده است که رایج ترین و اساسی ترین مقصدها هستند. برای اطلاعات در مورد سایر مقاصد به راهنماهای زیر مراجعه کنید:

• مقصدهای گفتگو
• مقاصد فعالیت

چارچوب ها

اگرچه گردش کار کلی یکسان در هر موردی اعمال می شود، نحوه ایجاد یک هاست ناوبری و نمودار دقیقاً به چارچوب UI که استفاده می کنید بستگی دارد.

• نوشتن: از NavHost composable استفاده کنید. با استفاده از Kotlin DSL یک NavGraph به آن اضافه کنید. شما می توانید نمودار را به دو روش ایجاد کنید:
  • به عنوان بخشی از NavHost: نمودار ناوبری را مستقیماً به عنوان بخشی از افزودن NavHost بسازید.
  • به صورت برنامه نویسی: از متد NavController.createGraph() برای ایجاد یک NavGraph و ارسال مستقیم آن به NavHost استفاده کنید.
• Fragments: هنگام استفاده از قطعات با چارچوب UI views، از NavHostFragment به عنوان میزبان استفاده کنید. چندین راه برای ایجاد نمودار ناوبری وجود دارد:
  • به صورت برنامه نویسی: از Kotlin DSL برای ایجاد NavGraph استفاده کنید و مستقیماً آن را در NavHostFragment اعمال کنید.
    • تابع createGraph() مورد استفاده با Kotlin DSL برای هر دو قطعه و Compose یکسان است.
  • XML: میزبان ناوبری و نمودار خود را مستقیماً در XML بنویسید.
  • ویرایشگر Android Studio: از ویرایشگر رابط کاربری گرافیکی در Android Studio برای ایجاد و تنظیم نمودار خود به عنوان یک فایل منبع XML استفاده کنید.

نوشتن

در Compose، از یک شی یا کلاس قابل سریال برای تعریف مسیر استفاده کنید. یک مسیر نحوه رسیدن به یک مقصد را توصیف می کند و شامل تمام اطلاعات مورد نیاز مقصد است.

از حاشیه‌نویسی @Serializable برای ایجاد خودکار روش‌های سریال‌سازی و سریال‌زدایی لازم برای انواع مسیر خود استفاده کنید. این حاشیه نویسی توسط افزونه Kotlin Serialization ارائه شده است. برای افزودن این افزونه این دستورالعمل ها را دنبال کنید .

هنگامی که مسیرهای خود را مشخص کردید، از 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.
}

1. یک شیء قابل سریال سازی هر یک از دو مسیر Profile و FriendsList را نشان می دهد.
2. تماس با NavHost composable یک NavController و یک مسیر برای مقصد شروع می‌کند.
3. لامبدا ارسال شده به NavHost در نهایت NavController.createGraph() فراخوانی می کند و NavGraph برمی گرداند.
4. هر مسیر به عنوان آرگومان نوع به NavGraphBuilder.composable<T>() ارائه می شود که مقصد را به NavGraph حاصل اضافه می کند.
5. لامبدا ارسال شده به 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)

هر زمان که نیاز دارید آرگومان هایی را به آن مقصد ارسال کنید، یک نمونه از کلاس مسیر خود ایجاد می کنید و آرگومان ها را به سازنده کلاس ارسال می کنید.

برای آرگومان های اختیاری، فیلدهای nullable با مقدار پیش فرض ایجاد کنید.

@Serializable
data class Profile(val nickname: String? = null)

نمونه مسیر را بدست آورید

می توانید نمونه مسیر را با 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 خود، همانطور که در بخش قبل مشاهده شد، استفاده کنید.

برای اطلاعات بیشتر، ویرایشگر پیمایش را ببینید.

نمودارهای تو در تو

می توانید از نمودارهای تو در تو نیز استفاده کنید. این شامل استفاده از یک نمودار به عنوان مقصد ناوبری است. برای اطلاعات بیشتر، نمودارهای تودرتو را ببینید.

ادامه مطلب

برای مفاهیم اصلی ناوبری بیشتر، به راهنماهای زیر مراجعه کنید:

• نمای کلی : حتماً نمای کلی مولفه ناوبری را بخوانید.
• مقصدهای فعالیت : نمونه هایی از نحوه پیاده سازی مقاصدی که کاربر را به سمت فعالیت ها می برد.
• مقصدهای گفتگو : نمونه هایی از نحوه ایجاد مقاصدی که کاربر را به یک گفتگو می برد.
• پیمایش به مقصد : راهنمای دقیقی که نحوه پیمایش از یک مقصد به مقصد دیگر را پوشش می دهد.
• نمودارهای تودرتو : راهنمای عمیق در مورد نحوه قرار دادن یک نمودار ناوبری در دیگری.