前往目的地

Navigation 元件提供了簡單通用的方式 前往目的地。這個介面適用於多種情況和 UI 架構。舉例來說，您可以將 Navigation 元件與 Compose 搭配使用。 檢視畫面、片段、活動，甚至是自訂 UI 架構。

本指南說明如何使用 Navigation 元件，瀏覽至 不同的目的地

使用 NavController

在目的地之間移動的金鑰類型為 NavController。 如要進一步瞭解類別本身，請參閱建立導覽控制器。 以及如何建立其例項本指南將詳細說明如何使用。

無論您使用何種 UI 架構，都可以透過 NavController.navigate() 這個單一函式前往目的地。

navigate() 有許多超載可用。您應根據自身確切情況選擇相應的超載。舉例來說，前往可組合函式和檢視畫面時，應分別使用不同的超載。

以下各節會概述幾個主要的 navigate() 超載 相關單位會如何運用資料，並讓他們覺得自己 獲得充分告知，且能夠針對該使用方式表示同意

導覽至可組合函式

如要前往可組合函式，您應使用 NavController.navigate<T>。 透過這個超載，navigate() 會使用單一 route 引數， 傳遞型別這可做為目的地的索引鍵。

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

如要前往導覽圖中的可組合函式，請先定義 NavGraph 使每個目的地都對應一個類型。適用對象 可以組合成對了，只要使用 composable() 函式即可。

從可組合函式公開事件

當可組合函式需要前往新的畫面時，您不應向其傳遞 NavController 參照，這樣才能直接呼叫 navigate()。根據單向資料流程 (UDF) 原則，可組合元件 應改為公開 NavController 處理的事件。

更直接地說，可組合函式應含有 () -> Unit 類型的參數。如果您使用 composable() 函式在 NavHost 中新增目的地，請將對 NavController.navigate() 的呼叫傳遞至可組合函式。

如需範例，請參閱以下子節。

範例

如以上各節所示，請在 程式碼片段：

  1. 圖表中的每個目的地都是透過路線建立， 可序列化的物件或類別，用來說明該物件需要的資料 目的地。
  2. MyAppNavHost 可組合函式會保留 NavController 例項。
  3. 因此，對 navigate() 的呼叫應該會在其中發生，而不是在 ProfileScreen 這類階層較低的可組合函式中。
  4. ProfileScreen 包含一個按鈕，可在使用者點選時將使用者導向 FriendsList。不過，此按鈕本身不會呼叫 navigate()。
  5. 取而代之的是，按鈕會呼叫要公開為 onNavigateToFriends 參數的函式。
  6. 當 MyAppNavHost 將 ProfileScreen 新增至導覽圖時， onNavigateToFriends 會傳遞呼叫 navigate(route = FriendsList 的 lambda)。
  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")
    }
}

使用整數 ID 進行導覽

如要使用整數 ID 前往目的地，請呼叫 navigate(int) 超載，這會使用一項操作或一個目的地的資源 ID。下列程式碼片段顯示如何使用這個超載前往 ViewTransactionsFragment：

Kotlin

viewTransactionsButton.setOnClickListener { view ->
  view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
      Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
  }
});

使用 ID 進行導覽時，應盡可能使用操作。操作可在瀏覽圖中提供其他資訊，以視覺化的方式呈現出目的地之間如何相互連結。

使用 NavDeepLinkRequest 進行導覽

如要前往隱含深層連結目的地，請使用 navigate(NavDeepLinkRequest) 超載。下列程式碼片段說明這個方法的實作方式：

Kotlin

val request = NavDeepLinkRequest.Builder
  .fromUri("android-app://androidx.navigation.app/profile".toUri())
  .build()
findNavController().navigate(request)

Java

NavDeepLinkRequest request = NavDeepLinkRequest.Builder
  .fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
  .build()
NavHostFragment.findNavController(this).navigate(request)

與使用操作或目的地 ID 進行導覽不同的是，無論目的地是否可見，您都可以透過圖表前往任何深層連結。您可以前往目前圖表上的目的地，也可以前往完全不同圖表上的目的地。

操作和 MIME 類型

除了 Uri 以外，NavDeepLinkRequest 也支援含有操作及 MIME 類型的深層連結。如要在要求中新增操作，請使用 fromAction() 或 setAction()；如要在要求中加入 MIME 類型，請使用 fromMimeType() 或 setMimeType()。

為了讓 NavDeepLinkRequest 正確比對隱含深層連結目的地，URI、操作及 MIME 類型都必須與目的地中的 NavDeepLink 相符。URI 必須與模式相符、操作須完全相符，而 MIME 類型必須具有關聯性。例如 image/jpg 就與 image/\* 相符。

其他情況

本文件說明 NavController.navigate() 最常見的用途和使用方式。但是，該函式有多種超載功能，可供您在不同情況下使用，甚至能與任何 UI 架構搭配使用。如要進一步瞭解這些超載，請參閱參考說明文件。

其他資訊

如需詳細資訊，請參閱以下頁面：