Dialog

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

Anatomy

NexUI 导出了 7 个 Dialog 相关组件:

Dialog: 用于显示 Dialog 的根组件。
DialogContent: 用于显示 Dialog 内容的组件。
DialogHeader: 用于显示 Dialog 标题的组件。
DialogBody: 用于显示 Dialog 主体内容的组件。
DialogFooter: 用于显示 Dialog 底部内容的组件。
DialogTrigger: 用于触发 Dialog 打开的组件。
DialogClose: 用于触发 Dialog 关闭的组件。


import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogBody,
  DialogFooter,
  DialogTrigger,
  DialogClose,
} from '@nex-ui/react'

Usage

Hide Backdrop

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

Prevent Scroll

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

Keep Mounted

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

Sizes

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

Placements

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

Custom Motion

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

Overflow Scroll

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

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

Asynchronous Closing

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

Prevent Close

DialogClose 可在 children 的 onClick 中调用 event.preventDefault() 阻止 Dialog 关闭。

Controlled

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

Dialog is closed

API

Dialog Props

Prop	Type	Default	Description
children	ReactNode	-	通常是 DialogContent、DialogTrigger 等组件。
open	boolean	-	控制 Dialog 的打开状态。(受控)
defaultOpen	boolean	-	Dialog 的默认打开状态。(非受控)
onOpenChange	(open: boolean) => void	-	当 Dialog 打开/关闭时触发回调函数。
onClose	() => void	-	Dialog 关闭时执行的回调函数。

DialogContent Props

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

Prop	Type	Default	Description
children	ReactNode	-	通常是 DialogHeader、DialogBody、DialogFooter 等组件。
className	ClassValue	-	用于根元素的 className。
as	ElementType	'div'	用于根元素的组件。可以是表示 HTML 元素的字符串，也可以是一个组件。
sx	Interpolation	-	用于根元素的 sx 属性。
classNames	Partial<Record<Slots, ClassValue>>	-	DialogContent Slots 的 className。
slotProps	Partial<Record<Slots, ComponentProps>>	-	DialogContent Slots 的 props。
ref	Ref	-	用于转发到根元素的 ref。
closeIcon	ReactNode	-	自定义 Dialog 的关闭图标。
size	'xs'\|'sm'\|'md'\|'lg'\|'xl'\|'full'	'md'	Dialog 的尺寸。
hideCloseButton	boolean	false	是否隐藏 Dialog 的关闭按钮。
scroll	'inside'\|'outside'	'outside'	Dialog 内容的滚动行为。
placement	'top'\|'bottom'\|'left'\|'right'	'top'	Dialog 的显示位置。
radius	'sm'\|'md'\|'lg'\|'none'	'md'	Dialog 的边框圆角。
motionProps	HTMLMotionProps\|(placement) => HTMLMotionProps	-	自定义 Dialog 的动画效果。
aria-labelledby	string	-	Dialog 标题的 ARIA 标签。
aria-describedby	string	-	Dialog 描述的 ARIA 标签。
hideBackdrop	boolean	false	是否隐藏 Dialog 的背景遮罩。
container	HTMLElement\|null\|() => HTMLElement \| null	document.body	放置 Portal 的容器元素。
keepMounted	boolean	false	是否保持 Dialog 内容在关闭时仍然挂载。
preventScroll	boolean	false	是否限制 Dialog 打开时页面滚动。
closeOnInteractOutside	boolean	true	是否在点击 Dialog 外部时关闭 Dialog。
closeOnEscape	boolean	true	是否在按下 Escape 键时关闭 Dialog。
restoreFocus	boolean	true	是否在 Dialog 关闭时恢复焦点到之前聚焦的元素。
disableAnimation	boolean	false	是否禁用 Dialog 的动画效果。

DialogContent Slots

Slot Name	Class Name	Default Component	Description
closeButton	.nui-dialog-content-close-button	'button'	Dialog 的关闭按钮元素。
paper	.nui-dialog-content-paper	'div'	Dialog 的内容部分。
backdrop	.nui-dialog-content-backdrop	'div'	Dialog 的背景遮罩元素。

DialogHeader Props

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

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

DialogBody Props

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

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

DialogFooter Props

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

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

DialogTrigger Props

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

DialogClose Props

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