介绍

欢迎来到这个使用 Orchid 构建应用程序的教程！管理面板和业务应用程序对于许多 Web 应用程序来说都很重要，因为它们允许管理内容、用户和其他数据。

在本教程中，我们将创建一个简单的任务列表应用程序，以演示 Orchid 的一些功能。这个任务列表允许我们跟踪所有需要完成的任务，就像传统的“待办事项列表”。

在开始本教程之前，请确保您已经安装了框架和包，并启动了 Web 服务器。让我们开始吧！

为了最大化您的学习效果，我们建议您自己输入代码，而不是复制粘贴。这种方法有助于加深您的理解和记忆。

准备数据库

数据库迁移

首先，让我们使用迁移来定义一个数据库表以保存我们所有的任务。

php artisan make:migration create_tasks_table --create=tasks

让我们编辑此文件，并为任务的 name 添加一个额外的字符串列，以及为 active 添加一个布尔列：

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * 运行迁移。
     *
     * @return void
     */
    public function up()
    {
        Schema::create('tasks', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->boolean('active')->default(1);
            $table->timestamps();
        });
    }

    /**
     * 逆转迁移。
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('tasks');
    }
};

要运行我们的迁移，我们将使用 migrate Artisan 命令。

php artisan migrate

Eloquent 模型

因此，让我们定义一个与我们刚刚创建的 tasks 数据库表对应的 Task 模型。

php artisan make:model Task

在 app/Models 目录中，将创建一个新的文件 Task.php，我们将描述可供填写的字段：

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Orchid\Screen\AsSource;

class Task extends Model
{
    use HasFactory, AsSource;
}

注意。 模型具有 AsSource trait，以便通过点符号方便地处理。

屏幕

现在我们已经完成了基本设置，是时候在应用程序中添加我们的第一个屏幕了。Orchid 中的屏幕类似于控制器，但它具有用于定义单个页面的数据和事件的预定义结构。屏幕的结构使我们能够轻松定义页面的布局和行为，并有助于保持代码的组织和可维护性。

要创建一个新的屏幕，请使用 orchid:screen 命令。这将生成一个新的屏幕类，其中包含定义页面数据和事件所需的代码。然后，您可以使用此类来渲染页面并处理用户交互。

php artisan orchid:screen TaskScreen

将在 app/Orchid/Screens 目录中创建一个新的文件 TaskScreen.php：

namespace App\Orchid\Screens;

use Orchid\Screen\Screen;

class TaskScreen extends Screen
{
    /**
     * 定义所有屏幕输入数据的方法
     * 应在其中调用数据库查询，
     * API 或其他任何（不一定显式），
     * 其结果应为数组，
     * 其键将被使用。
     */
    public function query(): array
    {
        return [];
    }

    /**
     * 名称显示在用户屏幕和标题中
     */
    public function name(): ?string
    {
        return "TaskScreen";
    }

    /**
     * 在用户屏幕上显示描述
     * 直接在标题下方。
     */
    public function description(): ?string
    {
        return "TaskScreen";
    }
    
    /**
     * 确定控制按钮和事件。
     * 按下时将发生的事件
     */
    public function commandBar(): array
    {
        return [];
    }

    /**
     * 映射集
     * 行、表、图表、
     * 模态窗口及其组合
     */
    public function layout(): array
    {
        return [];
    }
}

路由

就像控制器一样，Orchid 中的屏幕需要在路由文件中注册，以便用户可以访问。要注册屏幕，我们需要打开管理面板的路由文件（通常是 routes/platform.php），并为屏幕定义一个新路由。

要为屏幕定义新路由，我们可以使用 Orchid 提供的 Screen 方法。此方法需要两个参数：屏幕的 URL 和屏幕的类名。

use App\Orchid\Screens\TaskScreen;

Route::screen('task', TaskScreen::class)->name('platform.task');

现在我们已经为屏幕注册了一个新路由，我们可以通过导航到相应的 URL 在浏览器中访问屏幕。在这种情况下，由于我们将路由注册为 /admin/task，我们可以通过访问 http://your-app.test/admin/task 在浏览器中查看屏幕。

