設計導覽圖

Navigation 元件使用「導覽圖」管理應用程式的導覽。導覽圖是一種資料結構,其中包含應用程式內的各個目的地,以及目的地之間的連結。

目的地類型

目的地分為三種一般類型:代管、對話方塊和活動。下表概述這三種目的地類型及其用途。

類型

說明

用途

代管

會填滿整個導覽主機。也就是說,代管目的地與導覽主機大小相同,因此無法顯示先前的目的地。

主要畫面和詳細資料畫面。

對話方塊

會顯示重疊的 UI 元件。此 UI 與導覽主機的位置或大小無關,先前的目的地可顯示在此目的地底下。

快訊、選取項目、表單。

活動

代表應用程式內的獨特畫面或功能。

做為導覽圖的結束點,啟動與該 Navigation 元件分開管理的新 Android 活動。

在 Modern Android Development 中,應用程式是由單一活動組成。因此,活動目的地最適合用於與第三方活動互動,或做為遷移程序的一部分。

本文件提供代管目的地的範例,這是最常見、也是基本的目的地。如需其他目的地的資訊,請參閱下列指南:

架構

雖然所有情況都適用相同的一般工作流程,但還是要根據所用 UI 架構,決定建立導覽主機和導覽圖的確切方式。

  • Compose:使用 NavHost 可組合函式。使用NavGraph Kotlin DSL。您可以透過下列兩種方式建立圖表:
    • 做為 NavHost 的一部分:直接在新增 NavHost 的過程中建構導覽圖。
    • 透過程式輔助方式:使用 NavController.createGraph() 方法建立 NavGraph 並直接傳遞至 NavHost
  • 片段:搭配檢視區塊 UI 架構使用片段時,請使用 NavHostFragment 做為主機。您可以透過下列幾種方式建立導覽 圖表:
    • 透過程式輔助方式:使用 Kotlin DSL 建立 NavGraph 和 並直接在 NavHostFragment 上套用。
      • createGraph() 函式會與 Kotlin DSL 搭配使用 片段和 Compose 相同。
    • XML:直接以 XML 編寫導覽主機和導覽圖。
    • Android Studio 編輯器:使用 Android Studio 中的 GUI 編輯器,以 XML 資源檔案的形式建立及調整導覽圖。

Compose

在 Compose 中,使用可序列化物件或類別定義路徑。路線 說明如何前往目的地,並包含 目的地需要定義路徑後,請使用 NavHost 可建立導覽圖的可組合函式。請參考以下範例:

@Serializable
object Profile
@Serializable
object FriendsList

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
    // Add more destinations similarly.
}
  1. 可序列化物件代表兩條路徑,ProfileFriendsList
  2. NavHost 可組合函式的呼叫會傳遞 NavController 和路徑 做為起始目的地
  3. 傳遞至 NavHost 的 lambda 最終會呼叫 NavController.createGraph() 並傳回 NavGraph
  4. 每條路徑都會做為型別引數提供至 NavGraphBuilder.composable<T>(),會將目的地新增至 結果 NavGraph
  5. 傳遞至 composable 的 lambda 是 NavHost 顯示的內容 目的地。
,瞭解如何調查及移除這項存取權。

瞭解 lambda

如要進一步瞭解會建立 NavGraph 的 lambda,建議您建立與前述程式碼片段相同的圖表,使用 NavController.createGraph() 單獨建立 NavGraph,並直接傳遞至 NavHost

val navGraph by remember(navController) {
  navController.createGraph(startDestination = Profile)) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
  }
}
NavHost(navController, navGraph)

傳遞引數

如果您需要將資料傳遞至目的地,請使用 具有參數。舉例來說,Profile 路徑是具有 name 的資料類別 參數。

@Serializable
data class Profile(val name: String)

每當您需要將引數傳送至該目的地時,都可以建立執行個體 將引數傳遞至類別建構函式。

如果是選用引數,請以預設值建立可為空值的欄位。

@Serializable
data class Profile(val nickname: String? = null)

取得路徑執行個體

您可以使用 NavBackStackEntry.toRoute()SavedStateHandle.toRoute()。使用 composable()NavBackStackEntry 可做為參數使用。

@Serializable
data class Profile(val name: String)

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(name = profile.name) }
}

請注意這個程式碼片段中的以下內容:

  • Profile 路徑會指定導覽中的起始目的地 圖表,其中 "John Smith" 做為 name 的引數。
  • 目的地本身是 composable<Profile>{} 區塊。
  • ProfileScreen 可組合函式會根據 profile.name 的值自行使用 name 引數。
  • 因此,"John Smith" 值會傳遞至 ProfileScreen

最簡單的範例

