跳到主要內容
+

彈出視窗

彈出視窗元件讓您可以建立對話方塊、彈出視窗、燈箱和其他元素,這些元素會強制使用者採取行動才能繼續。

簡介

彈出視窗是一個實用元件,可在背景幕前渲染其子元件。這讓您可以建立一個元素,使用者必須與之互動才能繼續在父應用程式中操作。

彈出視窗是一個較低層級的結構,用於以下 Material UI 元件中

元件

import { Modal } from '@mui/base/Modal';

以下範例示範如何建立和設定基本彈出視窗的樣式。點擊開啟彈出視窗以查看其行為方式

自訂

巢狀彈出視窗

以下範例示範如何在另一個彈出視窗內巢狀嵌入一個彈出視窗

轉場效果

您可以使用轉場元件為彈出視窗的開啟和關閉狀態製作動畫,只要該元件符合以下要求即可

  • 是彈出視窗的直接子系
  • 具有 in 屬性—這對應於開啟/關閉狀態
  • 在進入轉場開始時呼叫 onEnter 回呼屬性
  • 在退出轉場完成時呼叫 onExited 回呼屬性

彈出視窗內建支援 react-transition-group

您也可以將 react-spring 與彈出視窗一起使用,但這需要額外的自訂設定

效能

彈出視窗的內容在未開啟時會被卸載。這表示每次開啟時都需要重新掛載。

如果您在彈出視窗內渲染昂貴的元件樹,並且想要最佳化互動回應性,您可以透過啟用 keepMounted 屬性來變更此預設行為。

如果您希望彈出視窗的內容可供搜尋引擎使用(即使在彈出視窗關閉時),您也可以使用 keepMounted 屬性。

以下範例示範如何應用此屬性以保持彈出視窗掛載

與任何效能最佳化一樣,keepMounted 屬性不一定能解決您的所有問題。在實作此屬性之前,請先探索效能中其他可能的瓶頸,您可以在這些瓶頸上做出更顯著的改進。

伺服器端彈出視窗

React 不支援伺服器上的 createPortal() API。

若要顯示在伺服器上渲染的彈出視窗,您需要使用 disablePortal 屬性停用入口網站功能,如下列範例所示

限制

溢位版面配置偏移

彈出視窗在開啟時會停用頁面捲動,方法是在相關的捲動容器上將 overflow: hidden 設定為內嵌樣式,這會隱藏捲軸,進而影響頁面版面配置。為了補償此偏移並避免版面配置偏移,彈出視窗還會在捲動容器上設定 padding 屬性(正常情況下約為 15 像素)。

這可能會在使用 position: fixedposition: sticky 元素的版面配置中產生偏移。您需要在這些元素上新增 .mui-fixed 類別名稱,以便彈出視窗在停用捲動時新增 CSS padding 屬性。

<Box sx={{ position: 'sticky', right: 0, top: 0, left: 0 }} className="mui-fixed">

焦點陷阱

如果焦點嘗試逸出,彈出視窗會將焦點移回元件的主體。

這樣做是為了協助工具目的,但可能會為您的使用者帶來問題。

如果使用者需要與頁面的另一部分互動—例如,在父應用程式中開啟彈出視窗時與聊天機器人視窗互動—您可以使用 disableEnforceFocus 屬性停用預設行為。

Hook

import useModal from '@mui/base/unstable_useModal';

useModal hook 可讓您將彈出視窗的功能應用於完全自訂的元件。它會傳回要放置在自訂元件上的屬性,以及代表元件內部狀態的欄位。

Hook 支援 slot 屬性,但它們支援 自訂屬性

以下範例示範如何使用 useModal hook 建構與上述 元件章節中相同的彈出視窗

按下 Enter 鍵開始編輯

如果您使用 ref 來儲存對根元素的參考,請將其傳遞給 useModalref 參數,如上述範例所示。它將與 hook 內部使用的 ref 合併。

協助工具

請參閱 WAI-ARIA 關於對話方塊(彈出視窗)模式的指南以取得協助工具最佳實務的完整詳細資訊。

  • 所有互動式元素都必須具有可存取的名稱。使用 aria-labelledby="id..." 為您的彈出視窗元件提供可存取的名稱。您也可以使用 aria-describedby="id..." 來提供彈出視窗的描述

    <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 撰寫實務以協助您根據彈出視窗的內容將初始焦點設定在最相關的元素上。