Miuix弹窗体系完全指南:Overlay与Window双方案实现对话框、BottomSheet与下拉菜单
Miuix弹窗体系完全指南:Overlay与Window双方案实现对话框、BottomSheet与下拉菜单
Miuix 是一个面向 Compose Multiplatform 的开源 UI 组件库,它的弹窗体系提供 Overlay 与 Window 两套完整方案,帮你用同一套代码实现对话框(Dialog)、底部抽屉(BottomSheet)和下拉菜单(Dropdown Menu),并在 Android、iOS、桌面和 Web 等平台上获得一致的交互体验。本文带你快速看懂两套方案的区别与选型方法。
为什么需要 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-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 风格保持一致。
延伸阅读
- 组件文档(含完整参数表与示例):
- 源码入口:
- 中文文档版本位于 docs/zh_CN/components/

