模拟一个模态对话框，该对话框响应用户操作在主页面内容上方出现。

工作描述

模态窗口出现在页面顶部，使页面变暗。这有助于将用户的注意力集中在特定操作上，而不会失去整体上下文。需要注意的是，模态窗口不应用于大型表单。

使用时机

模态窗口最适合用于仅在某些情况下需要的次要内容。这些内容可能包括设置、新建文档、填写小型表单。例如，点击链接可能会打开一个模态窗口以输入地址。

使用方法

可以通过调用静态方法使用简短语法来实现模态窗口，这样就无需创建单独的类。以下示例演示如何创建模态窗口：

use Orchid\Support\Facades\Layout;
use Orchid\Screen\Actions\ModalToggle;
use Orchid\Support\Facades\Toast;

/**
 * 按钮命令。
 *
 * @return \Orchid\Screen\Action[]
 */
public function commandBar(): array
{
    return [
        ModalToggle::make('启动演示模态')
            ->modal('exampleModal')
            ->method('action')
            ->icon('full-screen'),
    ];
}

/**
 * 视图。
 *
 * @return string[]|\Orchid\Screen\Layout[]
 */
public function layout(): array
{
    return [
        Layout::modal('exampleModal', [
            Layout::rows([]),
        ]),
    ];
}

/**
 * 提交模态窗口表单时将发生的操作
 */
public function action(): void
{
    Toast::info('你好，世界！这是一个提示消息。');
}

需要注意的是，在添加模态窗口时，应将其添加到 layout() 方法返回的数组的顶层。它不应添加到其他布局（如 Tabs）内部。

标题

要设置模态窗口的标题，可以使用 title 方法：

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->title('窗口标题');

窗口大小

根据窗口的内容，可能需要调整其大小。这可以通过指定 size 方法来完成：

use Orchid\Screen\Layouts\Modal;

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->size(Modal::SIZE_LG);

按钮名称

模态窗口有两个操作：

• 颜色按钮 – 默认操作，保存已完成的工作或确认之前调用的命令。
• 取消按钮 – 关闭窗口而不保存输入的数据。

您可以为它们设置自己的名称：

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->applyButton('发送')
    ->closeButton('关闭');

禁用按钮

要禁用每个按钮有其自己的方法：

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->withoutApplyButton()
    ->withoutCloseButton();

位置

模态窗口不仅可以显示在屏幕中央，还可以显示在右侧：

use Orchid\Screen\Layouts\Modal;

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->type(Modal::TYPE_RIGHT);

打开

有时您可能需要在页面显示后立即打开模态窗口。为此，您可以使用 ->open 方法：

use Orchid\Screen\Layouts\Modal;

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->open();

延迟数据加载

在处理数据集时，无需为每个值创建模态窗口。相反，您可以使用延迟加载。这将在打开窗口时替换 query 屏幕数据并显示新内容。

为了声明模态窗口为异步，您必须调用 deferred 方法，并在参数中传递应替代 query 的方法名称：

Layout::modal('deferredModal', Layout::rows([
    Input::make('welcome')
]))->deferred('loadDataOnOpen'),

以下是延迟加载方法的示例：

/**
 * 此方法用于获取数据，并在模态打开时更新模态内容，而无需完全重新加载页面。
 */
public function loadDataOnOpen(string $welcome): array
{
    return [
        'welcome' => $welcome,
    ];
}

在触发模态窗口时，您可以直接传递值：

use Orchid\Screen\Actions\ModalToggle;

ModalToggle::make('打开模态')
    ->method('methodForSubmitModal')
    ->modalTitle('可自定义标题')
    ->modal('deferredModal', [
        'welcome' => '你好，世界！',
    ]),

禁用响应处理

默认情况下，窗口操作的结果将显示给用户，但如果您需要执行复杂处理或下载文件，这种方法可能不适用。要禁用响应处理，您需要添加对 rawClick 方法的调用：

Layout::modal('exampleModals', [
    Layout::rows([]),
])
    ->rawClick();