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 许可下授权。MIT 许可协议。

线元素 / 聚光灯

维护者

详细信息