NavControllerNavHost 搭配運作的完整範例:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
    profile: Profile
    onNavigateToFriendsList: () -> Unit,
  ) {
  Text("Profile for ${profile.name}")
  Button(onClick = { onNavigateToFriendsList() }) {
    Text("Go to Friends List")
  }
}

// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
  Text("Friends List")
  Button(onClick = { onNavigateToProfile() }) {
    Text("Go to Profile")
  }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
  val navController = rememberNavController()
  NavHost(navController, startDestination = Profile(name = "John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(
            profile = profile,
            onNavigateToFriendsList = {
                navController.navigate(route = FriendsList)
            }
        )
    }
    composable<FriendsList> {
      FriendsListScreen(
        onNavigateToProfile = {
          navController.navigate(
            route = Profile(name = "Aisha Devi")
          )
        }
      )
    }
  }
}

如程式碼片段所示,您應向 NavHost 公開事件,而不是將 NavController 傳遞至可組合函式。也就是說,可組合函式應提供 () -> Unit 類型的參數,讓 NavHost 傳遞呼叫 NavController.navigate() 的 lambda。

片段

如先前章節所述,使用片段時,您可以選擇使用 Kotlin DSL、XML 或 Android Studio 編輯器,透過程式輔助方式建立導覽圖。

以下各節將詳細說明這些不同做法。

透過程式輔助方式

Kotlin DSL 支援透過程式輔助方式,使用片段建立導覽圖。在許多方面,這種做法比使用 XML 資源檔案更簡潔,採用更現代化的技術。

請參考以下範例,當中會實作具有兩個畫面的導覽圖。

首先需要建立 NavHostFragment,其中「不得」包含 app:navGraph 元素:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

接下來,將 NavHostFragmentid 傳遞給 NavController.findNavController,這會將 NavController 與 NavHostFragment

隨後,呼叫 NavController.createGraph() 會將圖表連結至 NavControllerNavHostFragment 對應的內容如下:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = Profile(name = "John Smith")
) {
    // Associate each destination with one of the route constants.
    fragment<ProfileFragment, Profile> {
        label = "Profile"
    }

    fragment<FriendsListFragment, FriendsList>() {
        label = "Friends List"
    }

    // Add other fragment destinations similarly.
}

透過這種方式使用 DSL 與先前 Compose 一節所述的工作流程非常相似。例如,在這兩個流程中,NavController.createGraph() 函式都會產生 NavGraph。同樣地,NavGraphBuilder.composable() 會在圖表中加入可組合函式目的地,此處的 NavGraphBuilder.fragment() 則會加入片段目的地。

如要進一步瞭解如何使用 Kotlin DSL,請參閱「使用 NavGraphBuilder DSL 建構圖表」一文。

XML

您可以直接自行編寫 XML。以下範例等同於上一節的兩個畫面範例,會產生相同結果。

首先建立 NavHostFragment,做為包含實際導覽圖的導覽主機。

最簡單的 NavHostFragment 實作方式:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:navGraph="@navigation/nav_graph" />

</FrameLayout>

NavHostFragment 包含 app:navGraph 屬性。請使用這項屬性 將導覽圖連結至導覽主機。以下範例說明如何實作圖表:

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/profile">

    <fragment
        android:id="@+id/profile"
        android:name="com.example.ProfileFragment"
        android:label="Profile">

        <!-- Action to navigate from Profile to Friends List. -->
        <action
            android:id="@+id/action_profile_to_friendslist"
            app:destination="@id/friendslist" />
    </fragment>

    <fragment
        android:id="@+id/friendslist"
        android:name="com.example.FriendsListFragment"
        android:label="Friends List" />

    <!-- Add other fragment destinations similarly. -->
</navigation>

您可以使用動作定義不同目的地之間的連結。在本範例中,profile 片段包含前往 friendslist 的動作。詳情請參閱「使用導覽動作和片段」。

編輯者

您可以使用 Android Studio 中的 Navigation 編輯器管理應用程式的導覽圖。基本上,這個編輯器就是可用來建立及編輯 NavigationFragment XML 的 GUI,如上一節所示。

詳情請參閱「Navigation 編輯器」。

巢狀結構圖

您也可以使用巢狀結構圖,也就是使用圖表做為導覽目的地。詳情請參閱「巢狀結構圖」。

其他資訊

如要進一步瞭解核心導覽概念,請參閱下列指南:

  • 總覽請務必詳閱 Navigation 元件的一般總覽。
  • 活動目的地提供多個範例,說明如何實作會將使用者導向至活動的目的地。
  • 對話方塊目的地提供多個範例,說明如何建立會將使用者導向至對話方塊的目的地。
  • 前往目的地內容詳盡的指南,說明如何從某個目的地導覽至另一個目的地。
  • 巢狀結構圖關於如何建立單一導覽的深入指南 圖表內的兩個區塊