應用程式列

應用程式列是容器，可讓使用者存取重要功能和導覽項目。應用程式列分為兩種：頂端應用程式列和底部應用程式列。外觀和用途分別如下：

類型	外觀	目的
頂端應用程式列	螢幕頂端。	提供重要工作和資訊的存取權。通常會顯示標題、核心待辦事項和特定導覽項目。
底部應用程式列	螢幕底部。	通常包含核心導覽項目。也可能提供其他重要動作的存取權，例如透過內含的懸浮動作按鈕。

圖 1. 頂端應用程式列 (左) 和底部應用程式列 (右)。

如要實作頂端和底部應用程式列，請分別使用 TopAppBar 和 BottomAppBar 可組合函式。您可以建立一致的介面，封裝導覽和動作控制項，並符合 Material Design 原則。

重要事項： 應用程式列通常會傳遞至 Scaffold 可組合函式，該函式具有接收這些列的特定參數。如要進一步瞭解 Scaffold 如何提供便利的方式來建構應用程式，請參閱 Scaffold 頁面。

頂端應用程式列

下表列出四種頂端應用程式列：

類型	範例
小型：適用於不需要太多導覽或動作的畫面。
置中對齊：適用於只有單一主要動作的畫面。
中等：適用於需要適量導覽和動作的畫面。
大型：適用於需要大量導覽和動作的畫面。

API 介面

可用來實作四種不同頂端應用程式列的各種可組合函式都相當類似。兩者有幾個共同的重要參數：

• title：顯示在應用程式列中的文字。
• navigationIcon：導覽的主要圖示。顯示在應用程式列左側。
• actions：可讓使用者執行重要動作的圖示。這些動作會顯示在應用程式列右側。
• scrollBehavior：決定頂端應用程式列如何回應 Scaffold 內部內容的捲動。
• colors：決定應用程式列的顯示方式。

捲動行為

您可以控制使用者捲動指定 Scaffold 的內部內容時，應用程式列的回應方式。如要這麼做，請建立 TopAppBarScrollBehavior 的例項，並將其傳遞至頂端應用程式列的 scrollBehavior 參數。

TopAppBarScrollBehavior 有三種類型。如下所示：

• enterAlwaysScrollBehavior：使用者向上拉動 Scaffold 的內部內容時，頂端應用程式列會收合。使用者開始下拉內部內容時，應用程式列會展開。
• exitUntilCollapsedScrollBehavior：與 enterAlwaysScrollBehavior 類似，但只有在使用者將內容完全向下拉時，應用程式列才會展開。
• pinnedScrollBehavior：應用程式列會固定在原位，不會隨著捲動而移動。

以下範例實作了其中幾個選項。

範例

以下各節將說明四種不同類型的頂端應用程式列實作方式，包括如何控制捲動行為的各種範例。

小

如要建立小型頂端應用程式列，請使用 TopAppBar 可組合函式。以下範例實作了僅包含標題的基本頂端應用程式列。

以下範例不會將 scrollBehavior 的值傳遞至 TopAppBar，因此不會對內部內容的捲動做出反應。

@Composable
fun SmallTopAppBarExample() {
    Scaffold(
        topBar = {
            TopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text("Small Top App Bar")
                }
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}
AppBar.kt

實作方式如下：

圖 2. 小型頂端應用程式列。

置中對齊

置中對齊的頂端應用程式列基本上與小型應用程式列相同，但標題會置中顯示在元件內。如要實作，請使用專屬的 CenterAlignedTopAppBar 可組合函式。

本範例使用 enterAlwaysScrollBehavior() 取得為 scrollBehavior 傳遞的值。因此，當使用者捲動 Scaffold 的內部內容時，列會收合。

@Composable
fun CenterAlignedTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),

        topBar = {
            CenterAlignedTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Centered Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior,
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}
AppBar.kt

實作方式如下：

圖 3. 置中對齊的頂端應用程式列。

中

中型頂端應用程式列會將標題置於任何其他圖示下方。如要建立，請使用 MediumTopAppBar 可組合函式。

與前一個程式碼片段一樣，這個範例使用 enterAlwaysScrollBehavior() 取得傳遞給 scrollBehavior 的值。

@Composable
fun MediumTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Medium Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}
AppBar.kt

這項實作如下所示，並示範 enterAlwaysScrollBehavior() 的捲動行為：

圖 4. 中型頂端應用程式列，會在使用者向上捲動時收合，向下捲動時展開。

大

大型頂端應用程式列與中型類似，但標題和圖示之間的邊框間距較大，且在螢幕上占用的空間較多。如要建立，請使用 LargeTopAppBar 可組合函式。

與上述程式碼片段不同，這個範例使用 exitUntilCollapsedScrollBehavior() 取得為 scrollBehavior 傳遞的值。因此，當使用者捲動 Scaffold 的內部內容時，列會收合，但當使用者捲動至內部內容結尾時，列會展開。

@Composable
fun LargeTopAppBarExample() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior(rememberTopAppBarState())

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                colors = TopAppBarDefaults.topAppBarColors(
                    containerColor = MaterialTheme.colorScheme.primaryContainer,
                    titleContentColor = MaterialTheme.colorScheme.primary,
                ),
                title = {
                    Text(
                        "Large Top App Bar",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
    ) { innerPadding ->
        ScrollContent(innerPadding)
    }
}
AppBar.kt

實作方式如下：

圖 5. 大型頂端應用程式列的實作範例。

底部應用程式列

如要建立底部應用程式列，請使用 BottomAppBar 可組合函式。這個可組合項的使用方式與本頁前幾節所述的頂端應用程式列可組合項非常相似。您需要為下列重要參數傳遞可組合函式：

• actions：顯示在狀態列左側的一系列圖示。這些通常是指定畫面的主要動作或導覽項目。
• floatingActionButton：顯示在列右側的懸浮動作按鈕。

@Composable
fun BottomAppBarExample() {
    Scaffold(
        bottomBar = {
            BottomAppBar(
                actions = {
                    IconButton(onClick = { /* do something */ }) {
                        Icon(Icons.Filled.Check, contentDescription = "Localized description")
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            Icons.Filled.Edit,
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            Icons.Filled.Mic,
                            contentDescription = "Localized description",
                        )
                    }
                    IconButton(onClick = { /* do something */ }) {
                        Icon(
                            Icons.Filled.Image,
                            contentDescription = "Localized description",
                        )
                    }
                },
                floatingActionButton = {
                    FloatingActionButton(
                        onClick = { /* do something */ },
                        containerColor = BottomAppBarDefaults.bottomAppBarFabColor,
                        elevation = FloatingActionButtonDefaults.bottomAppBarFabElevation()
                    ) {
                        Icon(Icons.Filled.Add, "Localized description")
                    }
                }
            )
        },
    ) { innerPadding ->
        Text(
            modifier = Modifier.padding(innerPadding),
            text = "Example of a scaffold with a bottom app bar."
        )
    }
}
AppBar.kt

實作方式如下：

圖 6. 底部應用程式列的導入範例。

注意： 您也可以使用 BottomAppBar，而不傳遞 actions 和 floatingActionButton 的值。在這種情況下，您可以建立自訂底部應用程式列，方法是像其他容器一樣，在 BottomAppBar 中填入內容。

其他資源

• Material 3 文件 - 頂端應用程式列
• Material 3 文件 - 底部應用程式列
• Scaffold