OverlayDropdownPreference

OverlayDropdownPreference 是 Miuix 中的下拉菜单组件，提供了标题、摘要和下拉选项列表，支持点击交互，常用于选项设置和列表选择中。

使用前提

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

引入

kotlin

import top.yukonga.miuix.kmp.preference.OverlayDropdownPreference
import top.yukonga.miuix.kmp.basic.DropdownEntry
import top.yukonga.miuix.kmp.basic.DropdownItem

基本用法

OverlayDropdownPreference 组件提供了基础的下拉菜单功能：

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val options = listOf("选项 1", "选项 2", "选项 3")

Scaffold {
    OverlayDropdownPreference(
        title = "下拉菜单",
        items = options,
        selectedIndex = selectedIndex,
        onSelectedIndexChange = { selectedIndex = it }
    )
}

带摘要的下拉菜单

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val options = listOf("中文", "English", "日本語")

Scaffold {
    OverlayDropdownPreference(
        title = "语言设置",
        summary = "选择您的首选语言",
        items = options,
        selectedIndex = selectedIndex,
        onSelectedIndexChange = { selectedIndex = it }
    )
}

监听展开状态

kotlin

var selectedIndex by remember { mutableStateOf(0) }
var expanded by remember { mutableStateOf(false) }
val options = listOf("选项 1", "选项 2", "选项 3")

Scaffold {
    OverlayDropdownPreference(
        title = "下拉菜单",
        summary = if (expanded) "展开" else "收起",
        items = options,
        selectedIndex = selectedIndex,
        onExpandedChange = { expanded = it },
        onSelectedIndexChange = { selectedIndex = it }
    )
}

自定义条目

当单个下拉项需要额外状态时，例如选中状态、点击回调或禁用某个选项，可以使用 DropdownEntry 和 DropdownItem。

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val entry = DropdownEntry(
    items = listOf(
        DropdownItem(text = "选项 1", selected = selectedIndex == 0, onClick = { selectedIndex = 0 }),
        DropdownItem(text = "选项 2", enabled = false),
        DropdownItem(text = "选项 3", selected = selectedIndex == 2, onClick = { selectedIndex = 2 }),
    )
)

Scaffold {
    OverlayDropdownPreference(
        title = "下拉菜单",
        entry = entry
    )
}

禁用的下拉项不可点击，文本和选中指示图标会使用禁用颜色。

分组下拉菜单

使用 entries 可以显示多个由分割线隔开的下拉分组。每个条目都可以维护自己的选中状态和点击回调。

kotlin

var firstSelectedIndex by remember { mutableStateOf(0) }
var secondSelectedIndex by remember { mutableStateOf(0) }
val entries = listOf(
    DropdownEntry(
        items = listOf("小", "中").mapIndexed { index, text ->
            DropdownItem(text = text, selected = firstSelectedIndex == index, onClick = { firstSelectedIndex = index })
        }
    ),
    DropdownEntry(
        items = listOf("红色", "绿色", "蓝色").mapIndexed { index, text ->
            DropdownItem(text = text, selected = secondSelectedIndex == index, onClick = { secondSelectedIndex = index })
        }
    )
)

Scaffold {
    OverlayDropdownPreference(
        title = "分组下拉菜单",
        entries = entries,
        collapseOnSelection = false
    )
}

对于 entries 重载，collapseOnSelection 控制选中条目后是否关闭弹窗。它默认是 entries.size <= 1，单个分组会在选中后关闭，多个分组会保持打开以便连续修改。

多选

因为选中状态放在 DropdownItem 上，可以用集合保存多个选中值，并在每个条目的 onClick 中切换选中状态。

kotlin

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

Scaffold {
    OverlayDropdownPreference(
        title = "多选下拉菜单",
        entries = entries,
        collapseOnSelection = false
    )
}

组件状态

禁用状态

kotlin

OverlayDropdownPreference(
    title = "禁用下拉菜单",
    summary = "此下拉菜单当前不可用",
    items = listOf("选项 1"),
    selectedIndex = 0,
    onSelectedIndexChange = {},
    enabled = false
)

属性