确认对话框

最后更新：2026-10-17 10:55:29

查看 WordPress Storybook 以获取更详细、交互式的文档。

ConfirmDialog 基于 Modal 构建
并显示一个确认对话框，包含 confirm 和 cancel 按钮。

点击 confirm 按钮或按 Enter 键可确认对话框。
点击 cancel 按钮、按 ESC 键或
点击对话框焦点外部（即遮罩层）可取消（关闭）对话框。

ConfirmDialog 有两种主要模式：受控模式和不受控模式。

不受控模式

允许组件独立使用，只需将其声明为另一个 React
组件渲染方法的一部分即可：

挂载时它将自动打开（显示）。
点击 cancel 按钮、按 ESC
键或点击对话框焦点外部（即遮罩层）时，它将自动关闭。
onCancel 不是必需的，但可以传递。即使传递了，对话框仍可以
自行关闭。

启用此模式只需省略 isOpen 属性即可。在这种情况下，唯一的必需属性
是 onConfirm 回调函数。消息作为 children 传递。

import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';

function Example() {
    return (
        <ConfirmDialog onConfirm={ () => console.debug( 'Confirmed!' ) }>
            Are you sure? <strong>This action cannot be undone!</strong>
        </ConfirmDialog>
    );
}

受控模式

让父组件控制对话框的打开/关闭状态。当向 isOpen 传递
布尔值时激活：

它不会自动关闭。你需要通过
更新 isOpen 属性的值来告知它在何时打开/关闭。
在此模式下，onConfirm 和 onCancel 回调函数都是必需的属性。
你可能希望从 onCancel 和
onConfirm 回调函数中更新控制 isOpen 的状态。

import { useState } from '@wordpress/element';
import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';

function Example() {
    const [ isOpen, setIsOpen ] = useState( true );

    const handleConfirm = () => {
        console.debug( 'Confirmed!' );
        setIsOpen( false );
    };

    const handleCancel = () => {
        console.debug( 'Cancelled!' );
        setIsOpen( false );
    };

    return (
        <ConfirmDialog
            isOpen={ isOpen }
            onConfirm={ handleConfirm }
            onCancel={ handleCancel }
        >
            Are you sure? <strong>This action cannot be undone!</strong>
        </ConfirmDialog>
    );
}

Props

__experimentalHideHeader

Type: boolean
Required: No
Default: true

是否隐藏底层 Modal 的标题，包括 title。

children

Type: ReactNode
Required: Yes

对话框的实际消息内容。它作为子节点传递，并接受任何有效的 ReactNode。

confirmButtonText

Type: string
Required: No

可选的自定义文本，用作确认按钮的标签。

cancelButtonText

Type: string
Required: No

可选的自定义文本，用作取消按钮的标签。

isOpen

Type: boolean
Required: No

定义对话框是打开（显示）还是关闭（未渲染/显示）。
如果设置了该属性，则隐式切换为受控模式；如果没有设置，则为不受控模式。

isBusy

Type: boolean
Required: No

指示在执行操作时的活动状态。
当 true 时，确认按钮将显示忙碌状态。
两个按钮都将被禁用。

onConfirm

Type: (event: DialogInputEvent) => void
Required: Yes

用户确认时调用的回调函数。
当点击 OK 按钮或按下 Enter 键时会发生确认。

onCancel

Type: ((event: DialogInputEvent) => void)
Required: No

用户取消时调用的回调函数。取消可能发生在
点击 Cancel 按钮、按下 ESC 键或
检测到点击对话框焦点外部时（即在遮罩层上）。

如果未设置 isOpen（不受控模式），则不需要此回调，因为组件
会自行处理关闭，但如果取消时需要执行某些操作，你仍然可以传递回调函数（在这种情况下，组件仍会自行关闭）。

如果设置了 isOpen（受控模式），则是必需的，并且你需要在回调函数中将
定义 isOpen 的状态设置为 false，以便在用户取消时关闭对话框。

size

Type: "small" | "fill" | "medium" | "large"
Required: No

底层 Modal 的大小。参见 Modal 的 size 属性。

title

Type: string
Required: No

底层 Modal 的标题：其无障碍名称，以及
可见标题，除非 __experimentalHideHeader 为 true。