useDialogs API

useDialogs hook 的 API 參考資料。

Import

import useDialogs from '@toolpad/core/useDialogs';
// or
import { useDialogs } from '@toolpad/core';

閱讀此指南，瞭解差異，關於最小化 bundle size。

Usage

透過調用 hook 來存取 dialogs API。

const dialogs = useDialogs();

Reference

`dialogs.alert`

開啟警示對話框，返回一個 Promise，在使用者關閉對話框時解析。

await dialogs.alert('Something went wrong', {
  title: 'Attention!',
});

簽章

function alert(message, options?)

參數

message: React.ReactNode 要在警示對話框中顯示的訊息。
options?: object 警示對話框的額外配置。
- onClose?: () => Promise<void> 在關閉對話框之前呼叫的函式。只要返回的 Promise 尚未解析，對話框就會保持開啟狀態。如果您想在關閉時執行非同步操作並顯示載入狀態，請使用此選項。
- title?: React.ReactNode 對話框的標題。預設為 'Alert'。
- okText?: React.ReactNode 在「確定」按鈕中顯示的文字。預設為 'Ok'。

Promise<void> 一個 Promise，在使用者關閉對話框後解析。

`dialogs.confirm`

開啟確認對話框。返回一個 Promise，如果使用者確認則解析為 true，如果使用者取消則解析為 false。

const confirmed = await dialogs.confirm('Are you sure?', {
  okText: 'Yes',
  cancelText: 'No',
});

簽章

function confirm(message, options?)

參數

message: React.ReactNode 要在確認對話框中顯示的訊息。
options?: object 確認對話框的額外配置。
- onClose?: (result: boolean) => Promise<void> 在關閉對話框之前呼叫的函式。只要返回的 Promise 尚未解析，對話框就會保持開啟狀態。如果您想在關閉時執行非同步操作並顯示載入狀態，請使用此選項。
- title?: React.ReactNode 對話框的標題。預設為 'Confirm'。
- okText?: React.ReactNode 在「確定」按鈕中顯示的文字。預設為 'Ok'。
- severity?: 'error' | 'info' | 'success' | 'warning' 表示對話框的用途。這會影響「確定」按鈕的顏色。預設為 undefined。
- cancelText?: React.ReactNode 在「取消」按鈕中顯示的文字。預設為 'Cancel'。

Promise<boolean> 一個 Promise，如果使用者確認則解析為 true，如果使用者取消則解析為 false。

`dialogs.prompt`

開啟提示對話框以請求使用者輸入。返回一個 Promise，如果使用者確認則解析為輸入值，如果使用者取消則解析為 null。

const input = await dialogs.prompt('What is your name?', {
  cancelText: 'Leave me alone',
});

簽章

function prompt(message, options?)

參數

message: React.ReactNode 要在提示對話框中顯示的訊息。
options?: object 提示對話框的額外配置。
- onClose?: (result: string) => Promise<void> 在關閉對話框之前呼叫的函式。只要返回的 Promise 尚未解析，對話框就會保持開啟狀態。如果您想在關閉時執行非同步操作並顯示載入狀態，請使用此選項。
- title?: React.ReactNode 對話框的標題。預設為 'Prompt'。
- okText?: React.ReactNode 在「確定」按鈕中顯示的文字。預設為 'Ok'。
- cancelText?: React.ReactNode 在「取消」按鈕中顯示的文字。預設為 'Cancel'。

Promise<string> 一個 Promise，如果使用者確認則解析為使用者輸入值，如果使用者取消則解析為 null。

`dialogs.open`

開啟自訂對話框。此對話框是一個 React 組件，可選擇性地接收 payload，並在其 onClose 屬性中選擇性地返回結果。

function MyDialog({ open, onClose, payload }) {
  // ...
}

const result = await dialogs.open(MyDialog, 123, {
  onClose: async (result) => callApi(result),
});

簽章

function open(component, payload, options?)

參數

component: React.ComponentType<{ open: boolean, onClose: (result: R) => Promise<void>, payload: P }> 要顯示的對話框組件。
payload?: P 傳遞給對話框的可選 payload。如果您想參數化對話框，或使用實例特定資料，這會很有用。此值在對話框的生命週期內將保持不變。
options?: object 對話框的額外配置。
- onClose?: (result: R) => Promise<void> 在關閉對話框之前呼叫的函式。只要返回的 Promise 尚未解析，對話框就會保持開啟狀態。如果您想在關閉時執行非同步操作並顯示載入狀態，請使用此選項。

Promise<R> 一個 Promise，在對話框關閉時解析為對話框的結果。

`dialogs.close`

以程式方式關閉先前使用 dialogs.open 開啟的對話框。如果對話框返回結果，則 close 也必須使用結果呼叫。原始對話框 Promise 將會使用此結果解析。此 Promise 也會從 close 函式返回。

const myDialog = dialogs.open(/* ... */);

// ...

const result = await dialogs.close(myDialog, 123);

簽章

function close(dialog, result)

參數

dialog: Promise<R> 要關閉的對話框。這應該是先前由 dialogs.open 返回的 Promise。
result?: R 要從對話框返回的結果。

Promise<R> 一個 Promise，在對話框完全關閉時解析為對話框結果。