OverlayCascadingListPopup

OverlayCascadingListPopup 是支持二级菜单的弹出列表组件。DropdownItem.children 非空的项会成为子菜单触发器：点击后弹窗会以触发行为锚点变形为二级列表，主列表则缩小并被半透明遮罩覆盖。级联深度限制为 2 级。

前置条件

此组件依赖于 Scaffold 提供的 COUIPopupHost 来渲染弹窗内容。必须在 Scaffold 内部使用，否则弹窗内容将无法正常渲染。

引入

kotlin

import io.github.suqi8.coui.kmp.overlay.OverlayCascadingListPopup
import io.github.suqi8.coui.kmp.basic.DropdownEntry
import io.github.suqi8.coui.kmp.basic.DropdownItem
import io.github.suqi8.coui.kmp.basic.PopupPositionProvider

基本用法

构造 entries，让某些 DropdownItem 携带非空的 children 列表。组件会在这些触发行的尾部渲染向右的 chevron；点击触发行后会就地展开二级菜单。

kotlin

var showPopup by remember { mutableStateOf(false) }
var sortIndex by remember { mutableStateOf(0) }
var viewIndex by remember { mutableStateOf(0) }

val sortLabels = listOf("Sort by capture date", "Sort by date added")
val viewLabels = listOf("Group by date", "Compact")
val entries = listOf(
    DropdownEntry(
        items = sortLabels.mapIndexed { idx, label ->
            DropdownItem(
                text = label,
                selected = sortIndex == idx,
                onClick = { sortIndex = idx },
            )
        },
    ),
    DropdownEntry(
        items = listOf(
            DropdownItem(
                text = "View mode",
                children = viewLabels.mapIndexed { idx, label ->
                    DropdownItem(
                        text = label,
                        selected = viewIndex == idx,
                        onClick = { viewIndex = idx },
                    )
                },
            ),
        ),
    ),
)

Scaffold {
    Box {
        TextButton(
            text = "Click to show menu",
            onClick = { showPopup = true },
        )
        OverlayCascadingListPopup(
            show = showPopup,
            entries = entries,
            onDismissRequest = { showPopup = false },
        )
    }
}

级联深度

级联深度上限为 2。二级菜单中的项不会再处理自己的 children；更深层的子树会被静默忽略。

组件状态

不同的对齐方式

kotlin

OverlayCascadingListPopup(
    show = showPopup,
    entries = entries,
    onDismissRequest = { showPopup = false },
    alignment = PopupPositionProvider.Align.Start,
)

禁用窗口变暗

kotlin

OverlayCascadingListPopup(
    show = showPopup,
    entries = entries,
    onDismissRequest = { showPopup = false },
    enableWindowDim = false,
)

选中后保持弹窗打开

默认情况下，用户点击任何一个叶子项后弹窗会自动关闭。设为 collapseOnSelection = false 即可保持弹窗打开（例如二级菜单内的多选）。

kotlin

OverlayCascadingListPopup(
    show = showPopup,
    entries = entries,
    onDismissRequest = { showPopup = false },
    collapseOnSelection = false,
)

选中项标记

selected = true 的叶子项尾部会显示以 DropdownColors.selectedIndicatorColor 着色的对勾图标；子菜单触发行则始终显示尾部 chevron。

kotlin

DropdownItem(
    text = "Sort by date added",
    selected = true, // Marks this leaf with a trailing check icon
    onClick = { /* ... */ },
)

返回导航与变形行为

返回处理与点击外部的规则一致：二级列表展开时，返回手势（或点击弹窗外部、点击克隆的子菜单标题行）会将二级列表收起回主列表；处于主列表层级时，返回与点击外部会通过 onDismissRequest 关闭弹窗。预测式返回手势会预览收起/关闭过程，取消手势时弹窗会自动恢复，无需额外配置。

属性