跳到主要內容跳到主要內容
🚀 影響 Material UI 2025 年的藍圖！參與最新的開發者調查

DialogAPI

React Dialog 元件的 API 參考文件。了解此匯出模組的屬性、CSS 和其他 API。

示範

匯入

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

閱讀這份關於最小化套件大小的指南，以了解差異。



對話框是以模態紙張為基礎的覆蓋元件，並帶有背景幕。

屬性

Modal 元件的屬性也適用。

名稱類型預設描述
open*布林值-

如果為 true，則會顯示元件。

aria-describedby字串-

描述對話框的元素 ID。

aria-labelledby字串-

標記對話框的元素 ID。

aria-modal'false'
| 'true'
| 布林值		true

告知輔助技術此元素為模態。它會新增至具有 role="dialog" 的元素。

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

背景幕元件。此屬性啟用自訂背景幕渲染。

childrennode-

對話框子元件，通常是包含的子元件。

classesobject-

覆寫或擴充套用至元件的樣式。

請參閱下方的CSS 類別 API 以取得更多詳細資訊。

disableEscapeKeyDown布林值false

如果為 true，按下 Escape 鍵將不會觸發 onClose 回呼。

fullScreen布林值false

如果為 true，對話框會全螢幕顯示。

fullWidth布林值false

如果為 true，對話框會延展至 maxWidth。
請注意，對話框寬度的成長受到預設邊距的限制。

maxWidth'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'
| false
| 字串		'sm'

決定對話框的最大寬度。對話框寬度會隨著螢幕尺寸而成長。設定為 false 以停用 maxWidth。

onClosefunc-

當元件要求關閉時觸發的回呼。

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

用於渲染對話框主體的元件。

PaperPropsobject{}

套用至 Paper 元素的屬性。

scroll'body'
| 'paper'		'paper'

決定對話框捲動的容器。

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

用於每個插槽內部的屬性。

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

用於每個插槽內部的元件。

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

允許定義系統覆寫以及其他 CSS 樣式的系統屬性。

請參閱 `sx` 頁面 以取得更多詳細資訊。

TransitionComponentelementTypeFade

用於轉場效果的元件。請遵循此指南以深入了解此元件的需求。

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

轉場效果的持續時間，以毫秒為單位。您可以為所有轉場效果指定單一逾時，或使用物件個別指定。

TransitionPropsobject-

套用至轉場效果元素的屬性。預設情況下，此元素是以 Transition 元件為基礎。

ref 會轉發到根元素。

繼承

雖然上面未明確記錄，但 Modal 元件的屬性也適用於 Dialog。您可以利用這一點來鎖定巢狀元件。

主題預設屬性

您可以使用 MuiDialog 透過主題變更此元件的預設屬性。

插槽

插槽名稱類別名稱預設元件描述
transitionCollapse渲染轉場效果的元件。請遵循此指南以深入了解此元件的需求。
paper.MuiDialog-paperPaper渲染紙張的元件。
container.MuiDialog-container渲染容器的元件。
backdrop渲染背景幕的元件。
root.MuiDialog-root渲染根元素的元件。

CSS 類別

這些類別名稱對於使用 CSS 設定樣式很有用。它們在觸發特定狀態時應用於元件的插槽。

類別名稱規則名稱描述
.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"，則套用至容器元素的樣式。

您可以使用以下其中一種客製化選項來覆寫元件的樣式

原始碼

如果您在此頁面中找不到資訊，請考慮查看元件的實作以取得更多詳細資訊。