Dialog

在模态对话框中呈现需要关注的内容或操作，提供遮罩、焦点管理与背景滚动锁定，适合确认和表单任务。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于需要独立焦点和关闭流程的对话框。锚定某个按钮的小浮层用 Popover，短提示用 Tooltip；标题与按钮使用公开组合角色。

用 bind:open 控制面板；默认支持外部点击和 Escape 关闭。
通过公开 title / content / footer / close 角色组合内容；显式子项自行配置，parts 只影响默认标题、分隔线与关闭按钮。

导入

import { Dialog } from '@snowui-design-system/components';

用法

尺寸

遮罩层

展开

API 参考

属性	类型	默认值	示例	描述
`id`	`string`	`—`	`id="example"`	模版模式唯一标识
`template`	`boolean`	`false`	`template`	只注册模版,不直接显示
`as`	`"dialog" \| undefined`	`—`	`as={value}`	内嵌模式标记
`open`	`boolean`	`false`	`open`	面板模式显隐,支持 `bind:open`
`onOpenChange`	`(open: boolean) => void`	`—`	`onOpenChange={(value) => { /* handle value */ }}`	面板模式状态变化回调
`backdrop`	`DialogBackdrop`	`"opaque"`	`backdrop={value}`	遮罩层变体；与 ImageViewer 复用共享 backdrop 视觉，关闭与动效仍由 Dialog 管理。
`size`	`DialogSize`	`"md"`	`size={value}`	面板尺寸
`closeOnOutside`	`boolean`	`true`	`closeOnOutside`	默认点击面板外的遮罩关闭；false 禁止。面板内部空白处不关闭。未保存表单或必须明确选择的场景建议显式设为 false
`closeOnEscape`	`boolean`	`true`	`closeOnEscape`	Escape 是否关闭
`pinOffset`	`number`	`—`	`pinOffset={42}`	内置与外置 Pin 共用的统一偏移，单位 px；未传时使用随根字号缩放的 Token 默认行为：sm/md 16px、lg 20px。
`pinOffsetX`	`number`	`—`	`pinOffsetX={42}`	覆盖内置与外置 Pin 的水平偏移，优先于 pinOffset
`pinOffsetY`	`number`	`—`	`pinOffsetY={42}`	覆盖内置与外置 Pin 的垂直偏移，优先于 pinOffset
`role`	`"dialog" \| string`	`"dialog"`	`role="Example"`	面板可访问角色
`title`	`string`	`—`	`title="Example"`	生成内置文字标题；外置 as="title" 存在时忽略此值
`separator`	`boolean`	`—`	`separator`	控制标题下方分割线；无标题时不生成默认行为：sm 为 false；md/lg 为 true。
`showCloseButton`	`boolean`	`true`	`showCloseButton`	是否显示内置右上角关闭按钮；不隐藏外置关闭角色
`closeLabel`	`string`	`locale 的关闭文案`	`closeLabel="Example"`	内置关闭按钮的可访问名称
`parts`	`ComponentPartsOf<{ Button: typeof Button; Text: typeof Text; Separator: typeof Separator }>`	`—`	`parts={partsOptions}`	只配置实际内置关闭 Button、标题 Text 与 Separator；不影响 children/footer 中显式组件；标题 id、children 与 ARIA 由 Dialog 拥有
`children`	`Snippet`	`—`	`<Dialog>Content</Dialog>`	对话框内容