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（仅在使用 Livewire v2 时）

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 或 dispatch 辅助函数。

// Livewire v2
$this->dispatchBrowserEvent('toggle-spotlight');

// Livewire v3
$this->dispatch('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');
    }
}

现在，在搜索时，用户可以输入 "credit card"，并将显示 "查看账单设置" 命令的搜索结果。

如何定义命令依赖项

在某些情况下，您的命令可能需要依赖项。假设我们想要创建一个新用户并将其添加到特定的团队。在这种情况下，我们需要定义一个团队依赖项。要定义任何依赖项，请向您的命令添加一个新的方法并命名为 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可以访问用户选择的Team。这允许进行范围依赖项搜索。

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, Team $team)
    {
        // Given Foobar is the second dependency it will have access to any resolved depedencies defined earlier. In this case we can access the Team 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。要发布配置，请运行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/wire-elements/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许可协议授权。

patimio66 / spotlight

维护者

详细信息