showDialog

showDialog() 是以程序方式打开模态对话框的入口。它通过应用的 OverlayHost 渲染 Dialog，等待其关闭后返回对话框结果。

前置条件

调用 useOverlays() 或 createOverlayService(host) 返回的函数前，请创建控制器并渲染 <OverlayHost :host="overlays" />。仅程序化浮层需要 host；声明式 Dialog 实例不需要。Vue 和 Nuxt 配置请参阅 OverlayHost。

基本用法

import { useOverlays } from '@chillet/m3-vue';

const { showDialog } = useOverlays(); // 在 setup 期间捕获。
const result = await showDialog({
  headline: '删除文件？',
  content: '此操作无法撤销。',
  actions: [
    { label: '取消', value: 'cancel' },
    { label: '删除', value: 'confirm' },
  ],
});

Promise 会返回被点击操作的值。如果未提供显式的 value，则使用操作标签。所有操作都渲染为文本按钮，包括主要操作和破坏性操作。它们的层级由文案、排列顺序和位置体现，而不是通过填充、色调或描边变体强调。

选项

以下表格由源代码类型生成，并与 API 变更保持同步。

ShowDialogOptions

字段	类型	必填	说明	默认值
headline	string	否	Optional dialog headline text.	-
content	string	否	Optional supporting text content.	-
icon	string	否	Optional Material Symbols icon name rendered above the headline.	-
actions	DialogAction[]	否	Action buttons rendered in the dialog footer.	-
closeOnBackdrop	boolean | undefined	否	Whether clicking the backdrop closes the dialog.	true
role	'dialog' | 'alertdialog'	否	ARIA role forwarded to the root dialog element.	-

DialogAction

字段	类型	必填	说明	默认值
label	string	是	Label shown in the action row.	-
value	string | undefined	否	Value returned when this action closes the dialog.	-
disabled	boolean | undefined	否	Whether the action button is disabled.	-
autofocus	boolean | undefined	否	Whether this action should autofocus when rendered.	-
closeOnClick	boolean | undefined	否	Whether clicking the action should close the dialog.	-
onClick	(() => void | boolean | Promise<void | boolean>) | undefined	否	Optional callback invoked before the dialog closes. Return `false` to keep it open.	-

行为说明

• 在浏览器环境之外调用 showDialog() 会使 Promise 被拒绝。
• 未挂载 OverlayHost 时调用 showDialog() 会使 Promise 被拒绝。
• 卸载或处置目标 host 会拒绝尚未完成的调用。
• 对话框会从宿主继承应用级 provide 和 CSS 自定义属性。
• 如果操作回调抛出错误或返回被拒绝的 Promise，外层 Promise 会以该错误被拒绝。
• 原生对话框关闭时 Promise 即返回结果。清理工作仍会等待 Dialog 自身的所有退出动画（包括背景层）结束后才从宿主移除，因此不会延迟既有的结果返回时机。

手动渲染对话框并通过插槽组合内容时，请参阅 Dialog。