当您第一次访问屏幕时，它可能是空的，因为我们尚未为页面定义任何内容或布局。要用元素填充屏幕，我们需要定义屏幕的数据和事件，并使用它们来渲染页面的内容。

要为我们的屏幕添加名称和描述，我们需要按如下方式更新 name 和 description 方法：

/**
 * 名称显示在用户屏幕和标题中
 */
public function name(): ?string
{
    return '简单待办事项列表';
}

/**
 * 描述显示在用户屏幕的标题下方
 */
public function description(): ?string
{
    return 'Orchid 快速入门';
}

导航

菜单

为了让用户更容易访问我们的屏幕，我们可以在管理面板的导航菜单中添加一个新的菜单项。这将允许用户点击菜单中的链接来访问屏幕，而不必手动在浏览器中输入 URL。

要在导航菜单中添加新的菜单项，我们需要打开 app/Orchid/PlatformProvider.php 文件，并在 menu() 方法中添加一个新的声明。此声明将使用 Orchid 提供的 Menu 方法为我们的屏幕定义一个新的菜单项。

use Orchid\Screen\Actions\Menu;

/**
 * @return Menu[]
 */
public function menu(): array
{
    return [
        // 其他项目...
    
        Menu::make('Tasks')
            ->icon('bag')
            ->route('platform.task')
            ->title('工具')
    ];
}

面包屑

现在我们已经为屏幕添加了一个菜单项，它将显示在导航菜单中，用户可以通过点击菜单项来访问它。除了通过菜单导航到屏幕之外，用户还可以使用面包屑导航到屏幕。

面包屑是一种导航辅助工具，允许用户查看他们在应用程序中的当前位置，并轻松返回到以前的屏幕。它们通常显示为页面顶部的一系列链接，当前屏幕是系列中的最后一个链接。

要为我们的屏幕添加面包屑，我们需要更新 routes/platform.php 文件中的屏幕路由定义。具体来说，我们需要在路由后附加 ->breadcrumbs() 方法：

use App\Orchid\Screens\TaskScreen;
use Tabuna\Breadcrumbs\Trail;
    
Route::screen('task', TaskScreen::class)
    ->name('platform.task')
    ->breadcrumbs(function (Trail $trail){
        return $trail
            ->parent('platform.index')
            ->push('Task');
    });

添加任务

添加窗口模态

要在工作区显示元素，我们需要在屏幕类的 layout 方法中定义它们。layout 方法负责返回一组布局定义，这些定义定义了页面的结构和内容。

要添加带有任务名称输入字段的模态窗口，我们可以按如下方式更新 layout 方法：

use Orchid\Screen\Fields\Input;
use Orchid\Support\Facades\Layout;

/**
 * 屏幕的布局元素。
 *
 * @return \Orchid\Screen\Layout[]|string[]
 */
public function layout(): iterable
{
    return [
        Layout::modal('taskModal', Layout::rows([
            Input::make('task.name')
                ->title('名称')
                ->placeholder('输入任务名称')
                ->help('要创建的任务名称。'),
        ]))
            ->title('创建任务')
            ->applyButton('添加任务'),
    ];
}

这将创建一个标题为“创建任务”的模态窗口。模态将包含一个任务名称的输入字段，标签为“名称”。

启动模态

如果您在浏览器中访问屏幕，您会注意到模态窗口没有显示，即使我们在 layout 方法中定义了它。这是因为模态默认是隐藏的，必须调用才能显示。

要调用模态窗口，我们可以在屏幕上添加一个按钮，当点击时将触发模态。为此，我们可以使用屏幕类的 commandBar 方法，该方法定义了屏幕上可用的基本操作。

要添加一个调用模态窗口的按钮，我们可以按如下方式更新 commandBar 方法：

use Orchid\Screen\Actions\ModalToggle;

/**
 * 屏幕的操作按钮。
 *
 * @return \Orchid\Screen\Action[]
 */
public function commandBar(): iterable
{
    return [
        ModalToggle::make('添加任务')
            ->modal('taskModal')
            ->method('create')
            ->icon('plus'),
    ];
}

