OverlayDialog

OverlayDialog 是 COUI 中的对话框组件，用于显示重要信息、收集用户输入或确认用户操作。对话框会在当前界面上层显示，并支持自定义样式和内容布局。

使用前提

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

引入

import io.github.suqi8.coui.kmp.overlay.OverlayDialog

基本用法

OverlayDialog 组件提供了基础的对话框功能：

var showDialog by remember { mutableStateOf(false) }

Scaffold {
    TextButton(
        text = "显示对话框",
        onClick = { showDialog = true }
    )

    OverlayDialog(
        title = "对话框标题",
        summary = "这是一个基本的对话框示例，可以包含各种内容。",
        show = showDialog,
        onDismissRequest = { showDialog = false } // Close dialog
    ) {
        TextButton(
            text = "确定",
            onClick = { showDialog = false }, // Close dialog
            modifier = Modifier.fillMaxWidth()
        )
    }
}

属性

OverlayDialog 属性

属性名	类型	说明	默认值	是否必须
show	Boolean	是否显示对话框	-	是
modifier	Modifier	应用于对话框的修饰符	Modifier	否
title	String?	对话框的标题	null	否
titleColor	Color	标题文本的颜色	DialogDefaults.titleColor()	否
summary	String?	对话框的摘要说明	null	否
summaryColor	Color	摘要文本的颜色	DialogDefaults.summaryColor()	否
backgroundColor	Color	对话框背景色	DialogDefaults.backgroundColor()	否
enableWindowDim	Boolean	是否启用遮罩层	true	否
onDismissRequest	(() -> Unit)?	当用户请求关闭（点击遮罩层或返回手势）时触发	null	否
onDismissFinished	(() -> Unit)?	关闭动画完成后调用；若关闭过程被中途取消（例如 show 被设回 true），则不会触发	null	否
outsideMargin	DpSize	对话框外部边距	DialogDefaults.outsideMargin	否
insideMargin	DpSize	内置标题/摘要文本的边距（宽 = 水平内边距，高 = 标题上方内边距）；content 插槽不加内边距	DialogDefaults.insideMargin	否
defaultWindowInsetsPadding	Boolean	是否应用默认窗口插入内边距	true	否
renderInRootScaffold	Boolean	是否在根（最外层）Scaffold 中渲染对话框。为 true 时，对话框覆盖全屏。为 false 时，在当前 Scaffold 的范围内渲染	true	否
maxWidth	Dp	对话框的最大宽度	DialogDefaults.MaxWidth	否
largeScreen	Boolean?	大屏呈现方式的覆盖项（居中缩放/淡入淡出，而非底部滑入）；为 null 时根据窗口尺寸自动判断	null	否
cornerRadius	Dp?	圆角半径覆盖项；为 null 时使用 DialogDefaults.CornerRadius	null	否
content	@Composable () -> Unit	对话框的内容	-	是

DialogDefaults

属性

属性名	类型	说明
CornerRadius	Dp	对话框面板圆角（19.dp）
MaxWidth	Dp	对话框内容最大宽度（392.dp）
outsideMargin	DpSize	对话框外部默认边距（16, 24）
insideMargin	DpSize	内置标题/摘要文本的默认边距（24, 24）；content 插槽不加内边距
ButtonBarMinHeight	Dp	横向对话框按钮栏的最小高度（58.dp）
ButtonBarInsideMargin	PaddingValues	横向按钮栏中按钮的内边距（水平 24dp、上 12dp、下 22dp）；面板底部留白由按钮自身承担
ButtonBarDividerThickness	Dp	横向按钮栏分割线的粗细（1.dp）
ButtonBarDividerInsetTop	Dp	横向按钮栏分割线的上内缩（17.dp）
ButtonBarDividerInsetBottom	Dp	横向按钮栏分割线的下内缩（21.dp）

函数

函数名	返回类型	说明
titleColor()	Color	获取默认标题颜色
summaryColor()	Color	获取默认摘要颜色
backgroundColor()	Color	获取默认对话框背景颜色

进阶用法

居中呈现（大屏）

当窗口宽度不小于 840dp 且高度不小于 480dp 时，对话框会自动居中，并使用缩放/淡入淡出过渡代替底部滑入。可使用 largeScreen 强制指定呈现方式，cornerRadius 覆盖面板圆角：

var showDialog by remember { mutableStateOf(false) }

Scaffold {
    TextButton(
        text = "显示居中对话框",
        onClick = { showDialog = true }
    )

    OverlayDialog(
        title = "居中对话框",
        summary = "该对话框始终居中显示，与窗口尺寸无关",
        show = showDialog,
        largeScreen = true, // Force the centered presentation
        cornerRadius = 24.dp, // Override the panel corner radius
        maxWidth = 320.dp,
        onDismissRequest = { showDialog = false }
    ) {
        TextButton(
            text = "确认",
            onClick = { showDialog = false },
            modifier = Modifier.fillMaxWidth()
        )
    }
}

自定义样式对话框

var showDialog by remember { mutableStateOf(false) }

Scaffold {
    TextButton(
        text = "显示自定义样式对话框",
        onClick = { showDialog = true }
    )

    OverlayDialog(
        title = "自定义样式",
        summary = "这个对话框使用了自定义颜色和边距",
        show = showDialog,
        onDismissRequest = { showDialog = false }, // Close dialog
        titleColor = Color.Blue,
        summaryColor = Color.Gray,
        backgroundColor = Color(0xFFF5F5F5),
        outsideMargin = DpSize(20.dp, 20.dp),
        insideMargin = DpSize(30.dp, 30.dp)
    ) {
        Text(
            text = "自定义内容区域",
            modifier = Modifier.padding(vertical = 16.dp)
        )
        
        TextButton(
            text = "关闭",
            onClick = { showDialog = false }, // Close dialog
            modifier = Modifier.fillMaxWidth()
        )
    }
}

创建确认对话框

var showConfirmDialog by remember { mutableStateOf(false) }
var result by remember { mutableStateOf("") }

Scaffold {
    Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
        TextButton(
            text = "显示确认对话框",
            onClick = { showConfirmDialog = true }
        )
        
        Text("结果: $result")
    }
    
    OverlayDialog(
        title = "确认操作",
        summary = "此操作不可撤销，是否继续？",
        show = showConfirmDialog,
        onDismissRequest = { showConfirmDialog = false } // Close dialog
    ) {
        Row(
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            TextButton(
                text = "取消",
                onClick = { 
                    result = "用户取消了操作"
                    showConfirmDialog = false // Close dialog
                },
                modifier = Modifier.weight(1f)
            )
            Spacer(Modifier.width(20.dp))
            TextButton(
                text = "确认",
                onClick = { 
                    result = "用户确认了操作"
                    showConfirmDialog = false // Close dialog
                },
                modifier = Modifier.weight(1f),
                colors = ButtonDefaults.textButtonColorsPrimary() // Use theme color
            )
        }
    }
}

带有输入框的对话框

var showDialog by remember { mutableStateOf(false) }
var textFieldValue by remember { mutableStateOf("") }

Scaffold {
    TextButton(
        text = "显示输入对话框",
        onClick = { showDialog = true }
    )

    OverlayDialog(
        title = "请输入内容",
        show = showDialog,
        onDismissRequest = { showDialog = false } // Close dialog
    ) {
        TextField(
            modifier = Modifier.padding(bottom = 16.dp),
            value = textFieldValue,
            maxLines = 1,
            onValueChange = { textFieldValue = it }
        )
        
        Row(
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            TextButton(
                text = "取消",
                onClick = { showDialog = false }, // Close dialog
                modifier = Modifier.weight(1f)
            )
            Spacer(Modifier.width(20.dp))
            TextButton(
                text = "确认",
                onClick = { showDialog = false }, // Close dialog
                modifier = Modifier.weight(1f),
                colors = ButtonDefaults.textButtonColorsPrimary() // Use theme color
            )
        }
    }
}

带有表单的对话框

var showDialog by remember { mutableStateOf(false) }
var dropdownSelectedOption by remember { mutableStateOf(0) }
var switchState by remember { mutableStateOf(false) }
val dropdownOptions = listOf("选项 1", "选项 2")

