前往目的地

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. MyAppNavHostProfileScreen 新增至導覽圖時, 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 架構搭配使用。如要進一步瞭解這些超載,請參閱參考說明文件。

其他資訊

如需詳細資訊,請參閱以下頁面: