導覽列

導覽列可讓使用者在應用程式中切換目的地。您應在下列情況下使用導覽列：

  • 三到五個同等重要目的地
  • 精簡視窗大小
  • 在應用程式各個畫面中提供一致的目的地
包含 4 個目的地的導覽列。每個目的地都有一個名為
圖 1. 包含 4 個目的地的導覽列。

本頁面說明如何在應用程式中顯示導覽列，並提供相關畫面和基本導覽功能。

API 介面

使用 NavigationBar 和 NavigationBarItem 可組合函式來實作目的地切換邏輯。每個 NavigationBarItem 都代表單一目的地。

NavigationBarItem 包含下列重要參數：

  • selected：決定是否要視覺醒目顯示目前項目。
  • onClick()：這是必要的 lambda 函式，可定義使用者點選項目時要執行的動作。您通常會在此處處理導覽事件、更新所選項目狀態，或載入對應內容。
  • label：在項目中顯示文字。選用項目。
  • icon：在項目中顯示圖示。選用項目。

範例：底部導覽列

以下程式碼片段會實作底部導覽列，其中包含項目，讓使用者可以在應用程式中的不同畫面間導覽：

@Composable
fun NavigationBarExample(modifier: Modifier = Modifier) {
    val navController = rememberNavController()
    val startDestination = Destination.SONGS
    var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) }

    Scaffold(
        modifier = modifier,
        bottomBar = {
            NavigationBar(windowInsets = NavigationBarDefaults.windowInsets) {
                Destination.entries.forEachIndexed { index, destination ->
                    NavigationBarItem(
                        selected = selectedDestination == index,
                        onClick = {
                            navController.navigate(route = destination.route)
                            selectedDestination = index
                        },
                        icon = {
                            Icon(
                                destination.icon,
                                contentDescription = destination.contentDescription
                            )
                        },
                        label = { Text(destination.label) }
                    )
                }
            }
        }
    ) { contentPadding ->
        AppNavHost(navController, startDestination, modifier = Modifier.padding(contentPadding))
    }
}
Navigation.kt

重點

  • NavigationBar 會顯示一組項目，其中每個項目都對應至 Destination。
  • val navController = rememberNavController() 會建立並記住 NavHostController 的例項，用於管理 NavHost 中的導覽。
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } 會管理目前所選項目的狀態。
  • var selectedDestination by rememberSaveable { mutableIntStateOf(startDestination.ordinal) } 會管理目前選取項目的狀態。
    • startDestination.ordinal 會取得 Destination.SONGS 列舉項目的數字索引 (位置)。
  • 點選項目時，系統會呼叫 navController.navigate(route = destination.route) 以前往對應的畫面。
  • NavigationBarItem 的 onClick lambda 會更新 selectedDestination 狀態，以視覺方式醒目顯示已點選的項目。
  • 它會呼叫 AppNavHost 可組合函式，傳遞 navController 和 startDestination，以便顯示所選畫面的實際內容。

結果

下圖顯示上一個程式碼片段產生的導覽列：

應用程式畫面，底部導覽列中水平列出 3 個目的地：歌曲、專輯和播放清單。每個目的地都會搭配相關的圖示 (例如「歌曲」的音符)。
圖 2. 導覽列包含 3 個目的地，以及相關聯的圖示：歌曲、專輯和播放清單。

其他資源