Scaffold {
    TextButton(
        text = "显示表单对话框",
        onClick = { showDialog = true }
    )

    OverlayDialog(
        title = "表单对话框",
        show = showDialog,
        onDismissRequest = { showDialog = false } // Close dialog
    ) {
        Card(
            colors = CardDefaults.defaultColors(
                color = COUITheme.colorScheme.secondaryContainer,
            ),
        ) {
            OverlayDropdownPreference(
                title = "下拉选择",
                items = dropdownOptions,
                selectedIndex = dropdownSelectedOption,
                onSelectedIndexChange = { dropdownSelectedOption = it }
            )
            
            SwitchPreference(
                title = "开关选项",
                checked = switchState,
                onCheckedChange = { switchState = it }
            )
        }
        
        Spacer(Modifier.height(12.dp))
        
        Row(
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            TextButton(
                text = "取消",
                onClick = { showDialog = false }, // Close dialog
                modifier = Modifier.weight(1f)
            )
            Spacer(Modifier.width(20.dp))
            TextButton(
                text = "确认",
                onClick = { showDialog = false }, // Close dialog
                modifier = Modifier.weight(1f),
                colors = ButtonDefaults.textButtonColorsPrimary() // Use theme color
            )
        }
    }
}

带有颜色选择器的对话框

var showColorDialog by remember { mutableStateOf(false) }
var selectedColor by remember { mutableStateOf(Color.Red) }

Scaffold {
    TextButton(
        text = "选择颜色",
        onClick = { showColorDialog = true }
    )
    
    OverlayDialog(
        title = "选择颜色",
        show = showColorDialog,
        onDismissRequest = { showColorDialog = false } // Close dialog
    ) {
        Column {
            ColorPicker(
                initialColor = selectedColor,
                onColorChanged = { selectedColor = it }
            )
            Spacer(modifier = Modifier.height(16.dp))
            Row(
                modifier = Modifier.fillMaxWidth(),
                horizontalArrangement = Arrangement.spacedBy(8.dp),
            ) {
                TextButton(
                    modifier = Modifier.weight(1f),
                    text = "取消",
                    onClick = { showColorDialog = false } // Close dialog
                )
                TextButton(
                    modifier = Modifier.weight(1f),
                    text = "确认",
                    colors = ButtonDefaults.textButtonColorsPrimary(), // Use theme color
                    onClick = {
                        showColorDialog = false // Close dialog
                        // Handle confirm logic
                    }
                )
            }
        }
    }
}

变更日志

最后编辑于 1 天前

查看完整变更日志

b31da82-library: match the dialog button bar to its real COUI metrics

429b622-docs: rebrand site to COUI and audit all component pages

9aba0de-chore: rename package from com.suqi8 to io.github.suqi8

7acb5ab-library: retheme to COUI 16 and rename Miuix to COUI

4edc0d1-library: cap the derived dialog corner radius at 48dp

25d5ef7-library: add dialog cornerRadius override and fixed centered default

3257140-library: add largeScreen override for OverlayDialog and WindowDialog

fd5743c-dialog: add maxWidth support for OverlayDialog and WindowDialog (#370)

7c5c9a4-docs: clarify onDismissFinished cancel semantics + ListPopup defaults

a6234e9-library: refactor: unify dropdown and spinner components (#315)

baf2ab8-library!: restructure modules into miuix-ui and miuix-preference (#282)

4cb32d9-library: refactor overlay components and optimize Scaffold popup management (#251)

e623fef-library: Remove onClick from some composite components

10319d3-docs: Add missing onDismissFinished

62b1ec4-library: Add WindowBottomSheet component (#173)

f46d539-docs: Emphasize the use of MiuixPopupHost param

25d20ba-docs: Preview for components in documentation website (#80)

08848d5-library: Support custom dialog/popup layout anim (#71)

8c3380d-library: Refactor dialog/popup layout

cc1634b-docs: Add English version through AI translation

7bd2bac-chore: Add documents (#63)