跳到主要内容跳到主要内容
🚀 影响 Material UI 2025 年路线图！参与最新的开发者调查

DialogAPI

React Dialog 组件的 API 参考文档。了解此导出模块的 props、CSS 和其他 API。

演示

导入

import Dialog from '@mui/material/Dialog';
// or
import { Dialog } from '@mui/material';

通过阅读本指南，了解关于最小化 bundle size 的差异。



对话框是带有背景幕的覆盖式模态纸质组件。

Props

Modal 组件的 Props 也可用。

名称类型默认值描述
open*bool-

如果 true，则组件显示。

aria-describedbystring-

描述对话框的元素 id。

aria-labelledbystring-

标记对话框的元素 id。

aria-modal'false'
| 'true'
| bool		true

告知辅助技术该元素是模态的。它被添加到具有 role="dialog" 的元素上。

BackdropComponentelementTypestyled(Backdrop, { name: 'MuiModal', slot: 'Backdrop', overridesResolver: (props, styles) => { return styles.backdrop; }, })({ zIndex: -1, })

背景幕组件。此 prop 启用自定义背景幕渲染。

childrennode-

Dialog children，通常是包含的子组件。

classesobject-

覆盖或扩展应用于组件的样式。

有关更多详细信息，请参见下方的 CSS 类 API。

disableEscapeKeyDownboolfalse

如果 true，则按 Escape 键不会触发 onClose 回调。

fullScreenboolfalse

如果 true，则对话框为全屏。

fullWidthboolfalse

如果 true，则对话框将拉伸到 maxWidth。
请注意，对话框宽度的增长受默认边距的限制。

maxWidth'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| false
| string		'sm'

确定对话框的最大宽度。对话框宽度随屏幕尺寸增长。设置为 false 以禁用 maxWidth。

onClosefunc-

当组件请求关闭时触发的回调。

签名：function(event: object, reason: string) => void
  • event 回调的事件源。
  • reason 可以是："escapeKeyDown"、"backdropClick"。
PaperComponentelementTypePaper

用于渲染对话框主体的组件。

PaperPropsobject{}

应用于 Paper 元素的 Props。

scroll'body'
| 'paper'		'paper'

确定对话框滚动的容器。

slotProps{ backdrop?: func
| object, container?: func
| object, paper?: func
| object, root?: func
| object, transition?: func
| object }		{}

用于内部每个 slot 的 props。

slots{ backdrop?: elementType, container?: elementType, paper?: elementType, root?: elementType, transition?: elementType }{}

用于内部每个 slot 的组件。

sxArray<func
| object
| bool>
| func
| object		-

允许定义系统 overrides 以及其他 CSS 样式的系统 prop。

有关更多详细信息，请参见 `sx` 页面。

TransitionComponentelementTypeFade

用于过渡效果的组件。 请遵循本指南，以了解有关此组件要求的更多信息。

transitionDurationnumber
| { appear?: number, enter?: number, exit?: number }		{ enter: theme.transitions.duration.enteringScreen, exit: theme.transitions.duration.leavingScreen, }

过渡效果的持续时间，以毫秒为单位。您可以为所有过渡效果指定单个超时，也可以使用对象单独指定。

TransitionPropsobject-

应用于过渡元素的 Props。默认情况下，该元素基于此 Transition 组件。

ref 被转发到根元素。

继承

虽然上面没有明确记录，但 Modal 组件的 props 也可在 Dialog 中使用。您可以利用这一点来 定位嵌套组件。

主题默认 props

您可以使用 MuiDialog 通过主题更改此组件的默认 props。

Slots

Slot 名称Class 名称默认组件描述
transitionCollapse渲染过渡效果的组件。 请遵循本指南，以了解有关此组件要求的更多信息。
paper.MuiDialog-paperPaper渲染纸张的组件。
container.MuiDialog-container渲染容器的组件。
backdrop渲染背景幕的组件。
root.MuiDialog-root渲染根元素的组件。

CSS 类

这些类名对于使用 CSS 设置样式很有用。当触发特定状态时，它们将应用于组件的 slot。

Class 名称规则名称描述
.MuiDialog-paperFullScreenpaperFullScreen如果 fullScreen={true}，则应用于 Paper 组件的样式。
.MuiDialog-paperFullWidthpaperFullWidth如果 fullWidth={true}，则应用于 Paper 组件的样式。
.MuiDialog-paperScrollBodypaperScrollBody如果 scroll="body"，则应用于 Paper 组件的样式。
.MuiDialog-paperScrollPaperpaperScrollPaper如果 scroll="paper"，则应用于 Paper 组件的样式。
.MuiDialog-paperWidthFalsepaperWidthFalse如果 maxWidth=false，则应用于 Paper 组件的样式。
.MuiDialog-paperWidthLgpaperWidthLg如果 maxWidth="lg"，则应用于 Paper 组件的样式。
.MuiDialog-paperWidthMdpaperWidthMd如果 maxWidth="md"，则应用于 Paper 组件的样式。
.MuiDialog-paperWidthSmpaperWidthSm如果 maxWidth="sm"，则应用于 Paper 组件的样式。
.MuiDialog-paperWidthXlpaperWidthXl如果 maxWidth="xl"，则应用于 Paper 组件的样式。
.MuiDialog-paperWidthXspaperWidthXs如果 maxWidth="xs"，则应用于 Paper 组件的样式。
.MuiDialog-scrollBodyscrollBody如果 scroll="body"，则应用于容器元素的样式。
.MuiDialog-scrollPaperscrollPaper如果 scroll="paper"，则应用于容器元素的样式。

您可以使用以下自定义选项之一来覆盖组件的样式

源代码

如果您在本页中没有找到所需的信息，请考虑查看组件的实现以获取更多详细信息。