README

安装

php artisan module:install morphcms/command-palette-module

通过 Composer

您需要在 composer.json 文件中粘贴仓库路径。

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:morphcms/command-palette-module.git"
        }
    ]
}

然后运行

composer require morphcms/command-palette-module

使用方法

在您的模块服务提供者或 EventServiceProvider 中，您可以注册您的监听器到 CommandSearch 事件。

CommandSearch::class => [
    // Register your listeners here.
],

监听器必须扩展 CollectionSearchListener 或 CommandSearchListener。

对 api 路由 /commands/search 执行命令搜索。

请求参数

'query' => ['required', 'string'],
'limit' => ['sometimes', 'numeric', 'min:1', 'max:100'],
'args' => ['array', 'nullable'],
'args.*' => [],
'options' => ['array', 'nullable'],
'options.*' => [],

返回一个包含 SearchResult 的数组。

{
    "group": [
        {
            "type": "resource-type",
            "meta": []
        }
    ],
    "blog": [
        {
            "type": "posts",
            "title": "My first post",
            "icon": "DocumentText",
            "description": "Some post summary.",
            "group": "blog",
            "meta": []
        }
    ]
}

创建 CollectionSearchListener

CollectionSearchListener 适用于您想通过 'contains' 方法硬编码一个将进行搜索的 SearchResult 列表的情况。

use Modules\CommandPalette\ActionTypes\NavigateAction;
use Modules\CommandPalette\ActionTypes\ToastAction;
use Modules\CommandPalette\DTO\SearchResult;
use Modules\CommandPalette\Enums\CommandIcon;
use Modules\CommandPalette\Listeners\CollectionSearchListener;

class GeneralCommandsSearchListener extends CollectionSearchListener
{
    public function items(): array
    {
        return [
            SearchResult::make('Greet') // The command title that will also be searched
                ->group('Admin') // Just a name to nicely group results
                ->icon(CommandIcon::LightningBolt) // Uses Hero Icons package
                ->description('Says hello back to you.') // A summary of what this command or this result does.
                ->action(ToastAction::make()->message('Hello, '.auth()->user()->name.'!')), // Action is catched on the frontend, this should send a payload
        ];
    }
}

创建 CommandSearchListener

CommandSearchListener 是基类监听器，您必须实现搜索和获取结果的方式。它必须返回一个 集合 的 SearchResult

namespace App\Listeners;

use Illuminate\Support\Collection;
use Modules\Blog\Models\Post;
use Modules\CommandPalette\ActionTypes\NavigateAction;
use Modules\CommandPalette\DTO\SearchResult;
use Modules\CommandPalette\Enums\CommandIcon;
use Modules\CommandPalette\Events\CommandSearch;
use Modules\CommandPalette\Listeners\CommandSearchListener;

class GeneralCommandsSearchListener extends CommandSearchListener
{
    protected function search(CommandSearch $event): Collection|null
    {
        return Model::search($event->query)
            ->limit($event->limit)
            ->get()
            ->map(fn (Model $model) => 
                SearchResult::make(
                    title: $model->title,
                    type: 'resource_name',
                )->group('Resource Name')
                 ->icon(CommandIcon::Sparkles)
                 ->action(NavigateAction::make(['id' => $model->id]))
            );
    }
}

搜索监听器的示例

博客文章示例

namespace App\Listeners\Commands;

use Illuminate\Support\Collection;
use Modules\Blog\Models\Post;
use Modules\Shop\Enums\ProductStatus;

use Modules\CommandPalette\ActionTypes\NavigateAction;
use Modules\CommandPalette\DTO\SearchResult;
use Modules\CommandPalette\Enums\CommandIcon;
use Modules\CommandPalette\Events\CommandSearch;
use Modules\CommandPalette\Listeners\CommandSearchListener;

class BlogCommandsSearchListener extends CommandSearchListener
{
    // This implementation uses Scout for search
    protected function search(CommandSearch $event): Collection|null
    {
        return Post::search($event->query)
            ->query(fn ($q) => $q->where('status', ProductStatus::Published->value))
            ->get()
            ->map(fn (Post $post) => SearchResult::make(
                title: $post->title,
                type: 'post',
            )->group('Blog')
                ->icon(CommandIcon::DocumentText)
                ->action(NavigateAction::make(['slug' => $post->slug]))
            );
    }
}

带授权的自定义命令示例

namespace App\Listeners\Commands;

use Laravel\Nova\Nova;use Modules\CommandPalette\ActionTypes\NavigateAction;
use Modules\CommandPalette\ActionTypes\ToastAction;
use Modules\CommandPalette\DTO\SearchResult;
use Modules\CommandPalette\Enums\CommandIcon;
use Modules\CommandPalette\Listeners\CollectionSearchListener;

class AdminCommandsSearchListener extends CollectionSearchListener
{
    public function authorize(): bool
    {
        return auth()->check() && auth()->user()->is_admin;
    }

    public function items(): array
    {
        return [
            SearchResult::make('Create Product')
                ->group('Admin')
                ->icon(CommandIcon::LightningBolt)
                ->action(
                    NavigateAction::make([
                        'url' => Nova::url('/resources/products/new'),
                ])),
        ];
    }
}

命令操作

CommandAction 类型只是一个具有流畅 API 的数据传输对象。

仅需要两个必需的属性是 type 和 meta。

创建 CustomAction

namespace Modules\CommandPalette\ActionTypes;

use Modules\CommandPalette\DTO\CommandAction;

class MyCommandAction extends CommandAction
{
    public function __construct(array $meta = [])
    {
        parent::__construct('my-type', $meta);
    }
}