这将创建一个标签为“添加任务”的按钮，并带有一个加号图标。当按钮被点击时，它将打开 taskModal 模态窗口，再次点击时，它将关闭模态。

在接下来的部分中，我们将详细介绍如何定义 create 方法并控制按钮的行为。

创建任务

要处理模态窗口表单的提交，我们需要定义一个方法，该方法将在表单发送到服务器时调用。此方法可用于验证表单数据、将新任务保存到数据库以及执行任何其他必要的操作。

要定义在提交表单时调用的方法，我们可以按如下方式更新屏幕类：

use App\Models\Task;
use Illuminate\Http\Request;

/**
 * @param \Illuminate\Http\Request $request
 *
 * @return void
 */
public function create(Request $request)
{
    // 验证表单数据，将任务保存到数据库等。
    $request->validate([
        'task.name' => 'required|max:255',
    ]);

    $task = new Task();
    $task->name = $request->input('task.name');
    $task->save();
}

太好了！我们现在可以成功创建任务。接下来，让我们继续通过构建所有现有任务的列表来完善我们的屏幕。

显示现有任务

query 方法指定应在屏幕上显示哪些数据。此数据可以在方法中收集或生成。数据以数组形式返回，

让我们返回一个简单的示例，键为 tasks：

use App\Models\Task;

/**
 * 获取要在屏幕上显示的数据。
 *
 * @return array
 */
public function query(): iterable
{
    return [
        'tasks' => Task::latest()->get(),
    ];
}

一旦数据传递，我们可以在布局中遍历任务并将它们显示在表格中。

要创建任务列表，我们需要为屏幕定义一个新的布局。此布局将使用表格组件来显示任务列表，并将包括任务名称和操作的列。

要定义任务列表布局，我们可以按如下方式更新屏幕类的 layouts 方法：

use Orchid\Screen\TD;

/**
 * 屏幕的布局元素。
 *
 * @return \Orchid\Screen\Layout[]|string[]
 */
public function layout(): iterable
{
    return [
        Layout::table('tasks', [
            TD::make('name'),
        ]),

        Layout::modal('taskModal', Layout::rows([
            Input::make('task.name')
                ->title('名称')
                ->placeholder('输入任务名称')
                ->help('要创建的任务名称。'),
        ]))
            ->title('创建任务')
            ->applyButton('添加任务'),
    ];
}

第一个参数指向我们在 query 方法中指定的 tasks 键。将传递给表格的就是这个集合。 而第二个参数，我们传递我们想要显示的列的集合。根据指定的属性名称，值将自动设置。

我们的任务应用程序几乎完成了。但是，当任务完成时，我们没有办法删除现有任务。让我们接下来添加这个功能！

删除任务

添加删除按钮

因此，让我们为任务列表中的每一行添加一个删除按钮…

use Orchid\Screen\Actions\Button;

Layout::table('tasks', [
    TD::make('name'),

    TD::make('操作')
        ->alignRight()
        ->render(function (Task $task) {
            return Button::make('删除任务')
                ->confirm('删除后，任务将永远消失。')
                ->method('delete', ['task' => $task->id]);
        }),
]),

删除任务

要删除任务，我们需要在屏幕类中添加一个处理任务删除的方法。此方法可以在点击删除按钮时调用，并可用于从数据库中删除任务：

/**
 * @param Task $task
 *
 * @return void
 */
public function delete(Task $task)
{
    $task->delete();
}

恭喜您完成了本教程！您现在应该对如何为 Orchid 应用程序构建基本屏幕有了很好的理解。更复杂屏幕的开发过程在许多方面将是相似的，因此您应该能够将本教程中学到的概念应用到未来的项目中。

要了解有关 Orchid 屏幕功能的更多信息，我们建议访问文档的屏幕部分。该部分涵盖了与构建和自定义屏幕相关的广泛主题，包括布局自定义、表单处理、数据加载等。

我们希望您觉得本教程有用，并建议您还可以探索以下可用的课程链接。