组件 · 反馈
Dialog 对话框
模态对话框：DialogTrigger/Portal/Backdrop/Content 与标题描述页脚槽位。
使用建议
- 避免：嵌套无障碍焦点陷阱冲突
- 避免：杜撰 visible 代替 open
- 限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造
引入
import {
Dialog,
DialogBackdrop,
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
// …共 16 个导出
} from '@selrux/ui/dialog';演练场
调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。
代码演示
基础用法
模态对话框，打开后焦点移入、Esc 关闭、焦点返回触发器。
宽度与全屏
DialogContent 的 width 为 sm / md / lg；showFullscreenButton 显示全屏切换。
受控与全屏
open / onOpenChange 受控；fullscreen + onFullscreenChange 受控全屏，defaultFullscreen 为非受控初始值。
关闭策略
closeOnOutsidePress 允许点遮罩关闭；closeOnEscape={false} 禁用 Esc；showCloseButton={false} 去掉右上角关闭钮；beforeClose 返回 false 拦截（如有未保存内容）；disabled 禁止打开。
API
属性覆盖：示例用到 15 / 15 个自有属性（100%）
由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。
Dialog.styles：语义 slot 内联样式，与 className/style 同类的样式逃生口，不单独演示Dialog.initialFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”Dialog.returnFocusRef：焦点目标 ref，效果不可见；行为见“无障碍”DialogPortal.container：Portal 挂载目标，默认 body；文档页无需更换挂载点
Dialog
Dialog 根。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
showCloseButton | 是否渲染 Dialog 右上角默认关闭钮；默认 true。 | boolean | true |
showFullscreenButton | 是否渲染 Dialog 右上角全屏切换钮；默认 true。 | boolean | true |
classNames | 语义结构 class；部件自身 className 拼接其后。 | DialogClassNamesInput | - |
styles | 语义结构 style；部件自身 style 覆盖同名键。 | DialogStylesInput | - |
disabled | 为真时禁止打开并立即抑制可见层。 | boolean | - |
closeOnEscape | 顶层 Esc 是否进入关闭流程。默认 true。 | boolean | true |
closeOnOutsidePress | 遮罩主指针按下是否进入关闭流程；默认 false，防止意外丢草稿。 | boolean | false |
beforeClose | 关闭前拦截；false/Promise<false> 取消，void/true 允许，reject 取消。 | DialogBeforeClose | - |
fullscreen | 受控全屏；与 defaultFullscreen 互斥。 关闭 Dialog 时库会请求退出全屏（发 onFullscreenChange(false)）。 | boolean | - |
defaultFullscreen | 非受控默认全屏；挂载时读取一次。默认 false。 | boolean | false |
onFullscreenChange | 全屏变更请求；不强改父状态。 | ((fullscreen: boolean) => void) | - |
initialFocusRef | 打开时初始焦点目标（优先于首个可 Tab 控件）。 | RefObject<HTMLElement | null> | - |
returnFocusRef | 适用关闭路径的返回焦点目标。 | RefObject<HTMLElement | null> | - |
open | 受控打开；与 defaultOpen 互斥。 | boolean | - |
defaultOpen | 非受控默认打开；挂载时读取一次。 | boolean | - |
onOpenChange | 请求变更；不强改父状态。 | ((open: boolean, details: OverlayChangeDetails) => void) | - |
children | 复合子树：Trigger / Portal 等。 | ReactNode | - |
DialogBackdrop
DialogBackdrop。
无自有属性；其余 279 项原生属性继承自 HTMLAttributes。
DialogBody
DialogBody。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 区域子树。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
DialogClose
DialogClose。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
render | 与 children 互斥；传 render 时禁用。 | ReactElement<unknown, string | JSXElementConstructor<any>> | - |
children | 不传 render 时的按钮内容。 | ReactNode | - |
另有 288 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
DialogContent
DialogContent。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
style | 普通样式；受管定位/模态隔离/aria 不可被绕过失效。 | CSSProperties | - |
onEscapeKeyDown | Esc 按下时调用；preventDefault 取消关闭且跳过 beforeClose。 | ((event: KeyboardEvent) => void) | - |
width | 宽度档；省略取 md。全屏时由全屏几何覆盖。 | "sm" | "md" | "lg" | - |
onPointerDownOutside | 外部主指针按下时调用；preventDefault 取消关闭且跳过 beforeClose。 | ((event: Event) => void) | - |
children | 卡片子树（Header/Body/Footer 等）。 | ReactNode | - |
另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。
DialogDescription
DialogDescription。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 说明内容。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
DialogFooter
DialogFooter。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 区域子树。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
DialogHeader
DialogHeader。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 区域子树。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
DialogPortal
DialogPortal。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
container | 挂载目标；省略默认 body；显式 null 等待就绪。 | PortalContainerInput | body |
children | Portal 子树：Backdrop 与 Content。 | ReactNode | - |
DialogTitle
DialogTitle。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 标题内容。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
DialogTrigger
DialogTrigger。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
render | 与 children 互斥；传 render 时禁用。 | ReactElement<unknown, string | JSXElementConstructor<any>> | - |
children | 不传 render 时的按钮内容。 | ReactNode | - |
另有 284 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。
导出类型：DialogBackdropProps、DialogBeforeClose、DialogClassNamesInput、DialogCloseProps、DialogContentProps、DialogDescriptionProps、DialogPortalProps、DialogProps、DialogSectionProps、DialogSemanticSlot、DialogStylesInput、DialogTitleProps、DialogTriggerProps、DialogWidth、OverlayChangeDetails、OverlayChangeReason、PortalContainerInput、ResolvedDialogClassNames、ResolvedDialogSemanticStyles、ResolvedDialogStyles、ResolveDialogSemanticStylesInput
函数与常量
| 名称 | 说明 | 签名 / 类型 |
|---|---|---|
dialogWidths | 合法宽度集合。 | Set<DialogWidth> |
mergeDialogClassName | 合并语义 class 与部件自身 className。 | (slot: string | undefined, own: string | undefined) => string | undefined |
mergeDialogStyle | 合并语义 style 与部件自身 style；部件显式键覆盖语义键。 | (slot: CSSProperties | undefined, own: CSSProperties | undefined) => CSSProperties | undefined |
resolveDialogSemanticStyles | 解析语义样式映射；非法函数结果回退为空对象。 | (input: ResolveDialogSemanticStylesInput) => ResolvedDialogSemanticStyles |
resolveDialogWidth | 解析 Content 宽度档；非法/缺省回退 md。 | (width: DialogWidth | undefined) => DialogWidth |
无障碍
摘自源码 JSDoc。
Dialog.closeOnEscape：顶层 Esc 是否进入关闭流程。Dialog.initialFocusRef：打开时初始焦点目标（优先于首个可 Tab 控件）。Dialog.returnFocusRef：适用关闭路径的返回焦点目标。DialogContent.onEscapeKeyDown：Esc 按下时调用；preventDefault 取消关闭且跳过 beforeClose。