Modal

Modal 元件為建立對話框、彈出視窗、燈箱或其他任何元件提供了穩固的基礎。

此元件會在背景幕元件前方呈現其 children 節點。Modal 提供了重要的功能

💄 當一次一個不夠用時，管理 modal 堆疊。
🔐 建立背景幕，以停用 modal 下方的互動。
🔐 開啟時，它會停用頁面內容的捲動。
♿️ 它正確地管理焦點；移動到 modal 內容，並將焦點保持在那裡直到 modal 關閉。
♿️ 自動新增適當的 ARIA 角色。

如果您要建立 modal 對話框，您可能需要使用 Dialog 元件，而不是直接使用 Modal。Modal 是一個較低層級的建構，以下元件會利用它

<Button onClick={handleOpen}>Open modal</Button>
<Modal
  open={open}
  onClose={handleClose}
  aria-labelledby="modal-modal-title"
  aria-describedby="modal-modal-description"
>
  <Box sx={style}>
    <Typography id="modal-modal-title" variant="h6" component="h2">
      Text in a modal
    </Typography>
    <Typography id="modal-modal-description" sx={{ mt: 2 }}>
      Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
    </Typography>
  </Box>
</Modal>

<Button onClick={handleOpen}>Open modal</Button>
<Modal
  open={open}
  onClose={handleClose}
  aria-labelledby="modal-modal-title"
  aria-describedby="modal-modal-description"
>
  <Box sx={style}>
    <Typography id="modal-modal-title" variant="h6" component="h2">
      Text in a modal
    </Typography>
    <Typography id="modal-modal-description" sx={{ mt: 2 }}>
      Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
    </Typography>
  </Box>
</Modal>

按下 Enter 開始編輯

請注意，您可以使用 outline: 0 CSS 屬性停用外框（通常為藍色或金色）。

Modal 可以巢狀化，例如對話框內的選擇器，但不建議堆疊超過兩個 modal，或任何兩個帶有背景幕的 modal。

<Button onClick={handleOpen}>Open modal</Button>
<Modal
  open={open}
  onClose={handleClose}
  aria-labelledby="parent-modal-title"
  aria-describedby="parent-modal-description"
>
  <Box sx={{ ...style, width: 400 }}>
    <h2 id="parent-modal-title">Text in a modal</h2>
    <p id="parent-modal-description">
      Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
    </p>
    <ChildModal />
  </Box>
</Modal>

<Button onClick={handleOpen}>Open modal</Button>
<Modal
  open={open}
  onClose={handleClose}
  aria-labelledby="parent-modal-title"
  aria-describedby="parent-modal-description"
>
  <Box sx={{ ...style, width: 400 }}>
    <h2 id="parent-modal-title">Text in a modal</h2>
    <p id="parent-modal-description">
      Duis mollis, est non commodo luctus, nisi erat porttitor ligula.
    </p>
    <ChildModal />
  </Box>
</Modal>

按下 Enter 開始編輯

轉場效果

modal 的開啟/關閉狀態可以使用轉場效果元件進行動畫處理。此元件應遵守以下條件

成為 modal 的直接子系。
具有 in 屬性。這對應於開啟/關閉狀態。
當進入轉場開始時，呼叫 onEnter 回呼屬性。
當結束轉場完成時，呼叫 onExited 回呼屬性。這兩個回呼允許 modal 在關閉並完全轉場後卸載子內容。

Modal 內建支援 react-transition-group。

或者，您可以使用 react-spring。

效能

modal 的內容在關閉時會卸載。如果您需要讓內容可供搜尋引擎使用，或在 modal 內部渲染昂貴的元件樹，同時為了最佳化互動回應性，那麼啟用 keepMounted 屬性來變更此預設行為可能是一個好主意

<Modal keepMounted />

與任何效能最佳化一樣，這並非萬靈丹。請務必先找出瓶頸，然後再嘗試這些最佳化策略。

React 不支援伺服器上的 createPortal() API。為了顯示 modal，您需要使用 disablePortal 屬性停用 portal 功能

限制

焦點陷阱

如果焦點嘗試逸出 modal，modal 會將焦點移回元件的主體。

這是為了協助工具目的而做的。但是，這可能會產生問題。如果使用者需要與頁面的另一部分互動，例如與聊天機器人視窗互動，您可以停用此行為

<Modal disableEnforceFocus />

協助工具

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)

請務必將 aria-labelledby="id..."（參考 modal 標題）新增至 Modal。此外，您可以使用 Modal 上的 aria-describedby="id..." 屬性提供 modal 的描述。
```
<Modal aria-labelledby="modal-title" aria-describedby="modal-description">
  <h2 id="modal-title">My Title</h2>
  <p id="modal-description">My Description</p>
</Modal>
```
WAI-ARIA 撰寫實務可以協助您根據您的 modal 內容，將初始焦點設定在最相關的元素上。
請記住，「modal 視窗」會覆蓋在主要視窗或另一個 modal 視窗之上。modal 下方的視窗是惰性的。也就是說，使用者無法與活動 modal 視窗外部的內容互動。這可能會產生衝突的行為。

無樣式

使用 Base UI Modal 完全掌控元件的設計，無需覆寫 Material UI 或 Joy UI 樣式。此元件的無樣式版本是需要高度自訂且套件大小較小的理想選擇。

API

請參閱以下文件，以取得此處提及之元件所有可用屬性和類別的完整參考。

<Modal />

Modal

伺服器端 modal