選單

使用者只要按一下圖示、文字欄位或其他元件，即可從臨時性平台上的選項清單中選取。本指南說明如何建立基本選單和包含分隔符和圖示的更複雜選單。

圖 1. 基本下拉式選單，其中列出兩個項目。

API 介面

使用 DropdownMenu、DropdownMenuItem 和 IconButton 元件來實作自訂下拉式選單。DropdownMenu 和 DropdownMenuItem 元件用於顯示選單項目，而 IconButton 則是用於顯示或隱藏下拉式選單的觸發事件。

DropdownMenu 元件的關鍵參數包括：

• expanded：指出選單是否可見。
• onDismissRequest：用於處理選單關閉作業。
• content：菜單的可組合內容，通常包含 DropdownMenuItem 可組合項。

DropdownMenuItem 的關鍵參數包括：

• text：定義選單項目中顯示的內容。
• onClick：用來處理與選單中項目互動的回呼。

建立基本下拉式選單

以下程式碼片段示範最少的 DropdownMenu 實作方式：

@Composable
fun MinimalDropdownMenu() {
    var expanded by remember { mutableStateOf(false) }
    Box(
        modifier = Modifier
            .padding(16.dp)
    ) {
        IconButton(onClick = { expanded = !expanded }) {
            Icon(Icons.Default.MoreVert, contentDescription = "More options")
        }
        DropdownMenu(
            expanded = expanded,
            onDismissRequest = { expanded = false }
        ) {
            DropdownMenuItem(
                text = { Text("Option 1") },
                onClick = { /* Do something... */ }
            )
            DropdownMenuItem(
                text = { Text("Option 2") },
                onClick = { /* Do something... */ }
            )
        }
    }
}
Menus.kt

程式碼的重點

• 定義包含兩個選單項目的基本 DropdownMenu。
• expanded 參數可控制選單的展開或收合狀態。
• onDismissRequest 參數會定義在使用者關閉選單時執行的回呼。
• DropdownMenuItem 可組合項代表下拉式選單中的可選項目。
• IconButton 會觸發選單的展開和收合動作。

結果

圖 2. 只有兩個選項的簡易下拉式選單。

建立較長的下拉式選單

如果無法一次顯示所有選單項目，DropdownMenu 預設會可捲動。以下程式碼片段會建立可捲動的下拉式選單：

@Composable
fun LongBasicDropdownMenu() {
    var expanded by remember { mutableStateOf(false) }
    // Placeholder list of 100 strings for demonstration
    val menuItemData = List(100) { "Option ${it + 1}" }

    Box(
        modifier = Modifier
            .padding(16.dp)
    ) {
        IconButton(onClick = { expanded = !expanded }) {
            Icon(Icons.Default.MoreVert, contentDescription = "More options")
        }
        DropdownMenu(
            expanded = expanded,
            onDismissRequest = { expanded = false }
        ) {
            menuItemData.forEach { option ->
                DropdownMenuItem(
                    text = { Text(option) },
                    onClick = { /* Do something... */ }
                )
            }
        }
    }
}
Menus.kt

程式碼的重點

• 如果內容的總高度超過可用空間，DropdownMenu 就會可捲動。此程式碼會建立可捲動的 DropdownMenu，用於顯示 100 個預留位置項目。
• forEach 迴圈會動態產生 DropdownMenuItem 可組合函式。項目並未以延遲方式建立，也就是說，所有 100 個下拉式選單項目都已建立，並存在於組合中。
• 點選 IconButton 時，系統會觸發 DropdownMenu 的展開和收合功能。
• 每個 DropdownMenuItem 中的 onClick lambda 可讓您定義使用者選取選單項目時要執行的動作。

結果

上述程式碼片段會產生以下可捲動的選單：

圖 3. 長且可捲動的下拉式選單。

建立較長的下拉式選單，並加入分隔線

下列程式碼片段顯示了下拉式選單的進階實作方式。在這段程式碼中，系統會在選單項目中加入前後圖示，並使用分隔符將不同群組的選單項目分開。

@Composable
fun DropdownMenuWithDetails() {
    var expanded by remember { mutableStateOf(false) }

    Box(
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp)
    ) {
        IconButton(onClick = { expanded = !expanded }) {
            Icon(Icons.Default.MoreVert, contentDescription = "More options")
        }
        DropdownMenu(
            expanded = expanded,
            onDismissRequest = { expanded = false }
        ) {
            // First section
            DropdownMenuItem(
                text = { Text("Profile") },
                leadingIcon = { Icon(Icons.Outlined.Person, contentDescription = null) },
                onClick = { /* Do something... */ }
            )
            DropdownMenuItem(
                text = { Text("Settings") },
                leadingIcon = { Icon(Icons.Outlined.Settings, contentDescription = null) },
                onClick = { /* Do something... */ }
            )

            HorizontalDivider()

            // Second section
            DropdownMenuItem(
                text = { Text("Send Feedback") },
                leadingIcon = { Icon(Icons.Outlined.Feedback, contentDescription = null) },
                trailingIcon = { Icon(Icons.AutoMirrored.Outlined.Send, contentDescription = null) },
                onClick = { /* Do something... */ }
            )

            HorizontalDivider()

            // Third section
            DropdownMenuItem(
                text = { Text("About") },
                leadingIcon = { Icon(Icons.Outlined.Info, contentDescription = null) },
                onClick = { /* Do something... */ }
            )
            DropdownMenuItem(
                text = { Text("Help") },
                leadingIcon = { Icon(Icons.AutoMirrored.Outlined.Help, contentDescription = null) },
                trailingIcon = { Icon(Icons.AutoMirrored.Outlined.OpenInNew, contentDescription = null) },
                onClick = { /* Do something... */ }
            )
        }
    }
}
Menus.kt

以下程式碼會在 Box 中定義 DropdownMenu。

程式碼的重點

• leadingIcon 和 trailingIcon 參數會在 DropdownMenuItem 的開頭和結尾新增圖示。
• IconButton 會觸發選單展開。
• DropdownMenu 包含多個 DropdownMenuItem 可編寫項，每個都代表可選取的動作。
• HorizontalDivider 可組合函式會插入水平線，用於分隔選單項目群組。

結果

上述程式碼片段會產生下拉式選單，其中包含圖示和分隔符：

圖 4. 下拉式選單分為多個區段，並帶有前置和後置圖示。

其他資源

• Material Design：選單