OverlayDropdownMenu

OverlayDropdownMenu 是基于 BasicComponent 的封装，点击后会展开 OverlayDropdownPopup。与 OverlayDropdownPreference 不同，它不再持有单一的选中索引——选中状态完全保存在每个 DropdownItem 的 selected 与 onClick 上。适用于动作菜单、多选菜单，或弹出项之间不构成单选互斥关系的场景。

使用前提

此组件依赖 Scaffold 提供的 COUIPopupHost 以显示弹出内容。必须在 Scaffold 中使用，否则弹出内容无法正常渲染。

引入

kotlin

import io.github.suqi8.coui.kmp.menu.OverlayDropdownMenu
import io.github.suqi8.coui.kmp.basic.DropdownEntry
import io.github.suqi8.coui.kmp.basic.DropdownItem

基本用法

传入单个 DropdownEntry 即可显示一个基础下拉菜单行：

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val entry = DropdownEntry(
    items = listOf("Option 1", "Option 2", "Option 3").mapIndexed { index, text ->
        DropdownItem(
            text = text,
            selected = selectedIndex == index,
            onClick = { selectedIndex = index },
        )
    }
)

Scaffold {
    OverlayDropdownMenu(
        title = "Dropdown Menu",
        entry = entry
    )
}

分组菜单

传入 List<DropdownEntry> 即可显示由分割线隔开的多个分组。collapseOnSelection 默认为 entries.size <= 1，多分组场景下选中后弹出框保持打开以便连续选择。

kotlin

var sizeIndex by remember { mutableStateOf(0) }
var colorIndex by remember { mutableStateOf(0) }
val entries = listOf(
    DropdownEntry(
        items = listOf("Small", "Medium").mapIndexed { index, text ->
            DropdownItem(text = text, selected = sizeIndex == index, onClick = { sizeIndex = index })
        }
    ),
    DropdownEntry(
        items = listOf("Red", "Green", "Blue").mapIndexed { index, text ->
            DropdownItem(text = text, selected = colorIndex == index, onClick = { colorIndex = index })
        }
    )
)

Scaffold {
    OverlayDropdownMenu(
        title = "Grouped Menu",
        entries = entries,
        collapseOnSelection = false
    )
}

多选

选中状态保存在 DropdownItem.selected 上，可以同时选中多个条目，在每个条目的 onClick 中切换选中状态即可。

kotlin

var selected by remember { mutableStateOf(setOf("A1", "B2")) }
val entries = listOf(
    DropdownEntry(
        items = listOf("A1", "A2").map { text ->
            DropdownItem(
                text = text,
                selected = text in selected,
                onClick = {
                    selected = if (text in selected) selected - text else selected + text
                }
            )
        }
    ),
    DropdownEntry(
        items = listOf("B1", "B2", "B3").map { text ->
            DropdownItem(
                text = text,
                selected = text in selected,
                onClick = {
                    selected = if (text in selected) selected - text else selected + text
                }
            )
        }
    )
)

Scaffold {
    OverlayDropdownMenu(
        title = "Multi Select Menu",
        entries = entries,
        collapseOnSelection = false
    )
}

带图标与摘要的选项

每个 DropdownItem 都可以在文本前显示图标，并在文本下方显示一行摘要。icon lambda 会收到一个预设尺寸的 Modifier，应将其应用到图标组件上。

kotlin

val entry = DropdownEntry(
    items = listOf(
        DropdownItem(
            text = "Rename",
            summary = "Change the display name",
            icon = { modifier ->
                Icon(
                    modifier = modifier,
                    imageVector = COUIIcons.Rename,
                    contentDescription = null,
                )
            },
            onClick = { /* handle action */ },
        ),
        DropdownItem(text = "Delete", onClick = { /* handle action */ }),
    )
)

Scaffold {
    OverlayDropdownMenu(
        title = "Item Icons",
        entry = entry
    )
}

监听展开状态

kotlin

var expanded by remember { mutableStateOf(false) }
val entry = DropdownEntry(
    items = listOf("Option 1", "Option 2", "Option 3").map { DropdownItem(text = it) }
)

Scaffold {
    OverlayDropdownMenu(
        title = "Observe Expanded",
        summary = if (expanded) "Expanded" else "Collapsed",
        entry = entry,
        onExpandedChange = { expanded = it }
    )
}

带提示槽的选项

hint 槽渲染在标题区块与选中指示图标之间，最大宽度 40dp，适合放红点、计数徽标或极短标签。与 ColorOS 一致，行被禁用时提示槽整体隐藏。

kotlin

val entry = DropdownEntry(
    items = listOf(
        DropdownItem(text = "Inbox", hint = { Badge(count = 12) }),
        DropdownItem(text = "Updates", hint = { Badge() }),
        // 该行被禁用，因此徽标不会显示。
        DropdownItem(text = "Archive", hint = { Badge(count = 3) }, enabled = false),
    )
)

Scaffold {
    OverlayDropdownMenu(title = "Hints", entry = entry)
}

分组标题

DropdownEntry 可声明 title，渲染为该分组各项之上的不可点击标题行（12sp 中等字重、次级标签色、最多 2 行）。分组标题与已有的分组分割线可以共存。

kotlin

val entries = listOf(
    DropdownEntry(
        title = "Sort by",
        items = listOf("Name", "Date modified").map { DropdownItem(text = it) }
    ),
    DropdownEntry(
        title = "Order",
        items = listOf("Ascending", "Descending").map { DropdownItem(text = it) }
    )
)

Scaffold {
    OverlayDropdownMenu(title = "Group Headers", entries = entries)
}

警示项

设置 alert = true 可将某项标记为危险操作，其标题使用错误色而非常规标签色；被禁用的警示项仍回退到禁用色。

kotlin

val entry = DropdownEntry(
    items = listOf(
        DropdownItem(text = "Rename"),
        DropdownItem(text = "Delete", alert = true),
    )
)

Scaffold {
    OverlayDropdownMenu(title = "Alert Item", entry = entry)
}

组件状态

禁用状态

kotlin

OverlayDropdownMenu(
    title = "Disabled Menu",
    summary = "This menu is currently unavailable",
    entry = DropdownEntry(items = listOf(DropdownItem(text = "Option 1"))),
    enabled = false
)

当所有 DropdownEntry 都不包含任何条目时，菜单也会被隐式禁用。

禁用部分选项

通过 DropdownItem.enabled 可以禁用单个选项，通过 DropdownEntry.enabled 可以禁用整个分组。禁用的行会置灰并忽略点击。

kotlin

val entries = listOf(
    DropdownEntry(
        items = listOf(
            DropdownItem(text = "Available option"),
            DropdownItem(text = "Unavailable option", enabled = false),
        )
    ),
    DropdownEntry(
        items = listOf(DropdownItem(text = "Whole group disabled")),
        enabled = false
    )
)

Scaffold {
    OverlayDropdownMenu(
        title = "Partially Disabled",
        entries = entries
    )
}

属性