Dialog

Dialog 显示需要关注或提供额外信息的自定义内容。

Storybook WAI-ARIA Source Recipe Source

Usage

Hide Backdrop

设置 Dialog 的 hideBackdrop 属性为 true 可以隐藏 Dialog 的背景遮罩。

Prevent Scroll

设置 Dialog 的 preventScroll 属性为 true 可以限制 Dialog 打开时页面滚动。

Keep Mounted

设置 Dialog 的 keepMounted 属性为 true 可以保持 Dialog 内容在关闭时仍然挂载。

Sizes

DialogContent 的 size 属性可以设置 Dialog 的大小，默认为 md。

FullScreen

设置 DialogContent 的 fullScreen 属性为 true 可以使 Dialog 全屏显示。

Placements

DialogContent 的 placement 属性可以设置 Dialog 的显示位置，默认为 top。

Custom Motion

DialogContent 的 motionProps 属性可以自定义 visible / hidden 的动画效果。

Overflow Scroll

DialogContent 的 scroll 属性可以控制 Dialog 内容的滚动行为。

inside: 内容在 Dialog 内部滚动。
outside: 内容在 Dialog 外部滚动。

Asynchronously Close

DialogClose 支持异步关闭 Dialog ，其 children 的 onClick 事件可返回一个 Promise , Dialog 会在 Promise 被 resolve 后关闭。

Controlled

使用 Dialog 的 open 和 onOpenChange 属性来控制 Dialog 的打开状态。

Dialog is closed

API

Dialog Props

Dialog 继承 as (默认为 m.div) 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	通常是 DialogContent、DialogTrigger 等组件。
open	boolean	-	控制 Dialog 的打开状态。(受控)
defaultOpen	boolean	-	Dialog 的默认打开状态。(非受控)
onOpenChange	(open: boolean) => void	-	当 Dialog 打开/关闭时触发回调函数。
className	string	-	Dialog 根元素的类名。
hideBackdrop	boolean	false	是否隐藏 Dialog 的背景遮罩。
container	HTMLElement\|null\|() => HTMLElement \| null	document.body	放置 Portal 的容器元素。
keepMounted	boolean	false	是否保持 Dialog 内容在关闭时仍然挂载。
preventScroll	boolean	false	是否限制 Dialog 打开时页面滚动。
closeOnInteractBackdrop	boolean	true	是否在与背景遮罩交互时关闭 Dialog 。
closeOnEscape	boolean	true	是否在按下 Escape 键时关闭 Dialog 。
restoreFocus	boolean	true	是否在 Dialog 关闭时恢复焦点到之前聚焦的元素。
onClose	() => void	-	Dialog 关闭时执行的回调函数。
as	ElementType	m.div	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。
classes	Partial<Record<Slots, ClassValue>>	-	Dialog Slots 的 className。
slotProps	Partial<Record<Slots, ComponentProps>>	-	Dialog Slots 的 props。

Dialog Slots

Slot Name	Class Name	Default Component	Description
backdrop	.nui-dialog-backdrop	'div'	Dialog 的背景遮罩元素。

DialogContent Props

DialogContent 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	通常是 DialogHeader、DialogBody、DialogFooter 等组件。
closeIcon	ReactNode	-	自定义 Dialog 的关闭图标。
size	'xs'\|'sm'\|'md'\|'lg'\|'xl'\|'full'	'md'	Dialog 的尺寸。
fullScreen	boolean	false	是否使 Dialog 全屏显示。
hideCloseButton	boolean	false	是否隐藏 Dialog 的关闭按钮。
scroll	'inside'\|'outside'	'outside'	Dialog 内容的滚动行为。
placement	'top'\|'bottom'\|'left'\|'right'	'top'	Dialog 的显示位置。
motionProps	HTMLMotionProps\|(placement) => HTMLMotionProps	-	自定义 Dialog 的动画效果。
aria-labelledby	string	-	Dialog 标题的 ARIA 标签。
aria-describedby	string	-	Dialog 描述的 ARIA 标签。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。
classes	Partial<Record<Slots, ClassValue>>	-	DialogContent Slots 的 className。
slotProps	Partial<Record<Slots, ComponentProps>>	-	DialogContent Slots 的 props。

DialogContent Slots

Slot Name	Class Name	Default Component	Description
closeButton	.nui-dialog-content-close-button	'button'	Dialog 的关闭按钮元素。
paper	.nui-dialog-content-paper	m.section	Dialog 的内容部分。

DialogHeader Props

DialogHeader 继承 as (默认为 'h2') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	Dialog 的标题内容。
as	ElementType	'h2'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。

DialogBody Props

DialogBody 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	Dialog 的内容。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。

DialogFooter Props

DialogFooter 继承 as (默认为 'div') 的 Props。

Prop	Type	Default	Description
children	ReactNode	-	Dialog 的底部内容。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。

DialogTrigger Props

Prop	Type	Default	Description
children	ReactNode	-	触发 Dialog 打开的元素，需支持 `onClick` 事件。

DialogClose Props

Prop	Type	Default	Description
children	ReactNode	-	触发 Dialog 关闭的元素，需支持 `onClick` 事件。