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');
    }
}

在搜索时，用户现在可以输入 "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

cswni / spotlight

维护者

详情