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许可证授权。

dvi / spotlight

维护者

详细信息