一个 React 对话框，采用 Liquid Glass 表面与自定义操作区。
Dialog 是通用模态框。它内部渲染 Portal、遮罩、居中弹窗、标题、描述、可选正文以及自定义操作区。
与始终禁止遮罩关闭的 AlertDialog 不同，Dialog 允许点击遮罩或按 Esc 关闭，footer 也可以渲染任意数量和任意类型的操作按钮。
组件通常以受控方式使用：用 open 控制显示，触发按钮由页面自己渲染。footer 放置自己的按钮，点击后通过 setOpen(false) 关闭。
footer 是普通 React 节点，可以放入两个、三个或更多按钮，也可以混合其他控件。按钮不会自动关闭对话框，需要像示例一样自行更新 open。
No release published.
disablePointerDismissal 会阻止点击遮罩关闭对话框，Esc 键仍然可用；适合包含未保存内容的确认流程。
Dialog 渲染模态 dialog，由 title 命名，并由 description 描述。打开时焦点移动到浮层内，打开期间被限制在浮层中，关闭后返回触发器。
默认情况下，Escape 与点击背景都会关闭对话框。disablePointerDismissal 只会阻止点击背景关闭，Escape 仍然可用；请在 footer 中提供可见的关闭操作。modal={false} 会放宽焦点限制与滚动锁定。浮层焦点规则见可访问性指南。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | ReactNode | — | 对话框标题，必填。 |
description | ReactNode | — | 标题下方的说明文字。 |
children | ReactNode | — | 描述与操作区之间的正文内容。 |
footer | ReactNode | — | 底部操作区，可放置任意数量的控件。 |
open | boolean | — | 受控的打开状态。 |
defaultOpen | boolean | false | 非受控时的初始打开状态。 |
onOpenChange | (open: boolean, details) => void | — | 对话框打开或关闭时调用。 |
onOpenChangeComplete | (open: boolean) => void | — | 打开或关闭动画结束后调用。 |
modal | boolean | "trap-focus" | true | 控制焦点锁定与页面滚动锁定。 |
disablePointerDismissal | boolean | false | 禁止点击遮罩关闭。 |
actionsRef | RefObject<Actions | null> | — | 命令式的 close 与 unmount 操作。 |
handle | DialogHandle | — | 将对话框与外部触发器关联。 |
triggerId | string | null | — | 与对话框关联的触发器 ID。 |
defaultTriggerId | string | null | — | 初始打开时使用的触发器 ID。 |
className | string | — | 合并到弹窗的 Tailwind 类名。 |
style | CSSProperties | — | 内联样式，合并到与 className 相同的元素。 |
ui | { backdrop?: ClassValue; viewport?: ClassValue; popup?: ClassValue; glass?: ClassValue; overlay?: ClassValue; content?: ClassValue; title?: ClassValue; description?: ClassValue; body?: ClassValue; footer?: ClassValue } | — | 按 data-slot 组织的内部槽位类名。 |
| 属性 | 说明 |
|---|---|
data-open | 对话框打开时存在。 |
data-closed | 对话框关闭时存在。 |
data-starting-style | 对话框开始进入动画时存在。 |
data-ending-style | 对话框正在退出动画时存在。 |
data-nested | 对话框嵌套在另一个对话框内时存在。 |
data-nested-dialog-open | 对话框内部还有另一个对话框打开时存在。 |
data-slot | 标记内部部件（backdrop、viewport、popup、glass、overlay、content、title、description、body、footer），用于样式选择。 |
组件使用共享玻璃材质。可以在父级调整 --ui-glass-* token，用 className 控制布局，并通过 ui 按 data-slot 调整内部槽位。组件级数值位于 src/theme/dialog.ts。Token 分层与预设见主题指南。