導覽元件使用「導覽圖」管理應用程式的導覽。導覽圖是一種資料結構,其中包含應用程式內的各個目的地,以及各個目的地之間的連線。
目的地類型
目的地分為三種一般類型:代管、對話方塊和活動。下表概述這三種目的地類型及其用途。
類型 |
說明 |
用途 |
---|---|---|
代管 |
填滿整個導覽主機。這表示代管目的地的大小與導覽主機的大小相同,而且不會顯示先前的目的地。 |
主要畫面和詳細資料畫面。 |
對話方塊 |
顯示重疊 UI 元件。此 UI 不會與導覽主機的位置或大小相關聯,先前的目的地會顯示在目的地下方。 |
快訊、選項、表單。 |
活動 |
代表應用程式中獨特的畫面或功能。 |
做為導覽圖的結束點,讓新的 Android 活動與導覽元件分開管理。 在 Modern Android Development 中,應用程式是由單一活動組成。因此,活動目的地最適合用於與第三方活動互動,或做為遷移程序的一部分。 |
本文件包含代管目的地的範例,最常見的目的地和基本目的地。請參閱下列指南,瞭解其他目的地的資訊:
架構
雖然每個情況下都適用相同的一般工作流程,但建立導覽主機和圖表的方式取決於您使用的 UI 架構。
- Compose:使用
NavHost
可組合項。使用 Kotlin DSL 建立NavGraph
。您可以透過下列兩種方式建立圖表:- 做為 NavHost 的一部分:直接在新增
NavHost
的過程中建構導覽圖。 - 透過程式輔助方式:使用
NavController.createGraph()
方法建立NavGraph
並直接傳送至NavHost
。
- 做為 NavHost 的一部分:直接在新增
- 片段:搭配檢視畫面 UI 架構使用片段時,請使用
NavHostFragment
做為主機。您可以透過下列幾種方式建立導覽圖表:- 透過程式輔助方式:使用 Kotlin DSL 建立
NavGraph
,並直接套用至NavHostFragment
。- 片段和 Compose 搭配使用的
createGraph()
函式與 Kotlin DSL 相同。
- 片段和 Compose 搭配使用的
- XML:直接使用 XML 編寫導覽主機和圖表。
- Android Studio 編輯器:使用 Android Studio 中的 GUI 編輯器,以 XML 資源檔案的形式建立及調整圖表。
- 透過程式輔助方式:使用 Kotlin DSL 建立
Compose
在 Compose 中,使用 NavHost
可組合項建立導覽圖表。請參考以下範例:
val navController = rememberNavController()
NavHost(navController = navController, startDestination = "profile") {
composable("profile") { Profile( /* ... */ ) }
composable("friendslist") { FriendsList( /* ... */ ) }
// Add more destinations similarly.
}
- 對
NavHost
可組合項的呼叫會傳遞NavController
和對應至起始目的地的route
字串。 - 傳遞至
NavHost
的 lambda 最終會呼叫NavController.creatGraph()
並傳回NavGraph
。 - 對
NavGraphBuilder.composable()
的呼叫會在產生的NavGraph
中新增目的地。 - 在這個範例中,目的地是
Profile
和FriendsList
可組合項。路徑字串"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)
最小示例
共同運作的 NavController
和 NavHost
最小但完整範例:
// 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>
接下來,將 NavHostFragment
的 id
傳遞給 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,如上一節所述。
詳情請參閱「導覽編輯器」。
巢狀結構圖
您也可以使用巢狀結構圖。這包括使用圖表做為導覽目的地。如需更多資訊,請參閱巢狀圖表。
其他資訊
如要進一步瞭解核心導覽概念,請參閱下列指南:
- 總覽:請務必閱讀導覽元件的一般總覽。
- 活動目的地:如何實作會將使用者導向活動的目的地範例。
- 對話方塊目的地:如何建立會將使用者導向對話方塊的目的地範例。
- 前往目的地:內容詳盡的指南,說明如何從某個目的地導覽至另一個目的地。
- 巢狀圖形:如何將導覽圖巢狀至另一個導覽圖的深度指南。