به یک مقصد حرکت کنید

کامپوننت ناوبری (Navigation) یک روش ساده و عمومی برای پیمایش به یک مقصد ارائه می‌دهد. این رابط از طیف وسیعی از زمینه‌ها و چارچوب‌های رابط کاربری (UI Frameworks) پشتیبانی می‌کند. برای مثال، می‌توانید از کامپوننت ناوبری (Navigation Components) با Compose، نماها (views)، فرگمنت‌ها (fragment)، فعالیت‌ها (activities) و حتی چارچوب‌های رابط کاربری سفارشی استفاده کنید.

این راهنما نحوه استفاده از کامپوننت ناوبری (Navigation) را برای پیمایش به یک مقصد در زمینه‌های مختلف شرح می‌دهد.

از یک NavController استفاده کنید

نوع کلیدی که برای جابجایی بین مقاصد استفاده می‌کنید، NavController است. برای اطلاعات بیشتر در مورد خود کلاس و نحوه ایجاد نمونه‌ای از آن، به بخش «ایجاد یک کنترلر ناوبری» مراجعه کنید. این راهنما نحوه استفاده از آن را شرح می‌دهد.

صرف نظر از اینکه از کدام چارچوب رابط کاربری استفاده می‌کنید، یک تابع واحد وجود دارد که می‌توانید برای پیمایش به یک مقصد از آن استفاده کنید: NavController.navigate() .

overload های زیادی برای navigate() وجود دارد. overload ای که باید انتخاب کنید دقیقاً با زمینه شما مطابقت داشته باشد. برای مثال، هنگام پیمایش به یک composable باید از یک overload و هنگام پیمایش به یک view از overload دیگری استفاده کنید.

بخش‌های زیر برخی از navigate() nav را که می‌توانید استفاده کنید، شرح می‌دهند.

به یک ترکیب‌پذیر بروید

برای رفتن به یک کامپوننت، باید از NavController.navigate<T> استفاده کنید. با این overload، navigate() یک آرگومان route واحد می‌گیرد که برای آن یک نوع ارسال می‌کنید. این آرگومان به عنوان کلید مقصد عمل می‌کند.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

برای پیمایش به یک composable در گراف ناوبری، ابتدا NavGraph خود را طوری تعریف کنید که هر مقصد با یک نوع مطابقت داشته باشد . برای composableها، این کار را با تابع composable() انجام می‌دهید.

رویدادها را از ترکیبات خود نمایش دهید

وقتی یک تابع composable نیاز به پیمایش به یک صفحه جدید دارد، نباید به آن ارجاعی به NavController بدهید تا بتواند مستقیماً navigate() فراخوانی کند. طبق اصول جریان داده یک‌طرفه (UDF) ، تابع composable باید رویدادی را که NavController مدیریت می‌کند، نمایش دهد.

به عبارت ساده‌تر، تابع composable شما باید پارامتری از نوع () -> Unit داشته باشد. وقتی با استفاده از تابع composable() به NavHost خود مقصد اضافه می‌کنید، تابع composable خود را به NavController.navigate() فراخوانی کنید.

برای مثالی از این مورد به زیربخش زیر مراجعه کنید.

مثال

به عنوان نمایشی از بخش‌های قبلی، این نکات را در قطعه کد زیر مشاهده کنید:

  1. هر مقصد در گراف با استفاده از یک مسیر (route) ایجاد می‌شود که یک شیء یا کلاس قابل سریال‌سازی است که داده‌های مورد نیاز آن مقصد را توصیف می‌کند.
  2. کامپوننت MyAppNavHost نمونه‌ی NavController را در خود نگه می‌دارد.
  3. بر این اساس، فراخوانی‌های تابع navigate() باید در آنجا رخ دهند و نه در یک کامپوننت سطح پایین‌تر مانند ProfileScreen .
  4. ProfileScreen حاوی دکمه‌ای است که با کلیک روی آن، کاربر به FriendsList هدایت می‌شود. با این حال، خودِ navigate() فراخوانی نمی‌کند.
  5. در عوض، دکمه تابعی را فراخوانی می‌کند که به عنوان پارامتر onNavigateToFriends نمایش داده می‌شود.
  6. وقتی MyAppNavHost ProfileScreen به گراف ناوبری اضافه می‌کند، برای onNavigateToFriends یک لامبدا ارسال می‌کند که تابع 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) overload را فراخوانی کنید. این تابع شناسه منبع یک اکشن یا یک مقصد را دریافت می‌کند. قطعه کد زیر نشان می‌دهد که چگونه می‌توانید از این overload برای پیمایش به 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);
  }
});

هنگام پیمایش با استفاده از شناسه‌ها، در صورت امکان باید از اقدامات (actions) استفاده کنید. اقدامات اطلاعات اضافی را در نمودار پیمایش شما ارائه می‌دهند و به صورت بصری نشان می‌دهند که چگونه مقاصد شما به یکدیگر متصل می‌شوند.

با استفاده از NavDeepLinkRequest پیمایش کنید

برای پیمایش به یک مقصد با پیوند عمیق ضمنی ، از سربارگذاری (overload 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، action و نوع MIME باید همگی با NavDeepLink در مقصد مطابقت داشته باشند. URIها باید با الگو مطابقت داشته باشند، actionها باید دقیقاً مطابقت داشته باشند و انواع MIME باید مرتبط باشند. برای مثال، image/jpg با image/\* مطابقت دارد.

زمینه‌های بیشتر

این سند نحوه استفاده از NavController.navigate() را در رایج‌ترین موارد استفاده پوشش می‌دهد. با این حال، این تابع دارای طیف وسیعی از overloadها است که می‌توانید در زمینه‌های مختلف و همراه با هر چارچوب رابط کاربری از آنها استفاده کنید. برای جزئیات بیشتر در مورد این overloadها، به مستندات مرجع مراجعه کنید.

مطالعه بیشتر

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