模態視窗 (Modal)

顯示一個帶有自訂內容的對話框，需要使用者注意或提供額外資訊。

安裝

上面的命令僅適用於個別安裝。如果 @nextui-org/react 已全域安裝，則可以跳過此步驟。

導入

NextUI 匯出 5 個與模態視窗相關的元件

• Modal：顯示模態視窗的主要元件。
• ModalContent：其他模態視窗元件的包裝器。
• ModalHeader：模態視窗的標頭。
• ModalBody：模態視窗的主體。
• ModalFooter：模態視窗的頁尾。

用法

當模態視窗開啟時

• 焦點會被限制在模態視窗內，並設定在第一個可使用 Tab 鍵選取的元素上。
• 模態對話框後面的內容是「惰性的」，表示使用者無法與其互動。

尺寸

不可關閉

預設情況下，可以透過點擊覆蓋層或按下 Esc 鍵來關閉模態視窗。您可以透過設定以下屬性來停用此行為

• 將 isDismissable 屬性設定為 false，以防止在點擊覆蓋層時關閉模態視窗。
• 將 isKeyboardDismissDisabled 屬性設定為 true，以防止在按下 Esc 鍵時關閉模態視窗。

模態框位置

預設情況下，模態框在螢幕高度大於 sm 時會置中顯示，在行動裝置上則會位於螢幕的 底部。這種位置稱為 auto，您可以使用 placement 屬性來更改它。

注意：top-center 和 bottom-center 位置表示模態框在行動裝置上會定位在螢幕的頂部/底部，在桌上型電腦上則會定位在螢幕的中心。

溢出滾動

您可以使用 scrollBehavior 屬性來設定模態框的滾動行為。

• inside：模態框的內容將可以滾動。
• outside：模態框的內容將可以滾動，並且模態框將會固定不動。

使用表單

Modal 會處理模態框內容內的焦點。這表示您可以毫無問題地在模態框中使用表單元素。當模態框關閉時，焦點會回到觸發器。

注意：您可以將 autoFocus 屬性新增到第一個 Input 元件，以便在模態框開啟時將焦點放在該元件上。

背景幕

Modal 元件有一個 backdrop 屬性，可在模態框後方顯示背景幕。背景幕可以是 transparent、opaque 或 blur。預設值為 opaque。

自訂背景幕

您可以使用 backdrop 插槽來自訂背景幕。

自訂動畫

Modal 提供 motionProps 屬性來自訂 enter / exit 動畫。

在此處深入瞭解 Framer 動畫變體 here。

可拖曳

嘗試拖曳標頭部分。

可拖曳溢出

將溢出設定為 true 可以將溢出拖曳到視窗外。

插槽

• wrapper：模態框的包裝器插槽。它會包住 base 和 backdrop 插槽。
• base：模態框內容的主要插槽。
• backdrop：背景幕插槽，它會顯示在模態框後方。
• header：模態框的標頭，它會顯示在模態框的頂部。
• body：模態框的主體，它會顯示在模態框的中間。
• footer：模態框的頁尾，它會顯示在模態框的底部。
• closeButton：模態框的關閉按鈕。

自訂樣式

您可以將自訂的 Tailwind CSS 類別傳遞到元件插槽來自訂 Modal 元件。

資料屬性

Modal 在 base 元素上具有以下屬性

• data-open: 當模態視窗開啟時。基於模態視窗的狀態。
• data-dismissable: 當模態視窗可關閉時。基於 isDismissable 屬性。

無障礙功能

• 當模態視窗開啟時，輔助技術會隱藏模態視窗以外的內容。
• 模態視窗可以在與外部互動或按下 Esc 鍵時選擇性地關閉。
• 焦點會在模態視窗掛載時移入模態視窗，並在卸載時恢復到觸發元素。
• 當開啟時，焦點會被限制在模態視窗內，防止使用者將焦點移到視窗外。
• 當模態視窗開啟時，會阻止模態視窗後方的頁面滾動，包括行動瀏覽器。

API

模態視窗屬性

模態視窗事件

模態視窗類型

動態屬性