Miuix弹窗体系完全指南:Overlay与Window双方案实现对话框、BottomSheet与下拉菜单

原创2026-10-11 18:42:252,123 阅读

Miuix弹窗体系完全指南:Overlay与Window双方案实现对话框、BottomSheet与下拉菜单

Miuix 是一个面向 Compose Multiplatform 的开源 UI 组件库,它的弹窗体系提供 Overlay 与 Window 两套完整方案,帮你用同一套代码实现对话框(Dialog)、底部抽屉(BottomSheet)和下拉菜单(Dropdown Menu),并在 Android、iOS、桌面和 Web 等平台上获得一致的交互体验。本文带你快速看懂两套方案的区别与选型方法。

Miuix示例应用首页,展示对话框与BottomSheet入口

为什么需要 Overlay 与 Window 两种弹窗方案?

在 Jetpack Compose 中做跨平台弹窗,官方 Popup 和 Dialog 的跨端支持并不完整,部分行为参数无法自定义。Miuix 为此设计了独立的弹层容器,并给出两种使用方式:

方案 渲染层级 使用前提 典型场景
Overlay 系列 当前页面(Scaffold)内覆盖渲染 必须包裹在 Scaffold 中,由其提供 MiuixPopupHost 页面内的确认对话框、设置面板、菜单
Window 系列 窗口级,基于平台原生 Dialog 渲染 任何 Composable 作用域均可,无需 Scaffold 全局确认框、跨页面弹层、简单页面里的临时弹窗

一句话总结:有 Scaffold 的完整页面优先用 Overlay,轻量页面或不便使用 Scaffold 时用 Window,两者 API 高度一致,切换成本很低。

💡 每个 Scaffold 会自动管理自己独立的弹层状态,多个嵌套或并列的 Scaffold 无需额外配置即可正确工作。

Overlay 方案:Scaffold 内的对话框与 BottomSheet

OverlayDialog:确认操作与收集输入

OverlayDialog 用于显示重要信息、收集用户输入或确认用户操作,支持自定义颜色、边距和圆角。核心用法只需三步:用 show 控制显隐、onDismissRequest 处理点按外部/返回、content 里放按钮或表单:

OverlayDialog(
    title = "确认操作",
    summary = "此操作不可撤销,确定继续吗?",
    show = showDialog,
    onDismissRequest = { showDialog = false }
) {
    TextButton(text = "确认", onClick = { showDialog = false })
}

几个值得注意的参数:

  • renderInRootScaffold:默认 true,对话框渲染在最外层 Scaffold,覆盖全屏;设为 false 则限制在当前 Scaffold 范围内。
  • largeScreen:为 null 时自动检测窗口尺寸——大屏(平板、桌面)呈现居中缩放/淡入效果,手机则从底部滑入,天然适配多形态设备。
  • onDismissFinished:在隐藏动画真正完成后回调,适合做状态清理。

OverlayBottomSheet:从底部滑起的抽屉

OverlayBottomSheet 支持拖动手势关闭,并提供自适应内容高度,适合承载长列表、设置表单等操作集合:

  • startAction / endAction:在标题栏放"取消/确定"按钮;
  • allowDismiss = false:禁止拖拽和返回手势关闭,强制用户点按钮;
  • enableWindowDim = false:去掉背景暗化层;
  • sheetMaxWidth:限制宽度,在大屏上呈现居中卡片而非通栏。

源码可参考 OverlayDialog.kt 与 OverlayBottomSheet.kt。

Window 方案:无需 Scaffold 的窗口级弹层

WindowDialog 和 WindowBottomSheet 基于平台 Dialog 渲染在窗口层级,任何 Composable 作用域中都可以直接使用,不依赖 Scaffold 和 MiuixPopupHost。它们同样支持大屏优化动画与系统返回手势关闭。

Window 系列还有一个统一的小技巧——LocalDismissState:在弹层内容内部直接请求关闭,无需向外传递闭包:

WindowDialog(title = "提示", show = showDialog, onDismissRequest = { showDialog = false }) {
    val dismiss = LocalDismissState.current
    TextButton(text = "确定", onClick = { dismiss?.invoke() })
}

对应源码见 WindowDialog.kt、WindowBottomSheet.kt,LocalDismissState 定义在 DismissState.kt。

下拉菜单:从单级选择到两级级联

Miuix示例应用下拉菜单区域,展示Dropdown选项组件

下拉菜单由 miuix-preference 模块提供,同样分为 Overlay 与 Window 双版本,并区分两种定位:

  • DropdownPreference(如 OverlayDropdownPreference.kt):组件自带单选索引,适合设置页里的"单一选项"行;
  • DropdownMenu(如 OverlayDropdownMenu.kt):不持有选中态,选中状态完全由每个 DropdownItem 的 selected 和 onClick 决定,适合动作菜单和多选菜单;
  • 级联列表:OverlayCascadingListPopup.kt 支持两级级联,带 children 的条目点击后会以形变动画展开二级列表,最多支持 2 级。

菜单支持 List<DropdownEntry> 传入多组条目并用分隔线分组;多组菜单默认 collapseOnSelection = false,即每次选择后保持展开,方便连续修改多个选项。

Overlay vs Window 快速选型对照

对比项 Overlay 系列 Window 系列
需要 Scaffold / MiuixPopupHost ✅ 必须 ❌ 不需要
渲染层级 页面内覆盖 窗口级(原生 Dialog)
可限制在某个 Scaffold 范围内 ✅(renderInRootScaffold) ❌(始终窗口级)
使用位置 完整的页面结构 任意作用域,包括轻量组件
组件覆盖 Dialog / BottomSheet / ListPopup / 级联菜单 Dialog / BottomSheet / ListPopup / 下拉菜单

📌 实用建议:主框架页面(有 Scaffold)用 Overlay 可获得更好的层级隔离;如果只是想在一个工具类组件里快速加个确认框,Window 系列零依赖、拿来即用。

常见问题与进阶技巧

  • 弹层内容不显示? 检查 Overlay 系列组件是否真的写在 Scaffold 的 content 内——没有 MiuixPopupHost 时弹层不会渲染。
  • 键盘遮挡? 两个系列的 defaultWindowInsetsPadding 默认为 true,会自动处理键盘与导航栏内边距。
  • 暗色/动态取色:DialogDefaults、BottomSheetDefaults 提供的默认颜色均来自 MiuixTheme,配合 Monet 动态取色 自动适配。
  • 动画缓动:Miuix 内置 MiuixEasing.kt 等自定义曲线,弹层动画与 MIUI 风格保持一致。

延伸阅读

登录后查看全文
miuix