README

关于 Wire Elements Spotlight

Wire Elements Spotlight 是一个 Livewire 组件，为 Laravel 应用程序提供类似 Spotlight/Alfred 的功能。查看演示视频。

安装

点击上面的图片，阅读有关使用 Wire Elements Spotlight 包的完整文章，或按照以下说明操作。

要开始使用，请通过 Composer 需求包

composer require wire-elements/spotlight

Livewire 指令

添加 Livewire 指令 @livewire('livewire-ui-spotlight')

<html>
<body>
<!-- content -->

@livewire('livewire-ui-spotlight')
</body>
</html>

Alpine

Spotlight 需要 Alpine。您可以使用官方 CDN 快速包含 Alpine

<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>

打开 Spotlight

要打开 Spotlight 输入栏，您可以使用以下快捷键之一

CTRL + K
CMD + K
CTRL + /
CMD + /

您可以在配置文件中自定义键盘快捷键（见下文）。您还可以从任何其他 Livewire 组件或通过 JavaScript 切换 Spotlight。

在任何 Livewire 组件中，您都可以使用 dispatchBrowserEvent 助手。

$this->dispatchBrowserEvent('toggle-spotlight');

您还可以使用 Alpine 的 $dispatch 助手从您的标记中触发相同的浏览器事件。

<button @click="$dispatch('toggle-spotlight')">Toggle Spotlight</button>

创建第一个 Spotlight 命令

您可以通过创建一个新类并使其扩展 LivewireUI\Spotlight\SpotlightCommand 来创建您的第一个 Spotlight 命令。首先为您的命令定义一个 $name 和 $description。名称和描述将在搜索命令时可见。

为了帮助您开始，您可以使用 php artisan make:spotlight <command-name> 命令。

use LivewireUI\Spotlight\SpotlightCommand;

class Logout extends SpotlightCommand
{
    protected string $name = 'Logout';

    protected string $description = 'Logout out of your account';

}

当选择命令且命令没有依赖项时，将调用 execute 方法。让我们以 Logout 命令的 execute 方法为例

use Illuminate\Contracts\Auth\StatefulGuard;
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;

class Logout extends SpotlightCommand
{
    protected string $name = 'Logout';

    protected string $description = 'Logout out of your account';

    public function execute(Spotlight $spotlight, StatefulGuard $guard): void
    {
        $guard->logout();
        $spotlight->redirect('/');
    }
}

如您所见，您可以类型提示您的依赖项，并由 Laravel 解析。如果您类型提示 Spotlight $spotlight，您将能够访问 Livewire Spotlight 组件。这使您能够访问所有 Livewire 助手，例如重定向用户、触发事件等。

如何定义搜索同义词

有时您可能希望在搜索命令时包括额外的搜索词（通常称为同义词）。如果用户用多个名称引用某物或命令可能包含多个功能（例如，一个具有多种设置类型的设置页面），这可能很有用。您可以直接在命令上定义一个 $synonyms 数组来添加您想要的任何同义词

use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;

class ViewBillingSettings extends SpotlightCommand
{
    protected string $name = 'View Billing Settings';

    protected string $description = 'Update your billing settings';

    protected array $synonyms = [
        'subscription',
        'credit card',
        'payment',
    ];

    public function execute(Spotlight $spotlight): void
    {
        $spotlight->redirect('/settings/billing');
    }
}

在搜索时，用户现在可以输入“信用卡”，系统会显示“查看账单设置”命令的搜索结果。

如何定义命令依赖

在某些情况下，您的命令可能需要依赖项。例如，如果我们想创建一个新用户并将其添加到特定的团队中，在这种情况下，我们需要定义一个团队依赖项。要定义任何依赖项，请向您的命令中添加一个新的方法，并将其命名为 dependencies。

您可以使用 SpotlightCommandDependencies::collection() 方法创建一个新的依赖项集合。通过调用 add 方法来注册一个新的依赖项。您可以添加任意数量的依赖项。用户输入提示按照添加命令的顺序排列。

SpotlightCommandDependencies::collection()
    ->add(SpotlightCommandDependency::make('team')->setPlaceholder('For which team do you want to create a user?'))
    ->add(SpotlightCommandDependency::make('foobar')->setPlaceholder('Input from user')->setType(SpotlightCommandDependency::INPUT));

对于每个依赖项，Spotlight 都会检查命令上是否存在 search{dependency-name} 方法。该方法提供了用户给出的搜索查询。例如，要搜索我们的团队依赖项

public function searchTeam($query)
{
    return Team::where('name', 'like', "%$query%")
        ->get()
        ->map(function(Team $team) {
            return new SpotlightSearchResult(
                $team->id,
                $team->name,
                sprintf('Create license for %s', $team->name)
            );
        });
}

Spotlight 期望一个 SpotlightSearchResult 对象的集合。SpotlightSearchResult 对象由结果标识符、名称和描述组成。

每个依赖项都将有权访问已定义的依赖项。因此，在下面的示例中，您可以看到 searchFoobar 可以访问用户选择的“团队”。这允许进行范围依赖项搜索。

use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;
use LivewireUI\Spotlight\SpotlightCommandDependencies;
use LivewireUI\Spotlight\SpotlightCommandDependency;
use LivewireUI\Spotlight\SpotlightSearchResult;

class CreateUser extends SpotlightCommand
{
    protected string $name = 'Create user';

    protected string $description = 'Create new team user';

