對話框

對話框會告知使用者關於某項任務，並且可以包含重要資訊、需要決策或涉及多個任務。

Dialog 是一種模態視窗類型，會出現在應用程式內容前方，以提供重要資訊或要求做出決策。當對話框出現時，會停用所有應用程式功能，並保持在螢幕上，直到確認、關閉或採取必要的動作。

對話框刻意具有干擾性，因此應謹慎使用。

簡介

對話框是使用相關元件的集合來實作

Dialog：父元件，用於渲染模態視窗。
Dialog Title：用於對話框標題的包裝器。
Dialog Actions：對話框按鈕的可選容器。
Dialog Content：用於顯示對話框內容的可選容器。
Dialog Content Text：<DialogContent /> 內文字的包裝器。
Slide：可選的 Transition，用於使對話框從螢幕邊緣滑入。

已選取user02@gmail.com

<Typography variant="subtitle1" component="div">
  Selected: {selectedValue}
</Typography>
<br />
<Button variant="outlined" onClick={handleClickOpen}>
  Open simple dialog
</Button>
<SimpleDialog
  selectedValue={selectedValue}
  open={open}
  onClose={handleClose}
/>

<Typography variant="subtitle1" component="div">
  Selected: {selectedValue}
</Typography>
<br />
<Button variant="outlined" onClick={handleClickOpen}>
  Open simple dialog
</Button>
<SimpleDialog
  selectedValue={selectedValue}
  open={open}
  onClose={handleClose}
/>

按下 Enter 開始編輯

基本用法

import Dialog from '@mui/material/Dialog';
import DialogTitle from '@mui/material/DialogTitle';

警示

警示是緊急的中斷，需要確認，以告知使用者有關情況。

大多數警示不需要標題。它們用一到兩句話總結一個決定，透過以下方式：

提出問題（例如「刪除此對話？」）
做出與動作按鈕相關的陳述

僅在高風險情況下使用標題列警示，例如可能失去連線能力。使用者應該能夠僅根據標題和按鈕文字來理解選項。

如果需要標題

使用清晰的問題或陳述，並在內容區域中提供說明，例如「清除 USB 儲存裝置？」。
避免道歉、含糊不清或問題，例如「警告！」或「您確定嗎？」

轉場效果

您也可以替換轉場效果，下一個範例使用 Slide。

表單對話框

表單對話框允許使用者在對話框內填寫表單欄位。例如，如果您的網站提示潛在訂閱者填寫他們的電子郵件地址，他們可以填寫電子郵件欄位並點擊「提交」。

自訂

以下是自訂元件的範例。您可以在覆寫文件頁面中了解更多相關資訊。

對話框新增了一個關閉按鈕，以幫助提升可用性。

全螢幕對話框

可選尺寸

您可以透過結合使用 maxWidth 列舉和 fullWidth 布林值來設定對話框的最大寬度。當 fullWidth 屬性為 true 時，對話框將根據 maxWidth 值進行調整。

響應式全螢幕

您可以使用 useMediaQuery 使對話框具有響應式全螢幕。

import useMediaQuery from '@mui/material/useMediaQuery';

function MyComponent() {
  const theme = useTheme();
  const fullScreen = useMediaQuery(theme.breakpoints.down('md'));

  return <Dialog fullScreen={fullScreen} />;
}

確認對話框

確認對話框要求使用者在選項提交之前明確確認他們的選擇。例如，使用者可以收聽多個鈴聲，但只有在點擊「確定」後才能做出最終選擇。

在確認對話框中點擊「取消」，會取消動作、捨棄任何變更並關閉對話框。

中斷

手機鈴聲

Dione

預設通知鈴聲

Tethys

對話框也可以是非模態的，這表示它們不會中斷使用者在後台的互動。請造訪 Nielsen Norman Group 文章，以取得有關模態與非模態對話框用法的更深入指南。

下面的示範展示了持久性 Cookie 橫幅，這是一種常見的非模態對話框用例。

可拖曳對話框

您可以使用 react-draggable 建立可拖曳的對話框。若要執行此操作，您可以將匯入的 Draggable 元件作為 Dialog 元件的 PaperComponent 傳遞。這會使整個對話框都可拖曳。

滾動長內容

當對話框對於使用者的視窗或裝置來說太長時，它們會滾動。

scroll=paper 對話框的內容會在紙張元素內滾動。
scroll=body 對話框的內容會在 body 元素內滾動。

試試看下面的示範，看看我們的意思

效能

請遵循模組效能章節。

限制

請遵循模組限制章節。

補充專案

對於更進階的用例，您或許可以利用

material-ui-confirm

npm downloads

套件 material-ui-confirm 提供了用於確認使用者動作的對話框，而無需編寫樣板程式碼。

無障礙功能

請遵循模組無障礙功能章節。

實驗性 API - Toolpad

useDialogs

您可以使用 @toolpad/core 中的 useDialogs() API 命令式地建立和操作對話框。此 Hook 處理：

用於開啟和關閉對話框的狀態管理
將資料傳遞到對話框並從中接收結果
堆疊多個對話框
主題化、異步版本的 window.alert()、window.confirm() 和 window.prompt()

以下範例示範了其中一些功能

const handleDelete = async () => {
  const id = await dialogs.prompt('Enter the ID to delete', {
    okText: 'Delete',
    cancelText: 'Cancel',
  });

  if (id) {
    const deleteConfirmed = await dialogs.confirm(
      `Are you sure you want to delete "${id}"?`,
    );
    if (deleteConfirmed) {
      try {
        setIsDeleting(true);
        await mockApiDelete(id);
        dialogs.alert('Deleted!');
      } catch (error) {
        const message = error instanceof Error ? error.message : 'Unknown error';
        await dialogs.open(MyCustomDialog, { id, error: message });
      } finally {
        setIsDeleting(false);
      }
    }
  }
};

API

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