Navigation 元件使用「導覽圖」管理應用程式的導覽。導覽圖是一種資料結構,其中包含應用程式內的各個目的地,以及目的地之間的連結。
目的地類型
目的地分為三種一般類型:代管、對話方塊和活動。下表概述這三種目的地類型及其用途。
類型 |
說明 |
用途 |
---|---|---|
代管 |
會填滿整個導覽主機。也就是說,代管目的地與導覽主機大小相同,因此無法顯示先前的目的地。 |
主要畫面和詳細資料畫面。 |
對話方塊 |
會顯示重疊的 UI 元件。此 UI 與導覽主機的位置或大小無關,先前的目的地可顯示在此目的地底下。 |
快訊、選取項目、表單。 |
活動 |
代表應用程式內的獨特畫面或功能。 |
做為導覽圖的結束點,啟動與該 Navigation 元件分開管理的新 Android 活動。 在 Modern Android Development 中,應用程式是由單一活動組成。因此,活動目的地最適合用於與第三方活動互動,或做為遷移程序的一部分。 |
本文件提供代管目的地的範例,這是最常見、也是基本的目的地。如需其他目的地的資訊,請參閱下列指南:
架構
雖然所有情況都適用相同的一般工作流程,但還是要根據所用 UI 架構,決定建立導覽主機和導覽圖的確切方式。
- Compose:使用
NavHost
可組合函式。使用NavGraph
Kotlin DSL。您可以透過下列兩種方式建立圖表:- 做為 NavHost 的一部分:直接在新增
NavHost
的過程中建構導覽圖。 - 透過程式輔助方式:使用
NavController.createGraph()
方法建立NavGraph
並直接傳遞至NavHost
。
- 做為 NavHost 的一部分:直接在新增
- 片段:搭配檢視區塊 UI 架構使用片段時,請使用
NavHostFragment
做為主機。您可以透過下列幾種方式建立導覽 圖表:- 透過程式輔助方式:使用 Kotlin DSL 建立
NavGraph
和 並直接在NavHostFragment
上套用。createGraph()
函式會與 Kotlin DSL 搭配使用 片段和 Compose 相同。
- XML:直接以 XML 編寫導覽主機和導覽圖。
- Android Studio 編輯器:使用 Android Studio 中的 GUI 編輯器,以 XML 資源檔案的形式建立及調整導覽圖。
- 透過程式輔助方式:使用 Kotlin DSL 建立
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.
}
- 可序列化物件代表兩條路徑,
Profile
和FriendsList
。 - 對
NavHost
可組合函式的呼叫會傳遞NavController
和路徑 做為起始目的地 - 傳遞至
NavHost
的 lambda 最終會呼叫NavController.createGraph()
並傳回NavGraph
。 - 每條路徑都會做為型別引數提供至
NavGraphBuilder.composable<T>()
,會將目的地新增至 結果NavGraph
。 - 傳遞至
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
。
最簡單的範例
NavController
和 NavHost
搭配運作的完整範例:
@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>
接下來,將 NavHostFragment
的 id
傳遞給 NavController.findNavController
,這會將 NavController 與
NavHostFragment
。
隨後,呼叫 NavController.createGraph()
會將圖表連結至
NavController
與 NavHostFragment
對應的內容如下:
@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 元件的一般總覽。
- 活動目的地:提供多個範例,說明如何實作會將使用者導向至活動的目的地。
- 對話方塊目的地:提供多個範例,說明如何建立會將使用者導向至對話方塊的目的地。
- 前往目的地:內容詳盡的指南,說明如何從某個目的地導覽至另一個目的地。
- 巢狀結構圖:關於如何建立單一導覽的深入指南 圖表內的兩個區塊