    public function dependencies(): ?SpotlightCommandDependencies
    {
        return SpotlightCommandDependencies::collection()
            ->add(SpotlightCommandDependency::make('team')->setPlaceholder('For which team do you want to create a user?'))
            ->add(SpotlightCommandDependency::make('foobar')->setPlaceholder('Search for second dependency')
            );
    }

    public function searchFoobar($query, User $user)
    {
        // Given Foobar is the second dependency it will have access to any resolved depedencies defined earlier. In this case we can access the User which was chosen.
    }

    public function searchTeam($query)
    {
        return Team::where('name', 'like', "%$query%")
            ->get()
            ->map(function(Team $team) {
                return new SpotlightSearchResult(
                    $team->id,
                    $team->name,
                    sprintf('Create user for %s', $team->name)
                );
            });
    }

    public function execute(Spotlight $spotlight, Team $team, string $name)
    {
        $spotlight->emit('openModal', 'user-create', ['team' => $team->id, 'name' => $name]);
    }
}

注册命令

您可以通过将这些添加到 livewire-ui-spotlight.php 配置文件中来注册命令

<?php

return [
    'commands' => [
        \App\SpotlightCommands\CreateUser::class
    ]
];

您也可以通过您的一个服务提供程序来注册命令

use \App\SpotlightCommands\CreateUser;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Spotlight::registerCommand(CreateUser::class);

        // You can also register commands conditionally
        Spotlight::registerCommandIf(true, CreateUser::class);
        Spotlight::registerCommandUnless(false, CreateUser::class);
    }

}

或者，您也可以从命令本身有条件地显示或隐藏一个命令。（注意：您仍然需要在配置文件或服务提供程序中注册您的命令。）向您的命令中添加 shouldBeShown 方法，并添加任何逻辑以解决是否显示命令。依赖项从容器中解析，因此您例如可以验证当前认证的用户是否有访问给定命令所需的权限

use Illuminate\Http\Request;
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;

class CreateUser extends SpotlightCommand
{
    protected string $name = 'Create user';

    protected string $description = 'Create new team user';

    public function execute(Spotlight $spotlight)
    {
        $spotlight->emit('openModal', 'user-create');
    }

    public function shouldBeShown(Request $request): bool
    {
        return $request->user()->can('create user');
    }
}

如果您需要执行无法在服务提供程序中执行（例如，任何需要使用当前认证用户的逻辑）以确定您的命令是否应在 Spotlight 组件中显示的逻辑，您可以在您的命令上添加一个 shouldBeShown 方法。您可以类型提示所需的任何依赖项，它们将为您从容器中解析。（注意：您仍然需要在配置文件或服务提供程序中注册您的命令。）

use Illuminate\Http\Request;
use LivewireUI\Spotlight\Spotlight;
use LivewireUI\Spotlight\SpotlightCommand;

class CreateUser extends SpotlightCommand
{
    protected string $name = 'Create user';

    protected string $description = 'Create new team user';

    public function execute(Spotlight $spotlight)
    {
        $spotlight->emit('openModal', 'user-create');
    }

    public function shouldBeShown(Request $request): bool
    {
        return $request->user()->can('create user');
    }
}

配置

您可以通过 livewire-ui-spotlight.php 配置文件来自定义 Spotlight。这包括一些额外的选项，例如，如果您不使用 TailwindCSS 作为您应用程序的 CSS，则包括 CSS。要发布配置，请运行 vendor:publish 命令

php artisan vendor:publish --tag=livewire-ui-spotlight-config

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Shortcuts
    |--------------------------------------------------------------------------
    |
    | Define which shortcuts will activate Spotlight CTRL / CMD + key
    | The default is CTRL/CMD + K or CTRL/CMD + /
    |
    */

    'shortcuts' => [
        'k',
        'slash',
    ],

    /*
    |--------------------------------------------------------------------------
    | Commands
    |--------------------------------------------------------------------------
    |
    | Define which commands you want to make available in Spotlight.
    | Alternatively, you can also register commands in your AppServiceProvider
    | with the Spotlight::registerCommand(Logout::class); method.
    |
    */

    'commands' => [
        \LivewireUI\Spotlight\Commands\Logout::class
    ],

    /*
    |--------------------------------------------------------------------------
    | Include CSS
    |--------------------------------------------------------------------------
    |
    | Spotlight uses TailwindCSS, if you don't use TailwindCSS you will need
    | to set this parameter to true. This includes the modern-normalize css.
    |
    */
    'include_css' => false,

    /*
    |--------------------------------------------------------------------------
    | Include JS
    |--------------------------------------------------------------------------
    |
    | Spotlight will inject the required Javascript in your blade template.
    | If you want to bundle the required Javascript you can set this to false
    | run `npm install --save fuse.js` and add `require('vendor/livewire-ui/spotlight/resources/js/spotlight');`
    | to your script bundler like webpack.
    |
    */
    'include_js' => true,
];

如果您想翻译或更改默认的占位符，您将需要发布翻译文件。

php artisan vendor:publish --tag=livewire-ui-spotlight-translations

<?php

return [
    'placeholder' => 'What do you want to do?',
];

如果您想更改 spotlight 视图，您也可以发布视图。

php artisan vendor:publish --tag=livewire-ui-spotlight-views

致谢

许可证

Wire Elements 是开源软件，许可协议为 MIT 许可协议。

使用观察者管理您的 Laravel Horizon 实例

所有您最喜欢的 Laravel Horizon 功能（以及一些新功能）都打包在一个桌面应用程序中。每个 Laravel 开发者必备的生产力增强器。《点击此处获取 Observer》（https://observer.dev/）

lochness / spotlight

维护者

详细信息