設計導覽圖

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

目的地類型

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

類型

說明

用途

代管

填滿整個導覽主機。這表示代管目的地的大小與導覽主機的大小相同,而且不會顯示先前的目的地。

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

對話方塊

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

快訊、選項、表單。

活動

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

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

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

本文件包含代管目的地的範例,最常見的目的地和基本目的地。請參閱下列指南,瞭解其他目的地的資訊:

架構

雖然每個情況下都適用相同的一般工作流程,但建立導覽主機和圖表的方式取決於您使用的 UI 架構。

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

Compose

在 Compose 中,使用 NavHost 可組合項建立導覽圖表。請參考以下範例:

val navController = rememberNavController()

NavHost(navController = navController, startDestination = "profile") {
    composable("profile") { Profile( /* ... */ ) }
    composable("friendslist") { FriendsList( /* ... */ ) }
    // Add more destinations similarly.
}
  1. NavHost 可組合項的呼叫會傳遞 NavController 和對應至起始目的地的 route 字串。
  2. 傳遞至 NavHost 的 lambda 最終會呼叫 NavController.creatGraph() 並傳回 NavGraph
  3. NavGraphBuilder.composable() 的呼叫會在產生的 NavGraph 中新增目的地。
  4. 在這個範例中,目的地是 ProfileFriendsList 可組合項。路徑字串 "profile""friendslist" 會成為識別兩個目的地的索引鍵。

如要進一步瞭解建立 NavGraph 的 lambda,請考慮要建構與上述程式碼片段相同的圖表,您可以使用 NavController.createGraph() 分別建立 NavGraph,並直接將其傳遞至 NavHost

val navGraph by remember(navController) {
  navController.createGraph(startDestination = "profile") {
    composable("profile") { Profile() }
    composable("friendslist") { FriendsList() }
  }
}
NavHost(navController, navGraph)

最小示例

共同運作的 NavControllerNavHost 最小但完整範例:

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

// Define the FriendsList composable.
@Composable
fun FriendsList(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") {
    composable("profile") { Profile(onNavigateToFriendsList = { navController.navigate("friendslist") }) }
    composable("friendslist") { FriendsList(onNavigateToProfile = { navController.navigate("profile") }) }
  }
}

如程式碼片段所示,向 NavHost 公開事件,而不是將 NavController 傳遞至可組合項。也就是說,您的可組合項應包含 () -> Unit 類型的參數,而 NavHost 會將該類型的參數傳遞給 NavController.navigate()

片段

如前節所述,使用片段時,您可以選擇使用 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() 會將圖表連結至 NavController,因此也會連結至 NavHostFragment

// 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"
) {
    // 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 中的「導覽編輯器」管理應用程式的導覽圖。基本上就是可用來建立及編輯 NavigationFragment XML 的 GUI,如上一節所述。

詳情請參閱「導覽編輯器」。

巢狀結構圖

您也可以使用巢狀結構圖。這包括使用圖表做為導覽目的地。如需更多資訊,請參閱巢狀圖表

其他資訊

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

  • 總覽請務必閱讀導覽元件的一般總覽。
  • 活動目的地如何實作會將使用者導向活動的目的地範例。
  • 對話方塊目的地如何建立會將使用者導向對話方塊的目的地範例。
  • 前往目的地內容詳盡的指南,說明如何從某個目的地導覽至另一個目的地。
  • 巢狀圖形如何將導覽圖巢狀至另一個導覽圖的深度指南。