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

مولفه Navigation یک راه ساده و عمومی برای پیمایش به مقصد ارائه می دهد. این رابط از طیف وسیعی از زمینه ها و چارچوب های UI پشتیبانی می کند. برای مثال، می‌توانید از مؤلفه Navigation با Compose، نماها، قطعات، فعالیت‌ها و حتی چارچوب‌های سفارشی UI استفاده کنید.

این راهنما توضیح می دهد که چگونه می توانید از مؤلفه ناوبری برای پیمایش به مقصد در زمینه های مختلف استفاده کنید.

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

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

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

اضافه بارهای زیادی برای navigate() موجود است. اضافه باری که باید انتخاب کنید با زمینه دقیق شما مطابقت دارد. به عنوان مثال، هنگام پیمایش به یک Composable باید از یک اضافه بار استفاده کنید و هنگام پیمایش به یک View از دیگری استفاده کنید.

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

به یک کامپوزیشن پیمایش کنید

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

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

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

رویدادها را از اجزای سازنده خود افشا کنید

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

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

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

مثال

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

  1. هر مقصد در نمودار با استفاده از یک مسیر ایجاد می شود که یک شی یا کلاس قابل سریال سازی است که داده های مورد نیاز آن مقصد را توصیف می کند.
  2. MyAppNavHost composable نمونه 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) فراخوانی کنید. شناسه منبع یک اقدام یا مقصد را می گیرد. قطعه کد زیر نشان می دهد که چگونه می توانید از این اضافه بار برای پیمایش به 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);
  }
});

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

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

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

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

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

در ادامه مطلب

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

،

مولفه ناوبری یک راه ساده و عمومی برای پیمایش به مقصد ارائه می دهد. این رابط از طیف وسیعی از زمینه ها و چارچوب های UI پشتیبانی می کند. برای مثال، می‌توانید از مؤلفه Navigation با Compose، نماها، قطعات، فعالیت‌ها و حتی چارچوب‌های سفارشی UI استفاده کنید.

این راهنما توضیح می دهد که چگونه می توانید از مؤلفه ناوبری برای پیمایش به مقصد در زمینه های مختلف استفاده کنید.

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

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

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

اضافه بارهای زیادی برای navigate() موجود است. اضافه باری که باید انتخاب کنید با زمینه دقیق شما مطابقت دارد. به عنوان مثال، هنگام پیمایش به یک Composable باید از یک اضافه بار استفاده کنید و هنگام پیمایش به یک View از دیگری استفاده کنید.

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

به یک کامپوزیشن پیمایش کنید

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

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

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

رویدادها را از اجزای سازنده خود افشا کنید

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

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

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

مثال

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

  1. هر مقصد در نمودار با استفاده از یک مسیر ایجاد می شود که یک شی یا کلاس قابل سریال سازی است که داده های مورد نیاز آن مقصد را توصیف می کند.
  2. MyAppNavHost composable نمونه 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) فراخوانی کنید. شناسه منبع یک اقدام یا مقصد را می گیرد. قطعه کد زیر نشان می دهد که چگونه می توانید از این اضافه بار برای پیمایش به 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);
  }
});

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

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

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

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

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

در ادامه مطلب

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