bangsystems/livewire-select

Livewire 下拉选择组件(BANG Systems 使用 asantibanez/livewire-select 的分支)

v3.0.0 2024-09-22 13:01 UTC

This package is auto-updated.

Last update: 2024-09-22 13:02:52 UTC


README

这是BANG Systems Limited内部使用的分支。为了保持开源精神,我们发布了我们对这个包的所有更改。

以下是原始的readme,自2023年9月14日首次分支以来未做修改,仅作了一些小的调整。

Livewire Select

依赖项和/或可搜索选择输入的Livewire组件

预览

preview

安装

您可以通过composer安装此包

composer require bangsystems/livewire-select

要求

此包在底层使用 livewire/livewire (https://laravel-livewire.com/)。

它还使用TailwindCSS (https://tailwind.org.cn/)进行基本样式。

请在使用此组件之前确保包含这两个依赖项。

用法

为了使用此组件,您必须创建一个新的从 LivewireSelect 扩展的Livewire组件

您可以使用 make:livewire 命令创建一个新的组件。例如。

php artisan make:livewire CarModelSelect

CarModelSelect 类中,不要从基本Livewire Component 类扩展,而是从 LivewireSelect 类扩展。同时,删除 render 方法。您将拥有一个类似于以下代码片段的类。

class CarModelSelect extends LivewireSelect
{
    //
}

在这个类中,您必须重写以下方法来为您的选择输入提供选项

public function options($searchTerm = null) : Collection 
{
    //
}

options() 必须返回一个具有至少以下键的键值数组项的集合:valuedescription。例如

public function options($searchTerm = null) : Collection 
{
    return collect([
        [
            'value' => 'honda',
            'description' => 'Honda',
        ],
        [
            'value' => 'mazda',
            'description' => 'Mazda',
        ],
        [
            'value' => 'tesla',
            'description' => 'Tesla',
        ],       
    ]);
}

要在一个视图中渲染此组件,只需使用Livewire标签或包含语法即可

<livewire:car-brand-select
   name="car_brand_id"
   :value="$initialValue" // optional
   placeholder="Choose a Car Brand" // optional
/>

您将在屏幕上看到一个带有您定义的值的自定义样式的选择输入

preview

这里没有什么特别的。现在,让我们使另一个选择输入依赖于其值。

按照上述相同的过程创建另一个组件。在这种情况下,我们将创建一个具有以下 options() 方法的 CarModelSelect

// In CarModelSelect component
public function options($searchTerm = null) : Collection 
{
    $modelsByBrand = [
        'tesla' => [
            ['value' => 'Model S', 'description' => 'Model S'],
            ['value' => 'Model 3', 'description' => 'Model 3'],
            ['value' => 'Model X', 'description' => 'Model X'],
        ],
        'honda' => [
            ['value' => 'CRV', 'description' => 'CRV'],
            ['value' => 'Pilot', 'description' => 'Pilot'],
        ],
        'mazda' => [
            ['value' => 'CX-3', 'description' => 'CX-3'],
            ['value' => 'CX-5', 'description' => 'CX-5'],
            ['value' => 'CX-9', 'description' => 'CX-9'],
        ],
    ];

    $carBrandId = $this->getDependingValue('car_brand_id');

    if ($this->hasDependency('car_brand_id') && $carBrandId != null) {
        return collect(data_get($modelsByBrand, $carBrandId, []));
    }

    return collect([
        ['value' => 'Model S', 'description' => 'Tesla - Model S'],
        ['value' => 'Model 3', 'description' => 'Tesla - Model 3'],
        ['value' => 'Model X', 'description' => 'Tesla - Model X'],
        ['value' => 'CRV', 'description' => 'Honda - CRV'],
        ['value' => 'Pilot', 'description' => 'Honda - Pilot'],
        ['value' => 'CX-3', 'description' => 'Mazda - CX-3'],
        ['value' => 'CX-5', 'description' => 'Mazda - CX-5'],
        ['value' => 'CX-9', 'description' => 'Mazda - CX-9'],
    ]);
} 

并在视图中定义它如下

<livewire:car-model-select
    name="car_model_id"
    placeholder="Choose a Car Model"
    :depends-on="['car_brand_id']"
/>

通过这两个片段,我们已定义了一个选择输入,它依赖于另一个名为 car_brand_id 的选择输入。通过这种定义,我们告诉我们的组件监听 car_brand_id 输入的任何更新并通知更改。

preview

注意在 options() 方法中使用另外两个辅助方法:getDependingValuehasDependency

getDependingValue('token') 将返回另一个字段的值,在这种情况下是 car_brand_id。如果 car_brand_id 没有值,则它将返回 null

hasDependency('token') 允许我们检查我们的组件是否被指定依赖于其他组件的值。这允许我们通过检查布局中是否指定了依赖项来重用组件。

例如,如果我们定义了没有 :depends-on 属性的相同组件,我们可以使用该组件并返回所有汽车型号。

<livewire:car-model-select
    name="car_model_id"
    placeholder="Choose a Car Model"
/>

它应该看起来像这样

preview

可搜索输入

您可以在组件上定义 searchable 属性来更改输入的行为。使用 :searchable="true",您的组件将更改其行为,以允许搜索 options() 方法返回的选项。

<livewire:car-model-select
   name="car_model_id"
   placeholder="Choose a Car Model"
   :searchable="true"
/>

您的输入将看起来像这样

preview

要过滤下拉菜单中的选项,您可以在 options() 方法中使用 $searchTerm 参数。

自定义UI

// TODO 😬

高级行为

// TODO 😬

AlpineJs 支持

为箭头键导航添加 AlpineJs,使用回车键进行选择,使用回车/空格键进行重置。😎

测试

composer test

变更日志

请参阅变更日志以获取更多关于最近更改的信息。

贡献

请参阅贡献指南以获取详细信息。

安全性

如果您发现任何与安全相关的问题,请通过电子邮件santibanez.andres@gmail.com联系,而不是使用问题跟踪器。

鸣谢

许可证

MIT许可证(MIT)。请参阅许可证文件以获取更多信息。