模組API

React Modal 組件的 API 參考文件。了解此匯出模組的 props、CSS 和其他 API。

範例

如需此 React 組件用法的範例和詳細資訊，請造訪組件範例頁面

模組

導入

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

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

Modal 是一個較底層的結構，以下組件會利用它

如果您要建立模組對話框，您可能需要使用 Dialog 組件，而不是直接使用 Modal。

此組件與 react-overlays 有許多概念上的共通之處。

Props

原生組件的 Props 也可用。

名稱	類型	預設值	描述
children*	元素	-	單一子內容元素。這需要能夠持有 ref。
open*	布林值	-	如果為 `true`，則會顯示組件。
BackdropComponent	元素類型	styled(Backdrop, { name: 'MuiModal', slot: 'Backdrop', overridesResolver: (props, styles) => { return styles.backdrop; }, })({ zIndex: -1, })	背景幕組件。此 prop 啟用自訂背景幕渲染。已棄用－請改用 `slots.backdrop`。雖然此 prop 目前仍可運作，但將在下一個主要版本中移除。
BackdropProps	物件	-	應用於 `Backdrop` 元素的 Props。已棄用－請改用 `slotProps.backdrop`。
classes	物件	-	覆寫或擴展應用於組件的樣式。請參閱下方的「CSS 類別 API」以了解更多詳細資訊。
closeAfterTransition	布林值	false	當設定為 true 時，Modal 會等到巢狀 Transition 完成後才關閉。
component	元素類型	-	用於根節點的組件。可以是字串 (用於 HTML 元素) 或組件。
components	{ Backdrop?: elementType, Root?: elementType }	{}	用於每個 slot 內部的組件。已棄用－請改用 `slots` prop。此 prop 將在 v7 版本中移除。請參閱從已棄用的 API 遷移以了解更多詳細資訊。
componentsProps	{ backdrop?: func \| object, root?: func \| object }	{}	slot 組件的額外 props。您可以覆寫現有的 props 或新增 props。已棄用－請改用 `slotProps` prop。此 prop 將在 v7 版本中移除。請參閱從已棄用的 API 遷移以了解更多詳細資訊。
container	HTML 元素 \| func	-	一個 HTML 元素或傳回 HTML 元素的函式。container 將會附加 portal 子元素。您也可以提供回呼函式，該函式會在 React layout effect 中呼叫。這可讓您從 ref 設定 container，並使伺服器端渲染成為可能。預設情況下，它會使用最上層 document 物件的 body，因此大多數情況下它只是 document.body。
disableAutoFocus	布林值	false	如果為 `true`，模組在開啟時不會自動將焦點轉移到自身，並在關閉時將焦點替換回最後一個聚焦的元素。這也適用於任何具有 disableAutoFocus prop 的模組子元素。一般來說，永遠不應將其設定為 `true`，因為這會降低模組對輔助技術 (例如螢幕閱讀器) 的可存取性。
disableEnforceFocus	布林值	false	如果為 `true`，模組在開啟時不會阻止焦點離開模組。一般來說，永遠不應將其設定為 `true`，因為這會降低模組對輔助技術 (例如螢幕閱讀器) 的可存取性。
disableEscapeKeyDown	布林值	false	如果為 `true`，按下 Esc 鍵將不會觸發 onClose 回呼函式。
disablePortal	布林值	false	子元素將位於父組件的 DOM 階層之下。
disableRestoreFocus	布林值	false	如果為 `true`，模組在隱藏或卸載後將不會將焦點還原到先前聚焦的元素。
disableScrollLock	布林值	false	停用捲軸鎖定行為。
hideBackdrop	布林值	false	如果為 `true`，則不會渲染背景幕。
keepMounted	布林值	false	始終將子元素保留在 DOM 中。此 prop 在 SEO 情況下或當您想要最大化 Modal 的響應性時非常有用。
onClose	func	-	當組件請求關閉時觸發的回呼函式。reason 參數可選擇性地用於控制對 onClose 的響應。簽名：`function(event: object, reason: string) => void` `event` 回呼函式的事件來源。 `reason` 可以是：`"escapeKeyDown"`、`"backdropClick"`。
onTransitionEnter	func	-	當 transition 進入時呼叫的函式。
onTransitionExited	func	-	當 transition 結束時呼叫的函式。
slotProps	{ backdrop?: func \| object, root?: func \| object }	{}	用於 Modal 內部每個 slot 的 props。
slots	{ backdrop?: elementType, root?: elementType }	{}	用於 Modal 內部每個 slot 的組件。可以是字串 (用於 HTML 元素) 或組件。
sx	Array<func \| object \| bool> \| func \| object	-	允許定義系統覆寫以及額外 CSS 樣式的系統 prop。請參閱 `sx` 頁面以了解更多詳細資訊。

ref 會轉發到根元素。

Slots

Slot 名稱	類別名稱	預設組件	描述
root	.MuiModal-root	`'div'`	渲染根元素的組件。
backdrop	.MuiModal-backdrop		渲染背景幕的組件。

CSS 類別

這些類別名稱對於使用 CSS 設定樣式很有用。當觸發特定狀態時，它們會應用於組件的 slot。

類別名稱	規則名稱	描述
.MuiModal-hidden	hidden	如果 Modal 已結束，則應用於根元素的類別名稱。

您可以使用以下其中一種自訂選項來覆寫組件的樣式

使用全域類別名稱。
在自訂主題中使用規則名稱作為組件的styleOverrides 屬性的一部分。

原始碼

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