前往目的地

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() 的呼叫傳遞至可組合函式。

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

警告：請勿將 NavController 傳遞至可組合函式，將事件公開為 。

範例

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

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")
    }
}

警告： 您只應呼叫 navigate() 做為回呼的一部分，而不是將其做為回呼的一部分 可組合項目這可避免在每次呼叫navigate() 重組。

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

注意：如果是按鈕，Navigation.createNavigateOnClickListener() 會有三種變化版本。這些變化版本在您使用 Java 程式設計語言時非常實用。如果您使用 Kotlin，OnClickListener 會是 SAM 介面，因此您可以使用追蹤 lambda。相較於直接呼叫 createNavigateOnClickListener()，此方法更簡潔，更容易讀取。

注意：如要處理其他常見的 UI 元件 (例如頂端應用程式列和底部導覽列)，請參閱「透過 NavigationUI 更新 UI 元件」。

使用 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 進行導覽不同的是，無論目的地是否可見，您都可以透過圖表前往任何深層連結。您可以前往目前圖表上的目的地，也可以前往完全不同圖表上的目的地。

注意：使用 NavDeepLinkRequest 進行導覽時，返回堆疊「不會」重設。這個行為與深層連結導覽的其他形式不同。不過，popUpTo() 和 popUpToInclusive() 仍會從返回堆疊中將目的地移除，就如同您使用 ID 瀏覽一樣。

注意：為了方便起見，你也可以使用在 DeepLinkRequest 中納入 Uri 的 navigate(Uri)。

操作和 MIME 類型

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

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

其他情況

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

其他資訊

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

• 建立導覽控制器
• 導覽與返回堆疊
• 使用選項進行導覽
• Kotlin DSL 和 Navigation Compose 中的類型安全